Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does well: it declares statelessness explicitly (ADR 0038), states that no token means home-org resolution, and warns that the home org can only be changed in the DASHBOARD, never by the agent. It omits failure behavior (what happens for an unknown org or an org you don't belong to) and does not state read-only-ness outright, leaving a modest gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then the statelessness constraint, then the `_org` mechanics. Dense but every sentence carries operational information. The long parenthetical about the underscore prefix is the one passage that costs more reading effort than it returns.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter resolver with no output schema and no annotations, the critical missing piece is what the call returns — an org id, a slug, a display name? The phrase 'get the RELIABLE way to act under it' gestures at a return value without specifying it, forcing the agent to call and inspect. Otherwise the behavioral context is unusually complete for a tool of this size.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate, and it largely does: `org` is framed as the target to resolve by id or name, and `_org` is explained as the acting-context prefix that avoids clashing with a tool's own `org` argument. The role of `_org` on this tool itself (whether it changes the caller's context or is simply accepted) remains slightly ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Resolve an organization you belong to (by id or name)'. The second sentence clarifies the tool is a resolver with no side effects on session state, which distinguishes it conceptually from oto_list_orgs / oto_org. It does not name any sibling explicitly, so an agent must infer the distinction from the broader tool list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear operational context: to act under another org, pass `_org=<id>` directly on each org-scoped call rather than relying on this tool to set state. It also clarifies the default path (no token → home org, changed only in the dashboard). It stops short of explicit exclusions versus oto_list_orgs or oto_clear_org, which an agent would also want when choosing among the oto_* org family.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.