Orientation Namespace

Integration Identityorientation · core

Category: core
Namespace: orientation

Return the authenticated principal and a small, constant-size orientation summary at the start of a run, so every later call knows who it is acting as and what the connection is allowed to do.

Integration Capabilitywhoami · read

Access: read
Method: whoami
Side Effect: No

The only method in this namespace. Takes no parameters at all, needs no operationId and no organizationId, and returns one flat object: the principal, the connection's scope ceiling, a membership count, the documentation organization's id and lifecycle status, and the number of comment threads waiting for an agent. It never lists organizations and never explains how anything works.

Limitations

There is exactly one method. orientation.help does not exist, has never existed, and will not be added: guidance questions belong to the separate top-level guide tool, and calling orientation.help fails as an unknown method rather than teaching you anything. whoami also does not enumerate organizations, does not report per-organization permissions, and cannot change identity, switch principals, or elevate scopes. documentationOrganizationId is deployment configuration rather than a validated reference: it is null when the deployment names no documentation organization, and a misconfigured value is returned as-is instead of failing the call, so a non-UUID string is possible and documentationOrganizationLifecycleStatus is null whenever the id is absent, malformed, or unresolvable. organizationCount counts your active, unexpired memberships, not organizations you can currently write to and not organizations in any particular lifecycle state, so it can exceed the number of usable organizations. Failures that are not already presentable are redacted to a generic line, so a whoami error tells you the call failed and not why.

Usage

No operationId, no pagination, no cursor, and no organization argument. Call it with an empty argument object at the start of a run; the answer is constant-size and safe to call again, though there is rarely a reason to call it twice in one session. It makes a few small bounded reads (the membership count, the documentation organization's lifecycle status, and the number of comment threads waiting for an agent, returned as commentsWaitingForAgent), so it is a cheap first call and a good liveness check for a new connection. Treat the returned instructions string as guidance for the opening sequence rather than as a policy document.

Authorization

Any authenticated MCP connection can call whoami; it resolves no organization and checks no organization permission, so it is the one call that always answers for a live principal. authMethod is either api_key or oauth, and the distinction matters downstream: some operations, notably organization creation, are available only to delegated OAuth principals. scopes is the connection's ceiling, typically mcp:read for reads and mcp:write for changes; a scope present here is still subject to the per-organization permission check that every organization-scoped call performs live at call time. userId is the acting Oddlynew user and is the identity that appears in activity logs and document history.

Composition

orientation.whoami is step one of a fixed opening sequence. Step two is organizations.listMine to choose a concrete organization, and organizations.getMyAccess for that organization's live permissions. documentationOrganizationId names the public documentation organization, which is where the guide tool reads from; you can also read documents in it directly through the documents namespace when you want an exact document rather than an answer. Anything shaped like a question about how Oddlynew or an integration works goes to guide, never to this namespace.

Orientation

What it does

The orientation namespace answers one question: who am I, and what is this connection allowed to do. It contains a single method, whoami, and it is the natural first call in any run. The answer is deliberately small and bounded, so it costs almost nothing and never floods a context window.

whoami takes no parameters. Call it as orientation.whoami() or with an empty object; the generated signature is a strict empty-parameters schema, so passing fields is a validation error rather than a filter.

What every field means

userId is the acting Oddlynew user. This is the identity attributed in document history and in the activity log, so when you need to answer "who made this change", it is the id to compare against.

authMethod is api_key or oauth. It tells you whether you are a machine principal or a delegated user session. A few operations are restricted to delegated principals, and some organization permissions are carried by team roles that machine-principal API keys do not hold, so reading this field early explains an authorization failure you would otherwise have to discover by hitting it.

scopes is the array of scopes granted to this connection, the connection's ceiling. Seeing mcp:write here means the connection may attempt writes; it does not mean you may write in any particular organization. Every organization-scoped call authorizes its resolved organization live, against both the scope and the organization permission, at the moment it runs.

organizationCount is the number of active, unexpired memberships you hold. It is a count and nothing more. It does not filter by lifecycle state, so an organization that is quarantined, deleting, or tearing down is still counted, and the count can therefore be larger than the number of organizations you can actually work in. Use it as a signal, for example to notice that a fresh principal belongs to nothing yet, and use organizations.listMine when you need the actual list.

documentationOrganizationId names the public documentation organization for this deployment, and documentationOrganizationLifecycleStatus is its current lifecycle projection, one of active, deleting, quarantining, quarantined, tearing_down, or deleted. Both are null when the deployment configures no documentation organization. The id is deliberately not UUID-validated: it is deployment configuration, and a misconfigured value must not break orientation for everyone, so a malformed value is returned unchanged and its lifecycle status comes back null.

commentsWaitingForAgent counts the open comment threads, across all your organizations, whose turn is an agent's: threads a person addressed to an agent or answered, and threads an agent claimed or left with a progress note. It counts them for any agent, not for you in particular, so read a thread's claimedBy and last message before you take it over. Comments explains how the turn moves.

instructions is a standing orientation paragraph: it names organizations.listMine and the organization's AGENTS.md as the next steps, then the calls for types, documents, Loops and connections, the guide tool, and, when comments are waiting for an agent, how to list them. It is guidance for the opening sequence, not organization policy. Organization policy lives in each organization's AGENTS.md document, which you read after you have chosen an organization.

orientation.help does not exist

This is the single most common wrong call against this namespace, so it is worth stating flatly: there is no orientation.help, there is no orientation.guide, and there is no guidance method of any kind inside run. Public guidance is intentionally absent from the execution namespace. It lives in the separate top-level guide tool, which is read-only, needs no prior knowledge, and searches and reads the maintained public documentation for you.

The split is deliberate rather than incidental. run executes JavaScript against authorized data once you know the operation you want; guide is where you find out what that operation is. So when the next thing you want is a sentence of explanation, stop writing a run script and ask guide a direct natural-language question, for example How do I create a document?. When the next thing you want is data or a change, write the run script.

The opening sequence

const me = await orientation.whoami()

// scopes is the connection ceiling; per-organization permission is still checked live.
const canAttemptWrites = me.scopes.includes("mcp:write")

// listMine returns an envelope, not a bare array.
const { organizations: orgs } = await organizations.listMine({})

return {
  userId: me.userId,
  authMethod: me.authMethod,
  canAttemptWrites,
  memberships: me.organizationCount,
  organizationIds: orgs.map(organization => organization.organizationId),
}

Two things in that example are the usual stumbles. organizations.listMine returns an envelope shaped { organizations, hasMore, nextCursor? } and not a bare array, so destructuring it as an array fails. And organizationCount from whoami will not always equal organizations.length from a single listMine page, both because the list paginates and because the count includes memberships in organizations that are no longer active.

The example shows the flow; live server validation inside run is authoritative for exact parameters.

When orientation is not the answer

If you need the permissions you hold in one organization, call organizations.getMyAccess for that organization. If you need to know which organizations exist for you, call organizations.listMine. If you need to know how a namespace or workflow behaves, ask guide. If you need to know what an organization expects of you, read its AGENTS.md document after choosing it. whoami is the identity anchor those calls hang from, and it answers none of them itself.

For discovery, ask guide a direct question such as How do I start a session in Oddlynew?. For exact parameters, live server validation inside run is authoritative.