Server Quality Checklist

Tool Scores

• validate_recordsA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, indicating safe, idempotent read. The description adds return format details but does not disclose additional behavioral traits 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.

  Conciseness4/5

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

  Description is concise with clear purpose and usage in two paragraphs. Front-loaded with key information, but could slightly streamline the Args section since schema already covers it.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given no output schema, the description adequately explains return format (report with valid, total, valid_count, errors). Complete input expectations and usage context are provided, making it self-contained.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% with detailed descriptions for both parameters. The tool description's Arg section repeats schema info but adds no new meaning; baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Clearly states it validates flat records against a message type's JSON Schema. Distinguishes from siblings like validate_payment_scheme and generates_message by specifying it catches structural errors and provides row-by-row error reports.

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

  Usage Guidelines5/5

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

  Explicitly advises to use before generate_message and to also run validate_payment_scheme for rulebook checks, providing clear guidance on when to use and 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.

• get_required_fieldsA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context that it returns only field names, not types or constraints. 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.

  Conciseness4/5

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

  Description is concise (2-3 sentences plus an 'Args' block slightly redundant with schema). Efficient and front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple 1-parameter tool with comprehensive schema and annotations, the description covers purpose, usage guidance, and return value, making it fully self-contained.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% with detailed enumeration and alias explanation in the schema description. The main description adds no additional semantic value beyond restating 'a supported ISO 20022 pain message type.' Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool lists only required input field names for a pain message type, distinguishing it from get_input_schema which provides full type/format constraints.

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

  Usage Guidelines5/5

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

  Explicitly states use case ('quick checklist') and when not to use ('when you need full type/format constraints'), directing to alternative get_input_schema.

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

• validate_payment_schemeA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• validate_xml_against_schemaA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description adds value by confirming no filesystem access and specifying the return structure with valid, message_type, and error fields.

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

  Conciseness4/5

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

  Well-structured with clear first line, usage guidance, function reference, and comprehensive Args/Returns. The line 'Wraps :func:pain001.xml.validate_via_xsd.validate_xml_string_via_xsd.' is slightly technical but adds traceability.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 2-parameter validation tool with no output schema, the description fully covers inputs, return structure, and distinguishes from related tools. No gaps remain.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% and schema descriptions are detailed. The description adds an Args section but doesn't significantly extend beyond the schema, maintaining baseline score of 3.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states 'Validate a raw pain.001 / pain.008 XML string against its official XSD', specifying verb (validate), resource (XML string against XSD), and scope (pain.001/pain.008). It differentiates from siblings like validate_records and parse_camt053.

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

  Usage Guidelines5/5

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

  Explicitly states when to use (check XML as string without filesystem) and when not (use validate_records for pre-XML validation, use parse_camt053/pain002 for parsing). Also mentions alternative tools.

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

• get_input_schemaA
  4.5/5.0
  Behavior4/5

  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 context about returning a full JSON Schema but doesn't contradict annotations. No additional behavioral traits are needed given the annotation coverage.

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

  Conciseness5/5

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

  Description is two short paragraphs plus an Args line, front-loaded with purpose. Every sentence adds value with no redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the single parameter with enum, rich annotations, and sibling list, the description fully covers what the tool does, why to use it, and how it relates to others. No output schema is needed as the return is the schema itself.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so baseline is 3. The description adds only a brief 'Args: message_type: A supported ISO 20022 pain message type,' which largely repeats the schema's description. No new meaning beyond the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Description clearly states 'Return the full JSON Schema for a message type's flat input record,' specifying the verb and resource. It distinguishes from siblings by mentioning alternative tools for required fields and validation.

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

  Usage Guidelines5/5

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

  Explicitly says when to use ('learn every field, its type, and its constraints before assembling records, or to drive a form/UI') and when not to, with named alternatives ('get_required_fields' and 'validate_records').

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

• validate_identifierA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• convert_mt101A
  4.6/5.0
  Behavior5/5

  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.

  Conciseness4/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• inspect_templateA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds specific behavioral context: it returns column names from the bundled sample, or an error if the type is unsupported or no template ships. 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.

  Conciseness4/5

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

  The description is well-structured with a clear initial sentence, usage guidance, and a comparison. However, the Args/Returns section partially repeats schema info, making it slightly longer than necessary. Still, it remains efficient and front-loaded.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the tool's simplicity (1 parameter, no output schema), the description fully covers behavior: it specifies the exact return format (columns list or error) and states conditions for error. No additional information is needed.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, and the schema already explains the message_type parameter with enum and alias details. The description restates this information without adding significant new semantics, so baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool's purpose: 'Return the CSV column headers the message type's bundled template uses.' It specifies both the verb ('return') and resource ('CSV column headers'), distinguishing it from siblings like get_input_schema which returns a JSON contract.

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

  Usage Guidelines5/5

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

  The description explicitly advises when to use this tool: 'Use this to see the exact column order for hand-building a CSV before generate_message_from_file.' It contrasts with get_input_schema for the typed JSON contract, providing clear differentiation.

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

• list_supported_formatsA
  4.7/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• migrate_recordsA
  4.7/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• parse_pain002A
  4.7/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• sanitize_to_iso20022_charsetA
  4.7/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• generate_messageA
  4.8/5.0
  Behavior5/5

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

  Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: normalization of records, computation of nb_of_txs/ctrl_sum, strict IBAN/BIC validation, error payload format, and return type. No contradiction.

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

  Conciseness4/5

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

  Description is well-structured with clear paragraphs: purpose/alternatives, normalization/validation, return type, then args. It is comprehensive but slightly verbose; some information is repeated (e.g., IBAN/BIC validation). Still, efficient for the detail provided.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given complexity (2 params, 100% schema coverage, output schema exists, annotations present), the description is very complete. It covers purpose, alternatives, behavioral details, parameter semantics, and validation. Only minor gap: does not explicitly state output type, but returns are described.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, baseline 3. Description adds value by listing key fields for 'records', explaining aliases and defaults, and describing enum aliases for 'message_type'. Provides meaningful context beyond schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states it generates a validated ISO 20022 pain XML message from in-memory records. It uses specific verb 'generate' and resource 'pain XML', and distinguishes from siblings by specifying 'from 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.

  Usage Guidelines5/5

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

  Explicitly states when to use this tool (pass records in memory) and when to use alternatives (generate_message_from_file for CSV on disk, generate_message_async for large batches). Also mentions validation and no file written.

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

• generate_message_from_fileA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context beyond these: it reads from local filesystem, delegates to generate_message, uses a specific CSV loading function with path-safety guards, and returns validated XML or error JSON. 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.

  Conciseness4/5

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

  The description is well-structured with the key purpose upfront, followed by usage guidance and technical details. It is slightly verbose in places (e.g., references to function paths) but each sentence adds value. Could be trimmed slightly but remains effective.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the two parameters and the presence of an output schema (not shown but referenced), the description covers all necessary aspects: purpose, usage, parameters, return format, and technical details. It references sibling tools appropriately and is complete for an agent to decide and invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100% with clear parameter descriptions. The description adds extra meaning by clarifying that 'pain.001' and 'pain.008' are aliases for specific versions, and referencing the sibling tool 'list_message_types'. This provides value beyond the schema enum.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the verb 'Generate', the resource 'validated pain XML', and the source 'from a CSV file'. It distinguishes this tool from its sibling 'generate_message' by specifying that it works with a file rather than in-memory data. The title also reinforces the purpose.

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

  Usage Guidelines5/5

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

  The description explicitly tells when to use this tool ('when records live in a CSV file') and when not to ('if you already have records as dicts, call generate_message'). It names the alternative tool and provides clear context about supported formats and future plans.

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

• generate_message_asyncA
  4.9/5.0
  Behavior5/5

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

  The description adds context beyond annotations: it runs in a worker thread, delegates to a specific async adapter, returns validated XML or error JSON. Annotations already indicate read-only and idempotent, but the description clarifies the async behavior and error handling.

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

  Conciseness4/5

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

  Well-structured and front-loaded with purpose and usage guidance. The Args section somewhat duplicates schema descriptions but adds valuable detail. Could be slightly shorter, but overall efficient.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Covers all essential aspects: purpose, behavior comparison, delegation, return format, and thorough parameter details. Given the complexity (async, large batches, many parameters) with output schema present, the description is complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, yet the description adds extensive detail: record shape, aliases, defaults, validation rules for IBAN/BIC, and enum aliases for message_type. This goes well beyond the schema's descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states 'Generate validated pain XML off the event loop, for large batches.' It specifies the resource (pain XML), action (generate), and distinguishes from the synchronous sibling generate_message by noting the async execution for large batches.

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

  Usage Guidelines5/5

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

  Explicit guidance: 'Use generate_message for small or interactive batches; use this only when the record count is large enough that blocking would matter.' This tells when to use this tool vs. the alternative.

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

• list_message_typesA
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• parse_camt053A
  4.9/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.