pain001-mcp

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 readOnly, idempotent, non-destructive, closed-world. Description adds useful detail: it delegates to a specific function and returns coverage.json content with path/branch counts, percentages, completeness, missing/exempt lists, or an error when there is no set or corpus.

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 purpose, then usage, delegation, Args, and Returns. The Args/Returns sections are somewhat redundant with structured data but appropriate for a docstring-style definition and not wasteful.

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?

No output schema exists, so the description carries the burden of explaining return values. It does so clearly: coverage.json content or an error object, including the specific fields returned. Also explains the check's role in the workflow.

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 already documents the 'version' parameter with an example. Description adds no syntax or format detail beyond 'The message type', so 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: returns the schema coverage verdict of one message type's coverage set. Clearly distinguishes from corpus file listing/reading siblings by focusing on coverage report.

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 tells when to use it: '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.' Gives a clear context but does not name alternatives or when-not to use.

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, closed-world). The description adds real behavioral context: the returned text is exactly what pain001 ships and passed XSD, ISO MDR, rail profile, and overlay checks, plus the error-shape fallback when no file exists.

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 efficiently sized. The Args section is largely redundant with a fully-covered schema, and the 'Delegates to pain001.corpus.get_file' line is internal-hint filler, but the Returns block earns its place since there is no 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?

With no output schema present, the description supplies the critical return shape ({"scenario_id", "version", "variant", "xml"}) and the error alternative, which an agent otherwise could not know. Nothing needed to call or interpret the call 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 descriptions are in fact richer (they supply concrete examples like 'gb.chaps.property-purchase' and 'gb.example.priority'). The Args block in the description only restates those parameters in vaguer terms ('The scenario', 'The message type'), so it adds little 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 (Return) and resource (the XML of one validated example file from the market corpus), and immediately distinguishes it from the list_corpus_files sibling by being the single-file fetch. An agent knows exactly what this returns without opening anything else.

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 a concrete use context — showing a model, tester, or mapping exercise what a correct file looks like for a country/rail/edition. It does not name an explicit alternative or exclusion, but the context is clear and actionable.

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?

With readOnlyHint/idempotentHint already covering safety, the description adds real behavioral value: the confidence vocabulary (verified/derived/assumed), the per-rung validation ladder, renames/drops applied by the builder, and an explicit failure mode returning {"error": ...} when no file or corpus exists. It lacks any note on cost, pagination or caching, keeping it below the top mark.

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 purpose followed by usage rationale, then Args/Returns. The Args section is somewhat redundant given the fully documented schema, but nothing is bloated and structure aids scanning.

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?

No output schema exists, so the Returns block (parsed dict or error dict) legitimately fills a gap, and annotations cover the safety profile. An agent has enough to call it correctly, though the upstream delegation to pain001.corpus.provenance adds little for the caller.

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 Args block largely restates the schema ('The scenario', 'The message type') and only marginally enriches it by noting variant is the bank-variant overlay id or None.

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 ('return the provenance sidecar of one example file') and implicitly contrasts with the sibling get_corpus_file / list_corpus_files by scoping to provenance metadata only. An agent can distinguish this from the file-fetching siblings 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?

'Use this to know how far to trust a file' gives a clear motivating context for when to reach for the tool. It does not explicitly name the alternative sibling (get_corpus_file) or state exclusions, so it stops 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety profile is covered. The description adds that the schema represents a 'flat input record' and that field constraints are included, but doesn't describe output format (JSON Schema structure) or whether there are size limits. With annotations carrying the safety profile, a 3 is appropriate.

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 with zero waste: first states purpose, second gives usage context, third names alternatives with their specific function. Front-loaded with the core action and appropriately concise.

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 for a read-only schema retrieval tool with no output schema, one fully documented parameter, and annotations covering safety. The description provides enough for an agent to understand when and how to call it correctly, including routing to alternatives.

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 parameter is fully documented in the schema with enum values and alias explanation. The description only repeats that message_type is 'a supported ISO 20022 pain message type', adding no additional syntax or format details beyond the schema. Baseline 3 is correct when 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 and resource ('Return the full JSON Schema for a message type's flat input record') and names a clear scope. It distinguishes itself from siblings get_required_fields and validate_records by describing exactly what each alternative returns or does.

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 gives the purpose ('learn every field, its type, and its constraints before assembling records, or to drive a form/UI') and routes to sibling tools with distinct conditions: use get_required_fields for only required names, and validate_records to check records against this schema. No inference needed.

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 readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds genuinely new context: results come from the bundled sample, and the call can return an error if the type is unsupported or no template ships.

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 and the routing to get_input_schema are front-loaded in the first two sentences, which is efficient. The Args/Returns block is slightly redundant against a 100%-covered schema, and the 'Mirrors the in-tree ...' sentence is meta-commentary rather than task-relevant, but overall the text is tight and well-organized.

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 no output schema, the description supplies the return shape ({"message_type": str, "columns": list[str]}) and the error variant, which is exactly what an agent needs. Alternatives and preconditions are also covered, leaving no functional gap for a single-parameter read 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?

Only one parameter and schema description coverage is 100%, so the enum values, aliasing rules, and constraints are already fully documented in the schema. The description's 'A supported ISO 20022 pain message type' merely restates the schema, adding no new 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 ('Return the CSV column headers the message type's bundled template uses') with explicit scope tied to the bundled sample. It also differentiates itself from get_input_schema, so an agent can pick between them without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete use case ('hand-building a CSV before generate_message_from_file') and names the alternative tool plus the condition that selects it ('for the typed JSON contract ... use get_input_schema'). Both when-to-use and when-not-to-use are covered.

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/openWorld=false, so the safety profile is covered. The description goes beyond them by disclosing the empty-corpus failure mode ('{"error": ...} when the installed pain001 has no corpus') and by explaining the structural meaning of scenario_id and variant, which annotations cannot convey.

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 purpose and the use-before rule, then organized into Args/Returns blocks. Some material (the scenario_id example, the variant explanation) is dense, but every part maps to a decision the caller makes; nothing is 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?

There is no output schema, so the description carries the return-value burden and does so by spelling out the exact JSON shape including the flat file records and the error case. Combined with the file-family semantics and argument guidance, an agent has everything needed to call and interpret 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 dictionary is already documented, making 3 the baseline. The description adds genuine semantic texture on top: what 'variant' means (bank overlay a file was built with), how coverage files differ from market files, and a concrete scenario_id example, which helps interpret the returned values.

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 ('List the example files pain001 ships') and immediately scopes it to two file families, market scenarios and coverage sets. It also names the sibling tools it precedes (get_corpus_file, get_corpus_provenance), so an agent can position it in the workflow without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use it ('to discover what ready-made, validated ISO 20022 files exist before calling get_corpus_file or get_corpus_provenance'), which is a clear use-before condition. It differentiates market vs coverage files so the caller knows which result it wants, but it does not state when the tool is unnecessary (e.g. if you already have a scenario_id).

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 declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds significant behavioral context: it transforms records only (not XML), reports which fields are renamed/derived/dropped, wraps VersionMapper, returns both migrated rows and a summary, and returns error if version is unsupported. 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 with a clear purpose statement, usage context, workflow, technical reference, return format, and parameter list. Every sentence serves a purpose, and the most critical information is front-loaded. It is appropriately sized for the tool's complexity.

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 (schema version migration), the description is thorough. It explains the transformation process, error handling, return format, and the expected workflow after migration (validate and generate). It references sibling tools for version listing. No gaps remain for an agent to invoke the 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?

The input schema covers 100% of parameters with descriptions. The description's Args section reinforces and adds context, such as examples ('pain.001.001.03'), the shape of records ('each a dict of field name → value'), and references to list_message_types for version options. This adds value 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 explicitly states the tool migrates flat payment records between two pain.001 schema versions, with clear examples ('move .03 rows to .09'). It distinguishes itself from sibling tools like validation and generation tools by specifying the transformation scope.

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 detailed when-to-use guidance: 'when your bank requires a different pain.001 version than your source data uses'. It also outlines the recommended workflow (run validate_records afterwards, then generate_message). However, it does not explicitly state when NOT to use this tool or mention alternatives directly.

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 reading from local filesystem, optional XSD validation, and error return style ({"error": ...}) instead of exceptions. Annotations confirm read-only, non-destructive, idempotent; description aligns with no contradictions.

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-structured: main purpose first, then usage guidance, then details. Every sentence adds value; no redundancy. Efficiently conveys all needed info.

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?

Completes the picture: explains input (file path), optional validation, output format (header + entry list or error). No output schema needed given compact description.

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 description adds context about local filesystem reading and error behavior, but parameter descriptions are already clear in schema. Adds moderate value beyond 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 it parses a camt.053 bank-statement XML file into structured data, using specific verb 'Parse' and resource. It distinguishes from sibling tool parse_pain002 which handles payment-status replies.

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 (for account statements) and when not (for payment-status replies, for in-memory strings). Names alternative tool parse_pain002 and notes this tool requires a file path.

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 readOnly, idempotent, non-destructive. Description adds specific error handling behavior (returns error on schema/parse failure), optional XSD validation, and that it reads from filesystem. No contradictions.

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?

Concise, well-structured with summary, usage, parameters, returns. Front-loaded with purpose and context. Every sentence provides necessary 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 low complexity (2 params, no enums, no nested objects) and full schema coverage, the description fully explains behavior, including optional validation and error returns. No gaps.

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 has 100% description coverage, so baseline is 3. Description adds value by explaining the effect of providing xsd_file_path (validation before parsing) and the return structure on failure, which aids correct invocation.

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 parses a pain.002 file into structured data, identifies the specific resource and action, and distinguishes it from the sibling parse_camt053 by specifying it handles payment-status reports while parse_camt053 handles account statements.

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 (to read bank's acknowledgement of pain.001) and when not (for account statements, use parse_camt053). Provides context about per-transaction status and reason codes.

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 valuable behavioral context: it explains that accents are transliterated, out-of-set characters are replaced with spaces, and the result includes flags (was_valid, changed) for surfacing changes. This goes beyond the annotations by describing the transformation behavior and return flags.

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: it starts with the core purpose, then usage context, then charset details, then behavior, then parameters and return. Every sentence earns its place, and the use of bullet points for charsets improves readability. It is detailed but not bloated.

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 moderate complexity (2 params, 1 enum, no output schema), the description is complete. It covers what the tool does, when to use it, how the charsets differ, the transformation behavior, and the return structure. An agent has everything needed to call it correctly without additional context.

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 well. The description adds value by explaining the practical implications of each charset (e.g., SWIFT_Z is a strict superset, does not permit | or }), and by clarifying the purpose of the value parameter (single free-text field). It also explains the return structure, which is not in 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 clearly states the tool's purpose: sanitize a single free-text field to a SWIFT/ISO 20022 character set, with specific actions (transliterate accents, drop unsupported symbols) and a clear resource (one string). It distinguishes itself from sibling tools like validate_payment_scheme by explicitly noting it operates on one string versus a whole batch.

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 explicit guidance on when to use this tool: on a single free-text value before placing it in a record, and to check if the value changed. It also names the alternative (validate_payment_scheme) for batch compliance checks, and explains the two charset options with their use cases (SWIFT_X default, SWIFT_Z for narrative/envelope fields).

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 provide readOnly, idempotent, and non-destructive hints. The description adds meaningful behavioral details: return shape (kind, value, valid, error only when invalid), case insensitivity for kind, and that invalid kind returns error. This goes 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?

The description is concise (8 lines) and well-structured: purpose, usage guidance, return format, then parameter descriptions in a list. 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?

Given the tool's simplicity, the description covers everything needed: purpose, usage guidance, return format, and parameter constraints. No output schema exists, so the description adequately explains return values. Safety is covered by 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?

Schema coverage is 100%, so the baseline is 3. The description repeats the parameter descriptions from the schema without adding significant new semantics. It briefly mentions that invalid kind returns error, which is already in the schema 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?

The description clearly states 'Validate a single financial identifier (IBAN or BIC).' It uses a specific verb and resource, and distinguishes itself from sibling tools by mentioning alternative batch validation methods.

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 advises when to use this tool ('one-off identifier check') and when not to ('To validate identifiers embedded across a whole batch, prefer validate_records / validate_payment_scheme'). Provides 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 declare readOnlyHint and idempotentHint. The description adds that validation returns a structured violations object with specific keys and mentions delegation to a function, providing useful behavioral context 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?

Well-structured with clear paragraphs. Front-loads purpose and usage. A bit verbose with the function reference but overall efficient for the detail provided.

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 simplicity (2 params, no nested objects, no output schema) and rich annotations, the description fully covers purpose, usage, return format, and supported profiles. No gaps remain.

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% with descriptions for both parameters. The description adds the list of supported profiles and the structure of the return value (including violations keys), compensating for the missing output 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 tool validates records against a payment-scheme rulebook (e.g., SEPA) and distinguishes it from sibling 'validate_records' by specifying it enforces scheme-specific business rules not covered by JSON-Schema validation.

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 instructs to use after 'validate_records' and contrasts the two tools. No explicit when-not-to-use, 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 closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: it discloses that checks are JSON-Schema shape only, that a row-by-row error report is produced, and it gives the concrete return payload shape.

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 purpose, then the when-to-use guidance, then the return shape. The trailing Args section is largely redundant with the schema, costing a little efficiency, but the prose itself is tight and well-ordered.

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, two-parameter validator with no output schema, the description supplies everything an agent needs: purpose, ordering relative to generate_message, scope limits, and an explicit return schema shape. No material gap remains.

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's parameter descriptions (including the enum aliasing note) are richer than the terse Args block, which merely restates 'message_type' and 'records'. Baseline 3 is appropriate since the schema carries the semantic load and the description adds no format or example detail.

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 ('Validate flat records against a message type's input JSON Schema') and immediately bounds the scope to structural/type checking per record. It clearly distinguishes itself from sibling validation tools like validate_payment_scheme and validate_xml_against_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?

Explicitly tells the agent when to use it ('before generate_message to catch structural/type errors') and names the alternative plus its condition ('for payment-scheme rulebook checks ... also run validate_payment_scheme'). Both the intended workflow position and the exclusion boundary 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 declare readOnly, idempotent, non-destructive, local-only. The description adds the filesystem-independence constraint and describes the return shape including the conditional 'error' key present only when invalid, which is genuine behavioral context beyond the annotations. Missing details like whether it short-circuits on first error or reports all errors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by routing guidance, then Args/Returns. Efficient overall, though the Args section is redundant with the 100%-covered schema and the cross-reference to pain001.xml.validate_via_xsd.validate_xml_string_via_xsd is implementation leakage that adds little for an agent.

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?

No output schema exists, and the description compensates by documenting the return dict with its conditional error field. Combined with full parameter coverage and explicit sibling routing, an agent has enough to invoke correctly. Could note error detail granularity for higher completeness.

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 values are fully documented in the schema, including the alias behavior for bare 'pain.001'/'pain.008'. The description's Args block merely restates what the schema already provides, so it adds no meaning beyond the structured data. 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+scope ('Validate a raw pain.001 / pain.008 XML string against its official XSD') and explicitly distinguishes itself from 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?

Explicit when-to-use ('check XML you already have as a string ... without touching the filesystem') and named alternatives for adjacent use cases (validate_records for pre-XML records, parse_camt053/parse_pain002 for statement/status files). Routing is unambiguous.

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