iso20022-mcp

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false. The description usefully adds that resolution comes from local schemas and that errors return a structured {"error": ...} payload instead of raising, which is behavior beyond the annotations. It does not detail return shape, but that is covered by the output schema.

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 compact and front-loaded: core purpose first, then When to use, Not for, and Behavior. Every sentence carries distinct routing or behavioral information without redundancy.

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 output schema exists, the description need not explain return values. It covers purpose, usage timing, exclusions, resolution behavior, and error handling, leaving no meaningful gap for an agent selecting or invoking this tool.

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% and the single parameter is fully documented in the schema, including examples and the bare-family-name resolution rule. The description does not add parameter syntax beyond what the schema already provides, so the baseline of 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 states a specific verb and resource: 'Describe a message type: its required fields and input JSON Schema.' It also names the backing source and clearly differentiates itself from siblings by explaining that it feeds 'validate' and 'generate' and is not the tool for raw XML (that is 'parse').

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 usage timing ('After search, to obtain the schema...') and an explicit exclusion ('Not for: Raw XML payloads; parse reads those'). An agent can decide when to call this versus its siblings without inference.

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/destructive=false, so 'pure transformation; read-only and idempotent' is largely redundant. However, the description adds genuinely new behavior: errors list every missing/invalid field at once and the caller should fix all and retry once. That error/retry contract is valuable context not present in 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?

Front-loaded with purpose and return value, then clearly labeled 'When to use', 'Not for', and 'Behavior' segments. Dense but every clause carries signal; no filler sentences.

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 fully re-explained, yet the 'xml'/'error' keys are still surfaced. Purpose, routing, failure behavior, and validation strictness are all covered for a 2-parameter transformation tool.

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 both parameters are already documented in depth (fields, aliases, validation). The description adds little parameter-specific meaning beyond reiterating validation behavior, so the baseline 3 applies.

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 and resource ('Generate a validated ISO 20022 XML message from records') and immediately names the return key. It is clearly distinguishable from siblings like parse and validate, and the message-family examples make the scope concrete.

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?

Has explicit 'When to use' (outbound initiation and interbank messages) and 'Not for' (inbound camt.053, which has no generator). Both inclusion and exclusion conditions are spelled out, leaving nothing to inference.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description's 'read-only and idempotent' restates that. What it adds beyond the annotations is the operational nature — 'pure in-memory introspection' — which tells the agent there is no network I/O or external side effect, plus the fact that it reports installation status per backing package.

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 action and resource, then organized into clearly labeled 'When to use', 'Not for', and 'Behavior' segments. Every sentence carries routing or behavioral information; no 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?

Zero parameters, rich annotations, and an output schema that carries the return shape, so the description's job is primarily routing and readiness semantics — both delivered. An agent has everything it needs to decide to call this and to interpret the result.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. Describing the return contents (capabilities, backing package, installed flag) is useful but belongs to output semantics rather than parameter meaning.

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 and resource ('List every ISO 20022 family the gateway routes to') and enumerates the concrete families covered (pain, pacs, camt, acmt) plus what each entry contains. It clearly distinguishes itself from the schema-oriented siblings by naming 'search' and 'describe' as the tools for a different job.

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?

Explicit 'When to use' (check environment readiness, verify optional backing packages are installed) and an explicit 'Not for' that routes searching specific schemas to 'search' and 'describe'. Both the condition and the alternative are stated, leaving nothing to inference.

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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context by calling it a 'pure in-memory catalog listing', but mostly repeats the read-only and idempotent traits rather than adding deeper operational detail.

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 scope, then uses labeled 'When to use', 'Not for' and 'Behavior' sections. Every sentence contributes to routing or behavioral understanding, with no 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?

Given the empty input schema, comprehensive annotations and existing output schema, the description supplies the remaining needed context: what is listed, when to use it, what it is not for, and that it is a read-only in-memory catalog. Nothing essential for correct invocation 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?

The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the empty schema is fully consistent with the description.

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, 'List', and a specific resource: the whole ISO 20022 suite, including message families and specialized servers, with those contents enumerated. It also explicitly separates itself from generate/parse/validate for building or reading messages, so an agent can tell what this tool is for.

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?

Provides an explicit 'When to use' section about discovering specialized servers and routing cross-cutting payments workflows. It also includes a clear 'Not for' section naming the alternative tools 'generate', 'parse' and 'validate' for message building and reading.

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 cover read-only/idempotent/non-destructive, and the description goes well beyond them: it discloses the per-family parser coverage limit, that pain/acmt round-trips fail, and that parsing is pure in-memory. These are consequential behavioral constraints an agent cannot derive from the 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?

Front-loaded with the core action and structured with 'When to use / Not for / Behavior' labels. There is mild redundancy between the coverage sentence and the 'Not for' line, both restating that pain/acmt are outbound-only with no parser.

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 two-parameter parsing tool with an output schema and full annotations, the description covers coverage limits, usage boundaries, alternatives, and execution behavior. No material gap remains 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%, so the baseline is 3, but the description meaningfully constrains the valid domain of message_type by stating only pacs and camt families are parseable. It adds practical meaning beyond the schema's example values without restating syntax.

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 and resource ('Parse an inbound ISO 20022 XML message into structured data') and immediately bounds scope to inbound messages. It clearly distinguishes itself from siblings like validate and generate, which the 'Not for' section reinforces.

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?

Has explicit 'When to use' and 'Not for' sections naming the exact conditions (pacs.008, camt.053 inbound) and the excluded families (pain.001, acmt.001), routing the agent to 'validate' or XSD validation as the alternative. Nothing is left to inference.

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 and closed-world, so the safety profile is covered. The description adds context the annotations do not: pure in-memory lookup with zero network or filesystem I/O, which tells the agent this call is cheap and cannot fail on external dependencies.

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 purpose, then segments usage into labeled 'When to use', 'Not for' and 'Behavior' clauses. Dense but every sentence carries routing or behavioral information; nothing is redundant with the name or annotations.

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 re-explained. For a single-parameter discovery tool, the description covers purpose, alternatives, and I/O cost profile completely, leaving nothing an agent needs before calling it.

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 schema already documents the single 'query' parameter including the empty-equals-all behavior. The description still adds value by giving concrete example query values ('reconciliation', 'make a payment', 'pacs.008'), showing both natural-language and identifier-style inputs are accepted.

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 (Search) plus resource (ISO 20022 catalogue), the searchable facets (use-case, message type, keyword) with concrete examples, and the return shape (matching message types, their family, providing package). This clearly separates it from 'describe' and 'validate', which are named as the alternatives.

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?

Contains explicit 'When to use' (first step to discover which message type fits a workflow and which package supplies it) and explicit 'Not for' (field inspection and record checks once the type is known), naming 'describe' and 'validate' as the tools that cover those cases. No routing decision is left to inference.

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 readOnlyHint, idempotentHint and closed-world behavior, so the 'read-only and idempotent' phrasing is partially redundant. It nonetheless adds real context beyond the annotations: 'pure deterministic validation' and 'zero network I/O', plus the specific class of checks performed (types, required fields, date formats, IBAN/BIC).

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?

Purpose is front-loaded, then cleanly labeled 'When to use:', 'Not for:' and 'Behavior:' blocks. It is dense but every clause carries information an agent needs, with no 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 an output schema present, return values need no explanation, and the description covers prerequisites, the validation scope, side-effect profile and sibling alternatives. Nothing an agent needs to invoke this two-parameter tool 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 description coverage is 100% and the records parameter is exhaustively documented, so the schema does the heavy lifting. The description still adds meaning by framing the parameters as validation targets: it names the accepted date format (YYYY-MM-DD) and the IBAN/BIC constraints enforced, telling the agent what the two inputs are scrutinized against.

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 first sentence states a specific verb (validate) and resource (records for a message type against its JSON Schema), and even names the mechanism (the family's backing server). It clearly separates itself from 'generate' and 'parse' by describing validation-before-generation rather than XML production or parsing.

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 an explicit 'When to use' (ahead of 'generate' to verify types, required fields, date formats and IBAN/BIC) and an explicit 'Not for' boundary (raw XML, XSD tools, and 'parse'). Both the triggering condition and the excluded cases are stated, leaving nothing to inference.

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