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

With no annotations at all, the description carries the full behavioral burden and does so well: refresh tokens rotate and each works only once, reuse revokes the entire token chain, claim-flow polling has explicit terminal and retry states, shown_once appears only on success, and the claim success path returns a named agent key that never expires until revoked. These are exactly the non-obvious, safety-relevant traits an agent cannot infer from the schema.

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?

The description is information-dense and front-loads the core exchange operation before the flow-specific rules. Nearly every clause carries operational meaning, though the single run-on paragraph mixes three distinct flows and the parenthetical '(auth.md)' reference adds noise without telling the agent where to look.

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 nine-parameter, security-sensitive, no-annotations, no-output-schema tool, the description covers the hard parts: flow selection, retry/terminal conditions, rotation, and success semantics. It stops short of the complete picture because scope/resource usage is undocumented and the error surface for the authorization_code and refresh_token paths (beyond chain revocation) is not described.

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 description coverage is 0%, so the description has to explain parameters, and it largely does: it binds code and code_verifier to the authorization_code path, refresh_token to the refresh path, and claim_token plus the urn:workos:agent-auth:grant-type:claim enum value to the claim path. Two of the nine parameters, scope and resource, are never mentioned anywhere, leaving the agent guessing when they are needed.

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?

The description names a specific operation and resource: exchanging an authorization code plus PKCE verifier, a refresh token, or a claim token for agent access tokens. It also enumerates the three grant_type values inline, so an agent knows exactly which flows the tool serves. It falls short of 5 because it never distinguishes itself from neighbors like auth_oauthAuthorize, auth_oauthRegister, or agents_claim, which appear to sit on adjacent edges of the same OAuth/agent-auth flow.

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?

Usage guidance is strong for the claim flow: poll every interval only while the error is authorization_pending, wait longer on slow_down, and stop on access_denied, expired_token, invalid_grant, or once expires_in has elapsed. It also implicitly tells the agent when to use the refresh_token path via the rotation rule. What is missing is any routing language telling the agent when to pick this tool instead of siblings (auth_oauthAuthorize, agents_claim, agents_register).

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