ISO 20022 Navigator

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.

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds real behavioral context beyond that: it returns 'sourced, current values' and flags deactivated codes, and it discloses the pagination contract (page.complete/page.next_offset) with an instruction to finish paging before answering. It also warns that concept_description is AI-generated, a useful trust caveat not available in structured fields.

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 purpose, then per-identifier behavior, then the 'Not covered' block — a sensible order. Bullets are tight, though the description is on the long side and repeats the paging rule twice (once in prose, once in the schema for offset).

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-shape explanation is not required, yet the description still usefully characterizes the return format (pipe-delimited with header row). Coverage of the three identifier modes, exclusions, and paging is enough for correct invocation; the only minor gap is that element-level vs message-level scope is asserted without elaboration.

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. The description earns above baseline by explaining the interaction between `message` and `code` (code only applies when message is a code set), advising the `code` shortcut for validity questions instead of fetching a whole set, and describing the paging loop for `offset`.

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?

Opens with a specific directive ('Use for ANY question about ISO 20022 external code sets') and enumerates the concrete question types it answers (values of a code set, meaning of a code, validity, which code sets a message uses). It explicitly names the sibling iso20022_bank_transaction_codes as out of scope, so an agent can route correctly without opening another 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?

Gives explicit when-to-use ('Call it even when the answer seems well known'), a when-NOT-to-use section that names two concrete sibling tools for excluded topics, and a concrete alternative for the session-language question ('use iso20022_bank_transaction_codes'). Routing logic is unambiguous.

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

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

Beyond the readOnly/idempotent/non-destructive annotations it discloses real behavioral traits: results are sourced with status and caveats, 'schemes' responses omit descriptions for compactness while `standard` adds a scheme description, and retired ISO messages are returned flagged via iso20022_deactivated_in rather than hidden.

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 imperative 'Use for ANY question...' is front-loaded and the bulleted legacy/ISO cases are easy to scan. It is somewhat long and repeats the omit-`standard` guidance already present in the schema, keeping it from a 5.

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, yet the description still previews the return structure (legacy_equivalents, used_by_schemes, iso20022_deactivated_in), so an agent fully understands inputs and outputs. Nothing material is missing for correct invocation.

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% and the `standard` description already states the omit-by-default rule, so baseline is 3. The description goes further by explaining the differentiated response shape for legacy vs ISO input and the effect of `standard` on output size, adding genuine meaning. It stops just short of syntax details, so a 4.

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 states a specific verb and resource: mapping legacy payment messages (MT103, NACHA, CHAPS) to/from ISO 20022 messages and identifying which schemes use a message. It explicitly bounds the scope ('message-level only') and disclaims field-level mapping, which cleanly separates it from any sibling focused on transaction codes.

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 gives explicit when-to-use guidance ('Use for ANY question about...', 'Call it even when the answer seems well known'), the exact condition for including the optional `standard` param ('Omit unless the user names one scheme'), and an explicit when-not ('this tool does not map individual fields... Do not cite it for those').

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

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

Annotations already declare read-only, idempotent, closed-world, non-destructive behavior. The description adds real context beyond those: it covers only variant 1, returns the latest version held and notes differences, flags retired messages, and points to next_calls. It stops short of describing pagination or error behavior, so not a full 5.

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 first sentence is front-loaded with the core promise and the alternatives follow immediately after. It is slightly long and the long enumeration of return fields borders on restating the output schema, but no sentence is purely filler.

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?

With one required parameter, full schema coverage, an output schema present and sibling routing provided, an agent has everything needed to call this correctly. The variant/version and retirement caveats close the remaining ambiguity.

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%, with the pattern, length bounds and accepted separators already documented in the schema, so the baseline is 3. The description reinforces accepted forms ('pacs.008', 'camt.053', 'pain.001') but adds only the latest-version-resolved behavior, which the schema description already states.

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 resource (an ISO 20022 message) and enumerates exactly what it returns: official name, purpose, business area, latest version, structure statistics. It also names the siblings it is not for (legacy/scheme mappings, code sets), so the agent can separate it from alternatives without opening schemas.

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?

Gives explicit routing: use this for any 'what is this message' question, use iso20022_legacy_and_scheme_mappings for MT/NACHA/CHAPS equivalents and schemes, and iso20022_code_sets for code-set lists. It even tells the agent to call it despite familiarity, removing the main false-negative risk.

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