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

The description discloses the behavioral effects of each decision: 's1' keeps the existing account as source of truth and propagates it, while 'newImported' propagates the newly imported account and mirrors it. This gives a clear picture of what will happen after confirmation. It does not mention potential side effects or irreversible actions, but the decision outcomes are sufficiently described for a confirmation action.

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, consisting of two sentences that front-load the main action and then explain decision options. It uses clear formatting with semicolons to separate the two decision outcomes, making it easy to parse. Every sentence contributes essential information without extraneous detail.

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 tool's role in a larger auth workflow, the description provides sufficient context by referencing auth_switch persist and explaining the scenario. It covers the decision semantics, which is critical for the agent. The use of 'S1' and 'R2' without expansion is a minor gap, but the surrounding sibling tool names and the description itself give enough context to infer meaning.

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?

The description fully explains the 'decision' parameter by listing both enum values and their meanings, which the schema does not cover. The 'token' parameter is already described in the schema as 'confirmation token from the needs_confirmation response', and the description does not add further detail, but together the schema and description provide complete coverage of both parameters.

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—confirming a pending credential reconciliation choice—and provides specific context about the scenario (returned by auth_switch persist). The two decision options are explicitly named, which helps distinguish it from sibling auth tools. However, it relies on abbreviations like 'S1' and 'R2' without explanation, which slightly reduces clarity for an agent unfamiliar with the internal system.

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 gives a clear condition for use: when auth_switch persist returns a pending choice and S1 already holds a different account. It also explains the two possible decisions and their outcomes, effectively guiding the agent on what to do in this scenario. It does not explicitly contrast with alternatives, but the condition makes it clear when this tool is appropriate.

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