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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description goes further by disclosing the shape of the response: playbook contents (common causes, recommended actions, SLA timeframes, escalation steps, ISO 20022 reason codes) and child reason-code expansion for ACSP. It does not mention any caching, rate limits, or staleness of the reference data, but for a read-only lookup this is a minor 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 primary directive and organized as a scenario→code routing table, which is highly scannable. It does carry some redundancy: the closing 'Examples' block largely restates the scenario mappings already given above, and the 'Common codes' paragraph overlaps the earlier per-code descriptions, adding length without new information.

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?

An output schema exists so return values need not be explained, yet the description helpfully characterizes them anyway. For a single optional-parameter reference/diagnostic tool, everything an agent needs to select and invoke it correctly — entrypoint priority, scenario routing, and code vocabulary — is present and unambiguous.

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 100%, so the schema already documents the single optional 'code' parameter including case-insensitivity and the omit-to-list behavior. The description adds genuine semantics beyond that by mapping concrete real-world symptoms to recommended code values and noting that a code returns its playbook while a reason code (G001) yields narrower detail. This exceeds the baseline 3 for fully-covered schemas.

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 two concrete capabilities with specific resources: explaining SWIFT GPI status/reason codes and returning stuck-payment investigation playbooks. It is clearly distinguishable from siblings like track_payment and tracking_history, which fetch payment state rather than interpret codes. An agent knows exactly what this tool produces without opening the schema.

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?

It explicitly instructs 'USE THIS TOOL FIRST' for the entire family of stuck/delayed/rejected/pending symptoms, then maps each user-reported scenario to a specific code argument (ACSP, PDNG, BLCK, RJCT, RTRN) and reserves the no-arg call for reference listing. When-to-use, when-to-omit, and the routing logic are all explicit.

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