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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds what actually comes back per input shape and discloses two scope limits (external code list only; no message structure/bank fill behavior). It does not discuss pagination or result size on the open-world=closed lookup, a minor remaining 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-loads the trigger sentence, then a bulleted list of input forms – easy to scan. It is long relative to a single-parameter tool and the form list partially restates the schema description, but each bullet carries distinct return semantics, so little is pure waste.

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 one-parameter lookup with an output schema present, the description supplies everything else an agent needs: trigger conditions, input grammars, per-form output expectations, and scope boundaries. Nothing required to invoke it correctly is missing.

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 baseline is 3, but the description goes beyond it by enumerating eight concrete input forms and stating the return content for each ('PMNT//ESCT' returns the families under PMNT that contain ESCT; bare 'ESCT' is matched at every level separately). This meaningfully extends the schema's shorter format note, though the two texts overlap on slash/separator rules.

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+resource ('ISO 20022 Bank Transaction Codes... that classify entries in bank statements and account reports') with concrete examples (PMNT, PMNT-RCDT, PMNT-RCDT-ESCT). It explicitly bounds the tool ('matches codes, not meanings', 'ISO external code list only'), which cleanly separates it from the legacy/scheme-mapping sibling. An agent can select this tool 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?

Opens with an explicit trigger ('Use for ANY question about...') and pre-empts the common mistake of skipping the call for familiar codes ('Call it even when the code looks familiar'). It also gives exclusions: no proprietary/bank-specific codes, no message-structure information. Guidance covers when to use, when not to, and how to browse when searching by meaning.

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