mailkite_exchange_oauth_token

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

Given annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the description adds valuable behavioral context beyond those hints. It discloses that the authorization code is single-use and expires quickly, with a replay returning invalid_grant. It also notes that the refresh token is single-use and is revoked upon rotation. These details help the agent understand the side effects and constraints of the operation. While it doesn't explicitly state that the operation mutates state (like revoking tokens), the description of token rotation and revocation implies it. No contradiction with annotations.

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 concise and front-loaded: it starts with the core action and positions it as step 3. It then provides necessary context about the OAuth flow in a few sentences. There is no fluff, and each sentence contributes value. It could be slightly more structured by separating the two grant types, but it's still efficient.

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?

Given the complexity of an OAuth exchange with two grant types and six parameters, the description is fairly complete. It explains the overall flow, the need for a management session token, and points to the next step (getApiKey). However, it does not describe the response format (e.g., that it returns tokens), but since there is no output schema, the description could have mentioned what the tool returns. Still, the pointer to getApiKey implies the returned access token is used there. Minor gap, but solid overall.

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 100%, so the schema already documents each parameter thoroughly. The description adds a bit of context by describing the overall flow but does not provide additional parameter semantics beyond what's in the schema. For example, the schema already describes code_verifier as required and the grant_type enum. The description reinforces the sequence but adds minimal new information about parameters themselves. Baseline 3 is appropriate.

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 clearly states the tool's purpose: exchanging an authorization code for an access token or rotating a refresh token, and positions it as step 3 of an OAuth linking flow. It mentions specific actions (exchange) and resources (authorization code, access token, refresh token), which distinguishes it from other OAuth-related tools like register_oauth_client and get_api_key.

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?

The description provides a clear sequence: it explains the steps before (sending user to /oauth/authorize with specific parameters) and after (calling getApiKey with the access token and storing the key). It implicitly indicates when to use this tool (after obtaining the authorization code, before obtaining the API key) but does not explicitly mention alternatives or exclusions, which would justify a 5. However, it does mention the requirement of a management session token, which is useful context.

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