pain001-mcp

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=true, so the safety profile is partly covered. The description adds genuinely useful behavioral context beyond that: constant-time cryptographic comparison to prevent timing attacks, the concrete state transition from 'staged' to 'committed', and that it writes a file when a path is given. It omits what happens on a second commit (idempotentHint=false), which 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 core action, then organized into Args and Returns sections. Every sentence carries weight (security mechanism, state transition, optional file write). Slightly verbose for the payload but well structured and free of 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 tool's complexity, an output schema exists, and annotations cover the safety profile, the description is nearly complete: it covers parameters, the state change, the security mechanism, and an error return. The only meaningful omission is idempotency/re-commit behavior, which matters for a non-idempotent mutation.

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 the schema already documents all three parameters, including that output_file_path is optional and that stage_id comes from staging. The description restates these without adding syntax, format, or validation detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 (Commit) and resource (authorized staged payment batch) and qualifies the operation with 'dual-control authorization'. This clearly distinguishes it from the sibling stage_payment_batch, which only stages. An agent can tell the two apart without opening either 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?

The description implies the workflow by noting stage_id comes from stage_payment_batch, giving implicit context that this is the post-staging step. However, it never explicitly says when to use this versus simulate_payment_batch (the simulation sibling) or what preconditions must hold before committing. Guidance is implied rather than stated.

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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which the description reinforces by stating it operates on supplied text only, no file I/O. It also explains error handling for missing mandatory 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?

The description is well-structured with a one-line summary, usage context, and details. It is slightly lengthy but efficient, earning its place with useful 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?

Given the output schema exists and annotations cover behavior, the description is complete. It explains the purpose, usage, parameters, and return types adequately.

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 schema covers 100% of the single parameter with a description. The description adds value beyond the schema by explaining what constitutes MT101 text (bare tag list or block-4 envelope) and its repeating sequences.

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 title and description clearly state the tool converts MT101 to pain.001 records. It specifies the context (SWIFT MT→MX migration) and distinguishes itself from sibling tools like parse_camt053 by focusing specifically on MT101 input.

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 explicitly states when to use this tool ('bridge the Nov-2025+ SWIFT MT→MX migration') and directs the output to other tools. It does not explicitly state when not to use it, but the context is clear enough.

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 the description adds material behavior: the result is XSD-validated before return, no file is written, records are normalized (aliases, JSON booleans, bare dates, computed nb_of_txs/ctrl_sum), failures list every bad field at once, and IBAN/BIC are strictly validated and never coerced.

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?

Well front-loaded: purpose and sibling routing come first, then behavior, then return values, then Args. Some normalization detail duplicates the schema text, but no sentence is wasted enough to undercut structure.

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 generator with an output schema and full annotation coverage, the description covers purpose, alternatives, validation, normalization, and failure shape. Nothing an agent needs to call 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 description coverage is 100%, so the schema already documents both parameters in depth, including aliases, defaults, and validation rules. The description's Args block restates the same ground ('A supported ISO 20022 pain message type'), adding little over the enum and schema text; 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 pain XML message from in-memory records') and explicitly contrasts itself with the two nearest siblings. An agent can identify this as the in-memory primary generator without opening any 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?

Explicit routing guidance: use this for records held in memory, use generate_message_from_file when data lives in a CSV on disk, and generate_message_async for very large batches off the event loop. Both when-to-use and alternative conditions are stated.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavior: rendering runs in a worker thread so an agent can interleave other calls, and failures return a JSON-encoded error payload. The return-value mention slightly duplicates the output schema, and nothing is said about concurrency limits or multiple simultaneous invocations.

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 async/large-batch distinction in the first sentence and keeps the usage rule tight. The 'Delegates to pain001.async_adapter.generate_xml_string_async' line is internal implementation detail of marginal value to an agent picking a tool.

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 a rich input schema, an output schema, and full annotation coverage, the description only needs to supply selection guidance and async semantics — both are present. An agent has everything required to choose and invoke it correctly.

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' schema already enumerates key fields, aliases, defaults, and validation strictness in detail. The Args block merely restates the two parameter names, adding no meaning beyond the schema, 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+resource ('Generate validated pain XML') plus a distinguishing scope modifier ('off the event loop, for large batches'). It explicitly names the sibling it mirrors and differs from (generate_message), so an agent can select between them without opening either 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 and when-not: 'Use generate_message for small or interactive batches; use this only when the record count is large enough that blocking would matter.' The alternative and the selecting condition are both named, 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 readOnly, idempotent, non-destructive, and open-world behavior. The description adds useful context: it reads from the local filesystem, delegates to generate_message, applies path-safety guards, and returns validated XML or a JSON error payload.

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 front-loaded with purpose and usage, and most sentences earn their place. However, the Args and Returns sections duplicate information already covered by the input schema and output schema.

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 file-to-XML generator with full schema coverage and an output schema, the description supplies the missing usage context, sibling routing, format limitation, and path-safety note. Nothing critical is absent.

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 schema already documents both parameters including enum aliases and CSV header requirements. The description's Args section largely restates those schema descriptions without adding syntax or constraints, so the baseline is 3.

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 ('Generate'), resource ('validated pain XML'), and source ('CSV file on the local disk'). It explicitly distinguishes from generate_message by contrasting file-based records with in-memory records.

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 says to use this when records live in a CSV file rather than in memory, and tells the agent to call generate_message directly when records are already dicts. It also states the current CSV-only limitation, which is clear when-not guidance for other formats.

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 destructiveHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: it delegates to pain001.corpus.coverage_report and explicitly describes the error return shape when no coverage set or corpus exists. No contradiction with 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?

The description is well-structured and front-loaded: purpose, usage context, delegation, then Args/Returns. Every sentence contributes useful information, and there is no fluff or repetition of schema details.

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 single-parameter tool with a rich output schema and strong annotations, the description covers purpose, usage context, return contents, and error behavior. Nothing an agent needs to decide whether and how to call this 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 schema already documents version as 'The message type, e.g. pain.001.001.13.' The description's Args section merely repeats 'version: The message type' without adding format constraints, defaults, or additional meaning. Baseline 3 is appropriate since the schema carries the semantic weight.

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 opens with a specific verb and resource: 'Return the schema coverage verdict of one message type's coverage set.' It clearly distinguishes this from sibling corpus tools like get_corpus_file and get_corpus_provenance by focusing on coverage verdicts rather than file contents or provenance.

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 use case: 'Use this to check that the shipped coverage files reach every element path and choice branch of an edition's XSD before relying on them to smoke a parser or a mapping.' It does not explicitly name alternatives or when not to use it, but the context is strong enough for an agent to select it appropriately.

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 annotations, the description adds valuable behavior: the file is validated against XSD, ISO MDR rules, rail profile, and overlay; it is exactly what pain001 ships; it delegates to pain001.corpus.get_file; and it returns an error when the file or corpus is missing. This is rich, non-obvious context.

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 front-loaded with the core action, followed by a concise use case, validation guarantees, delegation note, and a structured Args/Returns section. Every sentence adds useful information and the length is appropriate for a tool with three parameters and a custom return shape.

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?

The description covers the tool's purpose, when to use it, what guarantees the returned XML has, the parameters, the return structure, and the error case. Nothing an agent needs to invoke it correctly is missing, especially given the annotations and schema already present.

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 the schema already documents all three parameters with examples. The Args section in the description mostly restates the schema ('scenario_id: The scenario', 'version: The message type', 'variant: The overlay id...') without adding new semantic detail, so the baseline of 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?

The description opens with a specific verb and resource: 'Return the XML of one validated example file from the market corpus.' This clearly distinguishes it from sibling tools like list_corpus_files, get_corpus_provenance, and get_corpus_coverage by focusing on retrieving a single file's XML content.

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 use cases: 'Use this to show a model, a tester or a mapping exercise what a correct file for a given country and rail looks like in a given edition.' It does not mention when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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?

The annotations already mark this as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral detail beyond that: it returns a parsed dict, returns an error dict when the file or corpus is missing, and delegates to pain001.corpus.provenance. It also discloses the provenance contents the agent should expect, which is valuable behavioral transparency.

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 front-loaded with the core purpose and use case, and the provenance contents list is informative rather than filler. The Args and Returns sections duplicate schema information and could be trimmed, but the overall size is reasonable and every section serves a purpose.

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 three-parameter read-only tool, the description is complete: it states what the tool returns, what the return looks like, when an error is returned, and what the provenance data means. Combined with full schema coverage and supportive annotations, an agent has everything needed to invoke and interpret this tool correctly.

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 the schema already fully documents scenario_id, version, and variant, including the version example and the variant's 'omit for generic file' guidance. The description's Args section repeats this information without adding new parameter semantics, so it earns the baseline score and no more.

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 opens with a specific verb and resource: 'Return the provenance sidecar of one example file.' This is clearer than the title and makes the tool's artifact obvious. However, it does not explicitly differentiate itself from sibling tools such as get_corpus_file or get_corpus_coverage, so it stops short of full sibling distinction.

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?

'Use this to know how far to trust a file' provides a clear, concrete usage context and explains what kind of information the result carries. It does not name alternative tools or state when not to use this tool, so there is clear context but no exclusions or alternates.

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 cover the safety profile with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by specifying that the result is the 'full' schema and the record shape is 'flat', which meaningfully clarifies expectations without contradicting 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?

The description is compact and front-loaded: purpose first, then use cases, then explicit alternatives, then a minimal Args section. Every sentence earns its place and there is 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?

The tool has one required parameter, an exhaustive enum in the schema, a rich schema description, an output schema, and annotations covering side effects. The description adds the missing use-case and sibling-selection context, making it complete for an agent deciding how and when to call 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 description coverage is 100%, and the schema itself fully documents the enum values and aliases for message_type. The description's Args line adds only a brief restatement rather than new semantic detail, so the schema carries the parameter-documentation burden.

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 opens with a specific verb and resource: 'Return the full JSON Schema for a message type's flat input record.' It clearly distinguishes this tool from siblings by naming get_required_fields and validate_records, and the 'flat input record' phrasing clarifies the exact shape of what is returned.

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 states when to use the tool: to learn fields, types, and constraints before assembling records, or to drive a form/UI. It also gives clear alternatives with conditions: use get_required_fields for just required-field names, and validate_records to check records against the schema.

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 destructiveHint=false, so safety is covered. The description adds genuine behavioral detail beyond that: the output is narrow (field names only, not type/format constraints), which is exactly the distinction an agent needs when choosing between this and get_input_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?

Three short sentences, front-loaded with the scope limit followed by usage and the alternative. The Args block is mildly redundant with the schema but costs almost nothing and no sentence is wasted.

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 no explanation, and the single parameter is fully documented in the schema. For a one-argument, read-only lookup tool, the description plus structured fields leave no gap an agent would need to guess around.

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 enum description already lists every accepted value plus the pain.001/pain.008 alias behavior, so the schema carries the parameter semantics. The description's only addition is the one-line restatement 'A supported ISO 20022 pain message type', which does not extend meaning beyond the schema.

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 resource (required input field names) with an explicit scope limiter ('only the required' for 'a pain message type'). This clearly separates it from get_input_schema, which the description names as the sibling covering the broader case.

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 ('quick checklist of the mandatory columns before building records') and explicit when-to-use-something-else ('When you need full type/format constraints... call get_input_schema instead'). Routing conditions are 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it returns column names from the bundled sample, returns an error for unsupported types or missing templates, and clarifies the alias behavior for bare family names. This goes beyond the annotations without contradicting them.

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: the first sentence states the core function, the second gives usage context, and the third distinguishes from a sibling. The Args/Returns sections are minimal and directly useful. Every sentence earns its place.

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 simple read-only introspection tool with one parameter, a full output schema, and rich annotations, the description is complete. It covers the return shape, error behavior, and the relationship to sibling tools. Nothing an agent needs to call 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 description coverage is 100%, so the schema already documents the parameter fully, including the enum values and alias behavior. The description adds a concise restatement of the parameter's purpose and the return contract, which is helpful but not strictly necessary. Baseline 3 is exceeded slightly because the description clarifies the alias semantics in the context of the tool's purpose.

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 ('Return the CSV column headers') and resource ('the message type's bundled template'), and distinguishes it from siblings by naming get_input_schema and generate_message_from_file. An agent can tell exactly what this tool does and how it differs from related tools.

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 explicitly says when to use this tool ('to see the exact column order for hand-building a CSV before generate_message_from_file') and when not to ('for the typed JSON contract ... use get_input_schema'). It also notes the mirroring of an in-tree tool, giving clear context for selection.

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 cover read-only, idempotent, and non-destructive behavior, so the description only needs to add context. It meaningfully explains what the two file kinds are, that coverage files carry no scenario, and that a missing corpus yields an error, all without contradicting 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?

The purpose is front-loaded and the description is well organized into usage guidance, args, and returns. The delegation note and return-shape block are somewhat redundant with schema/output schema, but the overall structure remains easy to scan.

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 read-only listing tool with full schema coverage, clear filtering rules, and an output schema, the description covers the discovery workflow, file-kind distinction, error case, and parameter semantics. Nothing critical is missing for an agent to call it correctly.

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 kind, country, and version with examples, so the description does not need to add much. It accurately reiterates the parameters and gives useful high-level context, but it does not materially exceed what the schema already provides.

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?

Clearly identifies the resource ('example files pain001 ships') and the specific listing verb, then breaks the result down into market scenarios and coverage sets. It distinguishes itself from siblings like get_corpus_file and get_corpus_provenance by being the discovery step, so an agent can tell them apart.

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?

Explicitly says to use this tool before calling get_corpus_file or get_corpus_provenance, which pins down the workflow position. It also gives selection context around market vs coverage files and country/version filtering, making when-to-use clear.

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?

Discloses return format (list of dictionaries with message_type and name) and complements annotations (readOnlyHint, etc.) with specific behavioral detail beyond what annotations provide.

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?

Three sentences, front-loaded with purpose, then usage guidance, then return format. Every sentence adds value; no wasted words.

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?

Complete explanation for a zero-parameter tool: purpose, usage context with exclusions, and return structure. No gaps given the tool's simplicity and rich annotations.

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?

No parameters exist, so the baseline is 4. The description adds no parameter-specific details, but none are needed.

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: 'List every supported ISO 20022 pain message type and its human name.' It also distinguishes from siblings by directing users to other tools for schema retrieval.

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?

Explicitly states when to use ('first, before any generation or validation call'), what not to use it for, and names alternatives ('get_required_fields' or 'get_input_schema').

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. Description adds return format (list of dictionaries with id/name/extension) and a dependency note about Parquet extra, providing value beyond 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?

Four sentences, front-loaded with purpose and usage, no redundancy, every sentence adds value. Well structured.

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?

Despite output schema existing externally, description succinctly covers return format and extra requirement. For a zero-parameter, read-only tool, this is complete.

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?

No parameters exist, so baseline is 4. Schema coverage is 100%, and description correctly has no param info needed.

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 specific verb 'list' and resource 'on-disk data formats the pain001 loader can read'. Distinguishes from sibling list_message_types by clarifying it lists data-source formats vs message types.

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?

Explicitly says 'Use this to tell a user which file types they may supply to generate_message_from_file' and directs to list_message_types for message types, providing clear alternatives.

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 establish readOnly, idempotent, and non-destructive behavior. The description adds real behavioral context beyond that: it reports renamed/derived/dropped fields, returns migrated rows plus a summary, and returns an error object if either version is unsupported. The 'transforms records only' statement clarifies there is no persistent side effect.

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 front-loaded with purpose and usage, then workflow, then return contract. It is readable and well organized, though somewhat redundant: the renamed/derived/dropped summary appears twice, and the Args/Returns sections duplicate the input schema and output schema rather than adding 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?

For a three-parameter transformation tool with rich annotations and an output schema, the description is complete. It covers the trigger condition, the transformation semantics, the error case, the return shape, and the correct surrounding workflow with validate_records and generate_message. Nothing needed 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 description coverage is 100%, so the baseline is 3 even without extra parameter detail. The description's Args section mostly repeats the schema, and the examples it adds ('pain.001.001.03', 'pain.001.001.09') are already present in the schema. It does not meaningfully compensate beyond what the structured schema already documents.

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 opens with a specific verb and resource: 'Migrate flat payment records between two pain.001 schema versions.' It clearly distinguishes itself from siblings by noting it 'transforms records only' and naming the downstream validate_records/generate_message steps, so an agent can tell this apart from XML generation or validation tools.

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 a clear trigger condition: use when a bank requires a different pain.001 version than the source data uses, with a concrete .03-to-.09 example. It also prescribes the follow-up workflow ('run validate_records afterwards, then generate_message'), but it does not explicitly mention alternatives or when not to use this tool, such as the sibling convert_mt101.

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 the description adds meaningful behavior beyond that: optional XSD validation precedes parsing, errors are returned as an {"error": ...} payload rather than raised, and the wrapped function is identified. This gives an agent accurate expectations about side effects and failure modes.

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 front-loaded with purpose and tool-selection guidance, then gives error behavior and args in a standard structure. It is slightly redundant with the input schema in the Args block, but every major section earns its place and there is 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?

For a two-parameter read-only tool with rich annotations and an output schema, the description covers prerequisites (file path), optional validation semantics, error return shape, and the sibling alternative. Nothing an agent needs to decide whether and how to invoke it 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 both parameters already have clear descriptions, so the baseline is 3. The description's Args block largely repeats the schema rather than adding new semantics; it does not materially deepen parameter understanding.

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 names a specific verb ('Parse'), a specific resource ('camt.053 bank-statement XML file on disk'), and the output ('structured data'). It explicitly distinguishes from parse_pain002 by contrasting statement reply vs payment-status reply, so an agent can select it correctly without inspecting sibling 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?

The description gives explicit when-to-use context: reading an account statement into a header + entry list. It names the alternative tool parse_pain002 for payment-status replies and warns that validating an already-held camt.053 string is not this tool's purpose because it requires a file path. This is strong routing guidance.

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 annotations, the description discloses that the tool reads from the local filesystem, optionally validates against an XSD before parsing, and returns an {"error": ...} payload on schema or parse errors instead of raising. It also notes the wrapped function, adding useful implementation context without contradicting any 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?

The description is well structured: a clear one-sentence summary, a usage rationale, an explicit sibling alternative, technical behavior, and a compact Args/Returns section. Every sentence serves a distinct purpose, and the key differentiator is front-loaded.

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?

The description is complete for a two-parameter parse tool with rich annotations. It covers what the tool does, when to use it, what the XSD parameter does, the error behavior, and the return shape. Nothing an agent needs to select and call this tool 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 description coverage is 100%, so the baseline is 3. The description's Args section mostly restates what the schema already documents, though it adds a small amount of contextual clarity around local filesystem access and the upfront-validation behavior. It does not meaningfully expand the semantic meaning of the parameters beyond the schema.

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: 'Parse a pain.002 payment-status report file on disk into structured data.' It also distinguishes itself from the sibling parse_camt053 by clarifying that this tool reads the bank's acknowledgement of a submitted pain.001, not the later account statement.

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 explicitly tells the agent when to use this tool — to read per-transaction accepted/rejected statuses and reason codes for a pain.001 — and when to use parse_camt053 instead. It also explains when to provide xsd_file_path, making the selection criteria and invocation context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds valuable behavioral detail beyond the annotations: accents are transliterated, out-of-set characters are replaced with a space, and the result includes flags for validity and change. It also discloses charset limitations such as SWIFT_Z not permitting '|' or '}'.

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 front-loaded with purpose and usage, then uses clear bullets and an Args/Returns section. It is longer than strictly necessary—some charset details repeat what the schema already states—but every major section contributes to correct invocation, so the structure earns a strong score.

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?

The description covers the input value, both charset options, the transformation behavior, and the exact return shape. It also routes to the correct sibling for batch validation. With a rich output schema and safety-bearing annotations present, there are no meaningful gaps for an agent deciding whether and how to call 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%, so the parameter semantics are already well documented in the input schema. The description still adds value by framing charset as 'SWIFT_X' default and backward-compatible, noting SWIFT_Z is a strict superset, and clarifying the practical distinction between basic and extended character sets.

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: 'Sanitise one free-text field to a SWIFT / ISO 20022 character set.' It clearly differentiates from the sibling tool validate_payment_scheme by noting that this operates on one string while that checks a whole batch's rulebook compliance. The two supported charsets are also explicitly named and contrasted.

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 explicit when-to-use guidance: apply this to a single free-text value before placing it in a record, and use it to surface whether the value changed. It also names the alternative for batch-level checks (validate_payment_scheme) and explains when to choose SWIFT_Z versus SWIFT_X, leaving no ambiguity about selection.

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=true, idempotentHint=true and non-destructive, so the safe, repeatable nature is covered. The description adds genuine context beyond that: it discloses that it evaluates network-specific rulebooks (per-rail currency/IBAN/charge-bearer/cut-off constraints) and the shape of the outcome (verdict, checks, settlement window, error).

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 uses bullets efficiently to convey per-rail semantics that would otherwise be opaque enum values. The trailing Args/Returns block largely duplicates the input schema and the output schema, which is minor waste rather than a structural flaw.

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 an output schema exists, the return detail is optional but harmless; the annotations cover safety. The description supplies the domain context an agent needs (rail-specific rule profiles, staged-batch input) to invoke it correctly, leaving only the sibling-boundary with simulate_payment_batch unaddressed.

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 would be 3, but the description adds real meaning to the clearing_system enum by spelling out what each rail enforces (EPC-SEPA EUR+IBAN+SLEV, FedNow instant gross, US-ACH next-day, SWIFT-MX BIC routing, CHAPS RTGS, BACS three-day), helping the agent choose a profile. The stage_id note merely restates the schema.

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 (simulate) and resource (settlement and clearing network execution) scoped to 'a staged batch', plus a concrete per-rail breakdown. It is clearly distinct from validation/generation siblings, though it never names the nearest sibling, simulate_payment_batch, to draw the boundary explicitly.

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?

Usage is only implied: it works on 'a staged batch' whose stage_id comes from stage_payment_batch, and each rail's intended use case is sketched. There is no explicit when-to-use-this-vs-simulate_payment_batch guidance and no exclusions or prerequisites stated.

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 the description usefully adds that no XML is generated and no files are staged, plus it outlines the internal checks and the returned verdict. It does not cover permissions, rate limits, or cost, so it adds solid but not exhaustive context.

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 one-line summary followed by a scannable numbered list of the five verifications is well structured. The trailing Args section largely duplicates schema content and is the one redundant element.

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 an output schema exists, the description need not detail return values, yet it still states a structured verdict with totals, per-currency sums, duplicates, and errors. Combined with the explicit no-side-effect statement, it is complete 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 description coverage is 100% and the schema itself documents scheme, records (with aliases, formats, defaults), and message_type in rich detail, including the bare-family aliases. The description's Args block only restates these minimally, adding no meaning beyond the schema, 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 (simulate/pre-flight) and resource (payment batch) and enumerates the five concrete checks performed. This clearly distinguishes it from siblings like validate_records, stage_payment_batch, and generate_message.

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?

Positions the tool precisely: 'pre-flight a payment batch before XML generation' and 'without generating XML or staging files,' which implicitly routes agents away from stage_payment_batch/generate_message for dry-run checks. It never explicitly names those alternatives or states when-not to use it, so a full 5 is not earned.

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 only declare readOnlyHint=false/destructiveHint=false/idempotentHint=false; the description adds genuinely useful behavior beyond that: zero fund movement, an in-memory staging model, a 1-hour expiration window, and a cryptographic confirmation token required before authorization. It does not state that repeat calls create new batches (consistent with idempotentHint=false), so it stops short of full disclosure.

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 purpose is front-loaded in the first sentence, but the six-item computed-steps list is verbose and the Args/Returns sections duplicate content already covered by a 100%-covered schema and an existing output schema. Length is not justified by additive 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 needn't be explained, yet the description still sketches the StagedBatchResult. For a complex staging operation it covers the important lifecycle (staging → risk/validation → token → authorization) and the ephemeral nature of the object. It omits any auth/permission requirements or note on repeat 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 description coverage is 100%, so the schema already carries the parameter contract in detail (ISO 20022 enums, aliases, defaults, IBAN/BIC validation). The Args section in the description largely restates this, adding little beyond the schema. Baseline 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?

Specific verb+resource: 'Stage a payment batch' with a clear scope (in-memory, zero fund movement, 1-hour expiration). It is clear what the tool does, but it never names or contrasts itself with the obvious siblings (simulate_payment_batch, commit_payment_batch), leaving the agent to infer the boundary.

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?

'For simulation and dual-control approval' and 'token for subsequent authorization' imply where this sits in a workflow, but the description never states when to choose this over simulate_payment_batch or commit_payment_batch, nor any preconditions or when-not-to-use guidance. Usage is implied rather than explicit.

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=true, idempotentHint=true, destructiveHint=false. The description adds specific behavioral constraints beyond these: 'Never changes IBANs, BICs, accounts, amounts or currencies, even for whitespace' and 'deterministic'. It also clarifies the output behavior (patches or reason). No contradiction with 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?

The description is compact: a purpose sentence, an output sentence, and a constraint/usage sentence. It front-loads the purpose and constraints, with no wasted words or redundant content. The structure is clean and efficient.

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 presence of an output schema and rich annotations, the description covers all essential aspects: what it does, its output, its constraints, and when to use it. It does not need to explain return values since the output schema handles that. Nothing critical is missing for an agent to invoke it correctly.

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% per context signals, so the schema already documents each parameter. The description's Args section largely mirrors the schema (e.g., 'record: A flat payment record, left unchanged' vs. schema 'One flat payment record; never modified'). It adds minimal new meaning, so a baseline 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 ('Suggest'), a specific resource ('record fixes'), and precise constraints ('review-only', 'non-financial fields', 'deterministic'). It clearly distinguishes this from siblings like validate_records (which validates) and generate_message (which generates), and explicitly notes it returns patches or a cannot_autofix reason, making the tool's function unambiguous.

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 provides clear usage context: it is meant to be used before generating a payment, and is review-only. It also implicitly defines when not to use it (for financial fields, since it never changes them). However, it does not explicitly name alternative tools or exclusions, so it falls short of a 5.

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?

The annotations already mark the tool as read-only and idempotent. The description adds the return contract (kind, value, valid, error) and clarifies that the error key appears only when valid is false, which is useful behavioral context beyond 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?

The description is compact and well structured: purpose, usage guidance, return format, and parameter details. Every section earns its place, and the key routing information is front-loaded.

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, read-only, idempotent tool with a complete input schema and an output schema, the description supplies everything needed to call it correctly. It covers purpose, alternatives, return shape, and parameter meaning without any meaningful gap.

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 both parameters are already well documented in the schema. The Args section mostly restates the schema and adds no significant new meaning, 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 precise action and resource: validating a single financial identifier (IBAN or BIC). It also distinguishes this tool from batch validation siblings, so an agent can tell exactly what it 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?

It explicitly says to use this for one-off identifier checks with a clear pass/fail and reason. It also names validate_records and validate_payment_scheme as the preferred alternatives for batch validation, giving concrete when-to-use versus when-not-to-use guidance.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: it delegates to pain001.validate_scheme, supports four named profiles, returns structured violations with specific keys, and returns an error for unknown profiles. No contradictions with 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?

The description is well-structured and front-loaded with the purpose and usage guidance. The Args and Returns sections are scannable and informative, though the profile list is repeated in both the prose and the Args section, adding minor 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?

The description fully equips an agent to invoke the tool: it names the alternative to use before it, specifies supported profiles, documents both parameters, and describes the exact return shape including error behavior. With only two parameters and strong annotations, nothing essential 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%, so the schema already documents both parameters. The description's Args section largely restates the schema, though it does add the clarifier that records are 'flat dicts' and that the tool validates 'for one profile' at a time. This is useful but not a major addition beyond an already rich schema.

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 specific action: validating records against a payment-scheme rulebook, with concrete examples (SEPA) and named profiles. It also distinguishes itself from the sibling validate_records by explaining that structural shape versus rulebook compliance is the difference.

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?

Explicitly says to use this tool after validate_records and explains the division of labor: JSON-Schema validation checks structure, while this enforces scheme-specific business rules. This gives an agent clear guidance on when to choose this tool over its sibling.

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 and idempotentHint, and the description adds valuable behavior beyond that: it checks JSON-Schema shape only, reports row-by-row errors, and returns a specific report structure. No contradiction with 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?

The description is well structured and front-loaded: purpose, usage, return format, then args. The Args block is somewhat redundant with the input schema, but the usage and return-format sentences earn their place.

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 read-only validation tool with complete schema annotations and sibling references, the description covers purpose, usage, limitations, and return shape. Nothing needed to call 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?

Input schema coverage is 100%, so the schema already documents message_type and records with details like the enum and references to get_input_schema/get_required_fields. The Args section in the description mostly repeats this rather than adding new semantic detail, so baseline 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 opens with a specific verb and object: 'Validate flat records against a message type's input JSON Schema.' It clearly separates this validation tool from sibling validate_payment_scheme by naming the alternative and the different check performed.

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 says exactly when to use it ('Use this before generate_message to catch structural/type errors') and when to use an alternative ('for payment-scheme rulebook checks... also run validate_payment_scheme'). This is explicit routing between siblings with no inference required.

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 non-destructiveness. The description adds useful behavioral context beyond annotations: it operates on an in-memory string without filesystem access, wraps a specific validation function, and specifies that the returned error field exists only when valid is false. No contradiction with 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?

The description is well-structured and front-loaded with the primary use case and alternative tools. The Args/Returns block is useful, though it partially duplicates the fully specified input schema, and the internal module path adds little for an agent. Still, every section serves a purpose and there is 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?

For a two-parameter validation tool, the description covers when to use it, what it does, what its output shape is, and how it differs from the most relevant siblings. The schema covers the remaining enum details and aliases, and the annotations cover safety and idempotency, so nothing an agent needs 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%, and the schema itself fully documents xml_content and message_type, including the enum values and alias behavior. The description adds only a terse restatement of the two parameters, so it does not meaningfully exceed what the schema already provides. Baseline 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?

States a specific verb (validate), a precise resource (raw pain.001/pain.008 XML string), and the referenced XSD. It also distinguishes itself from related siblings by naming validate_records, parse_camt053, and parse_pain002.

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?

Explicitly says when to use this tool: when the XML is already a string and you need to check it without touching the filesystem. It also gives clear alternatives and conditions: use validate_records before XML exists, and use parse_camt053/parse_pain002 for parsing statement or status-report files.

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