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

The description thoroughly discloses behavioral traits: returns preview only, never pays automatically, always requires human checkout for payment, and outlines the exact return structure and limitations. No contradiction with the title-only annotation.

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 long but well-structured with clear sections (purpose, when, how, limits, returns, cost). Each sentence adds value, though some redundancy exists (e.g., base64 encoding mentioned twice), preventing a perfect score.

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

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

Despite having an output schema, the description provides an excellent overview of the return fields (job, preview, summary, etc.), cost structure, payment process, and limitations, giving a complete picture for effective usage.

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 already covers all parameters with descriptions (base64 encoding, filename extension, lang, checkout). The description reiterates these points but adds no new semantic meaning beyond what the schema provides, warranting the baseline score for high schema coverage.

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 audits an entire creditor/supplier payment file with specific checks (IBAN, BIC, SEPA, etc.) and explicitly distinguishes it from single-IBAN checks, making its purpose unambiguous.

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

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

It explicitly provides 'USE WHEN' conditions (batch file checking before payments) and explains the payment flow, including when to use checkout and how to poll status, giving clear guidance on appropriate usage.

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

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

Beyond the readOnly and idempotent annotations, the description discloses specific behaviors: the download field is non-null only when paid AND session_id matches, and that session_id bypasses webhook delays. This adds transparency about the tool's internal logic.

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 clear sections (USE WHEN, RETURNS) and each sentence serves a purpose. It is informative without being redundant, condensing important details about parameters and conditional behavior into a compact format.

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 has an output schema (not shown) and the description mentions what fields are returned (free-preview fields, paid, paid_at, download), it provides enough context for a caller to understand the response. The description also covers the special session_id handling, making it complete for usage.

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 descriptions already cover both parameters, but the tool description adds crucial context: job is the id from audit_creditor_file, and session_id is the Stripe Checkout session id from the success redirect, explaining its role in confirming payment immediately.

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 that the tool 'checks the status of a creditor-file audit job' and explains it returns payment status and download link. It distinguishes from siblings by referencing the job created by audit_creditor_file, making its purpose unique and specific.

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

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

The description explicitly says 'USE WHEN' and details the scenario: following up on a job id after a human may have paid through Checkout URL. It also explains when to pass session_id to confirm payment immediately, providing concrete usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add value beyond that. It adds per-IBAN cost, the 100-IBAN limit, and the return summary fields, which are useful behavioral details. No contradiction with annotations.

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

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

The description is front-loaded with the core capability, then gives explicit usage triggers, return shape, and cost. Every sentence serves a distinct purpose, and the structured sections make it easy to scan.

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

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

Given the rich annotations, complete input schema, and an output schema, the description adds exactly what is missing: cost model, batch limits, return-summary fields, and when-to-use guidance. Nothing an agent needs to select and call this tool correctly is omitted.

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 already fully documents the single parameter with min/max constraints and a description, so the baseline is 3. The description adds contextual usage and pricing but does not materially redefine the parameter's semantics.

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?

Description states a precise action ('Validate up to 100 IBANs in a single call') on a specific resource, and explicitly contrasts with validate_iban. The tool's purpose and scope are unmistakable.

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

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

Provides explicit 'USE WHEN' conditions including pasting lists, cleaning CSVs, deduplicating databases, and triaging payout lists, plus guidance on when not to use it (repeated validate_iban calls). Names the sibling alternative 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?

Annotations already mark the tool read-only, idempotent, and non-destructive, so the bar for added behavioral context is satisfied amply. The description discloses the material limitation that sanctions screening is at the BANK/BIC8 level and does not screen beneficiary names, and it states the cost (0.02 USDC) and the exact set of checks performed. This goes well beyond the annotations.

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

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

The description is long but every section earns its place: USE WHEN, regulatory disclaimer, SCOPE limitation, CHECKS, RETURNS, and COST. It is front-loaded with the action and use case, and the structured format makes the information easy to parse without 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?

For a compliance tool that has one parameter, an output schema, and meaningful limitations, the description is complete. It covers when to use it, when not to use it, what it checks, what it returns, its bank-level scope limitation, its cost, and alternatives. Nothing an agent needs to decide whether and how to invoke it is missing.

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

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

Schema description coverage is 100%, so the single 'iban' parameter is already fully documented in the schema. The description adds useful context about what the check covers and returns, but it does not add parameter-level format, normalization, or validation semantics beyond the schema. Baseline 3 is appropriate because the schema carries the parameter burden.

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

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

The description opens with a specific verb and resource: 'Run a full pre-flight compliance check on an IBAN before sending a SEPA / cross-border payment.' It clearly distinguishes itself from siblings like validate_iban by enumerating the additional compliance checks (sanctions, reachability, VoP, risk score) and noting that it returns validate_iban fields plus a compliance object.

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 USE WHEN section gives explicit triggering scenarios such as payment risk triage, sanctions screening requests, SEPA Instant reachability questions, and numeric risk score needs. It also explicitly warns that this is NOT a regulated AML/CFT product and names alternatives (Refinitiv, Acuris, ComplyAdvantage), giving the agent clear routing guidance.

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

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

The description adds substantial behavioral detail beyond the annotations: verdict semantics (pass/fail/not_applicable), the meaning of 'conforms', and the requirement to relay each finding's source string for auditability. It also discloses note behavior, cost, and routing, which are non-obvious traits not inferable from 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 long but tightly organized with scannable labels (USE WHEN, DO NOT USE, SCHEMES, VERDICTS, IMPORTANT, COST), ensuring key guidance is front-loaded. Every section earns its place by addressing selection, behavior, or output interpretation, and there is no filler or redundancy.

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

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

Given the tool's complexity, the description covers usage context, exclusions, scheme availability, verdict interpretation, output auditability, cost, and routing. The presence of an output schema means return-value details are already structured, so the description does not need to restate them; nothing an agent needs to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is already high. The description adds valuable semantics by explaining scheme meanings and providing domain guidance (e.g., SPS forbids sending adr_tp) that is not fully captured in the schema. It does not repeat field-level descriptions, which is appropriate given the schema's completeness.

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 uses a specific verb ('Check') and specifies the exact resource (structured ISO 20022 postal address) and subject (payment rail's published address rules). It clearly distinguishes the tool's purpose from its siblings by emphasizing rule-by-rule conformity checking with citable verdicts, rather than general validation or lookup.

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 'USE WHEN' section explicitly names the triggering scenarios (assembling pain.001, Fedwire, or T2 instructions) and the 'DO NOT USE' section explicitly excludes postal-reality verification, preventing misuse. It also names the supported schemes and explains the deliberate absence of 'cbpr+', giving concrete selection criteria.

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 important runtime behavior beyond annotations: it returns structured findings with source strings, derives proposed structured addresses from combined addresses, and routes to a free POST endpoint. No conflict with readOnly/idempotent annotations 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?

The description is long but organized with USE WHEN, DO NOT USE, RETURNS, IMPORTANT, and COST sections. A few phrases are slightly redundant, but most sentences carry essential operational detail, and the 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?

The description fully covers the tool's inputs, outputs, special transformations, routing, cost, and operational context, including how to relay findings and what to do with combined addresses. Nothing needed for correct invocation appears missing.

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

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

The schema already covers the single payload parameter well, and the description adds meaning by noting it is the QR-code text starting with SPC and contains line breaks. Together they provide complete parameter understanding.

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

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

Clearly identifies the tool's function: checking a Swiss QR-bill payload for well-formedness, reference/IBAN compatibility, and address structure. It distinguishes itself from related tools like validate_iban by explicitly stating what it does not do.

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

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

Provides explicit when-to-use guidance (before paying or issuing a QR-bill), when-not-to-use guidance (for bank-account lookup use validate_iban), and contextual rules such as the 2025/2026 transition dates for address types.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior, so the bar for additional context is met by the description's specifics: 121k+ BIC entries, 38k+ LEI-enriched via GLEIF, monthly refresh, and 0.003 USDC cost. It also says fields are returned 'if available', setting expectations about completeness. No contradiction with annotations.

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

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

The description is compact despite covering purpose, usage, exclusions, data provenance, return fields, and cost. Information is front-loaded in a scannable label format. Each sentence contributes actionable meaning, and there is no filler or 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?

For a single-parameter lookup tool with strong annotations and an output schema, the description is fully sufficient. It explains when to use, when not to use, what data backs the tool, what will be returned, and the cost. Nothing an agent needs to decide 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%, and the schema already documents the BIC parameter with format and examples. The description repeats the same examples and 8/11-character format without adding new parameter-level meaning. It does clarify the output mapping, but the parameter itself is already well-defined in the schema, so a baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Resolve a BIC / SWIFT code into the underlying bank: name, country, city, LEI, address.' It clearly differentiates from sibling validate_iban by explicitly saying not to use it for IBAN inputs. This leaves little ambiguity about what the tool does and how it differs from related tools.

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

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

The 'USE WHEN' section gives concrete triggers: the user already has a BIC/SWIFT and asks which bank it belongs to, location, or LEI for compliance. 'DO NOT USE for IBAN inputs — call validate_iban instead' provides an explicit exclusion and names the alternative. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the data source and refresh cadence (1,100+ SIX BankMaster entries, monthly), the breadth of payment rails covered, and a clear cost of 0.003 USDC. This gives the agent useful expectations about freshness, scope, and billing.

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 labeled sections (USE WHEN, BACKED BY, RETURNS, COST) and front-loads the core purpose. Its length is justified by the richness of the lookup results and the use-case list. Minor points: the capitalized claim 'THE DEEPEST SWISS CLEARING DATA IN ANY PUBLIC API' is promotional rather than operational, and some data-depth information is repeated across sections.

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 single documented parameter, an output schema covering return fields, clear use cases, an explicit cost, and scope limitations, the description provides everything an agent needs to select and invoke the tool correctly. The combination of usage triggers, data provenance, and output summary makes this definition complete for its complexity.

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 schema already documents the single 'iid' parameter with format, example, and leading-zero behavior. The description repeats this information without adding significant new semantic detail. Given the high schema coverage, score 3 is the appropriate baseline.

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

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

The description opens with a specific verb and resource: 'Resolve a Swiss BC-Nummer / IID (1 to 5 digits) into the underlying institution.' It clearly differentiates itself from siblings like lookup_bic by emphasizing payment-rail participation, QR-IID allocation, and 'not just a name lookup.' An agent can accurately identify when this tool applies without opening the schema.

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

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

The 'USE WHEN' section provides concrete triggering scenarios: BC-Nummer/IID mentions, CH/LI IBAN clearing codes, Swiss instant transfer routing, QR-IID resolution, and institution classification. It also adds a geographic exclusion ('Only relevant for CH and LI accounts'). It does not explicitly name a sibling alternative like lookup_bic, so it stops short of the full when-not/alternative guidance.

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

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

Annotations contain only a title, so the description carries the full burden of behavioral disclosure. It does this thoroughly: it explains the server may delay up to thirty seconds, the tool must not be called in a tight loop, the key is delivered only once, and each response status implies a specific follow-up action. This is rich, non-obvious behavior that an agent needs to know.

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 long but organized with clear labels (USE WHEN, HOW TO CALL IT, WHAT THE ANSWERS MEAN). Every sentence carries operational value: rate limiting, status interpretation, retry limits, and fallback behavior. The structure front-loads the core purpose before diving into details, making it easy to scan.

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

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

Given the polling complexity, output schema presence, and a single optional parameter, the description covers everything an agent needs: when to call, how often, what each response means, how to handle errors, and the free-tier implications. It even specifies the key is delivered once, preventing a critical mistake. No meaningful context is missing.

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

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

Schema description coverage is 100%, and the input schema already states that device_code is optional and can be left empty to reuse the last request. The description repeats this guidance but does not add meaning beyond what the schema provides. Baseline 3 is appropriate because the schema handles the parameter documentation.

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

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

The description opens with a specific verb and resource: 'Collect the API key once a human has approved the request opened by request_api_key.' This clearly identifies the tool's role and directly distinguishes it from request_api_key, its primary sibling. The title reinforces the same meaning, and the condition (approved request) is explicit.

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 USE WHEN, HOW TO CALL IT, and WHAT THE ANSWERS MEAN sections. It tells the agent exactly when to call poll_api_key, when to wait and retry, when to call request_api_key again, and when to stop entirely. This is far beyond minimal guidance and leaves little 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 contain only a title, so the description carries the full burden. It thoroughly discloses the process: no email required, no leaving the conversation, the key-issuance flow, the need to read `status` first, and the prohibition on opening links or filling forms for the human. It also states that the tool is free and does not count against the daily limit.

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 longer than average but every section earns its place: purpose, usage triggers, result interpretation, required human-facing verbatim display, prohibited actions, and next-step call to poll_api_key. It is structured with labels like 'USE WHEN' and 'WHAT YOU MUST DO WITH THE RESULT,' making it easy for an agent to parse.

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 interactive key-issuance process and sparse annotations, the description is complete. It tells the agent when to call, how to interpret the result, what to show the human, what not to do, and that poll_api_key should follow. Even though an output schema exists, the description adds essential process context that structured fields could not convey.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema: both `reason` and `client_name` are already described in the schema as shown to the human on the approval page. No extra parameter guidance is provided.

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

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

The description states a specific verb and resource: 'Start the process that gives this session its own free IBANforge API key.' It clearly differentiates from siblings by naming poll_api_key as the next step and by emphasizing the key-requesting role rather than validation or lookup.

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 USE WHEN conditions: 'you hit the daily free allowance, a call answers 402, or you are about to run more than a handful of validations.' It also clarifies that the tool works even after the limit is reached. It does not explicitly describe when not to use it or name alternative tools, but the trigger conditions are clear.

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

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

Annotations provide only a title, so the description carries full behavioral burden. It discloses that the tool is free, does not count against the free-tier limit, works after the limit, is read by a human, and refunds verified data errors on paid x402 calls. This is rich and useful beyond the 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?

Four sentences with purpose and USE WHEN front-loaded, followed by the key operational facts. A slight redundancy between the colon list in the first sentence and the 'USE WHEN' examples keeps this from being a perfect 5.

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

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

For a low-complexity feedback tool with a rich input schema and an output schema present, the description covers purpose, when to use, cost/quota behavior, human review, and refunds. Nothing needed to decide or invoke 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 parameters like error_type and notes are already fully documented. The description reinforces categories and links reports to refund eligibility, but it doesn't materially add new parameter-level meaning beyond what the schema provides.

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

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

Opens with a precise action: 'Report a problem or a need directly to the IBANforge operators.' It immediately distinguishes this from the validation/lookup sibling tools by framing it as the human-feedback channel and listing concrete report categories.

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 'USE WHEN' list names triggering conditions: wrong results, missing data, quota/payment/capability walls. It doesn't mention when not to use or alternatives, but for a feedback tool the sibling tools are not substitutes, so 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?

Even though annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds substantial behavior beyond annotations: it clarifies that validation does not confirm account existence, explains the meaning of 'authoritative', warns about licensing conditions that must travel with data, and discloses cost/rate limits. This goes far 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?

The description is extremely long with a large 'RETURNS' section that duplicates much of what an output schema would likely provide. It is well-structured with caps and front-loaded purpose, but it is not appropriately sized; many sentences, especially the detailed return field explanations, could be trimmed or delegated to structured schema documentation.

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

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

The description covers use cases, limitations, country-specific checks, cost/usage limits, licensing conditions, and gives clear guidance on interpreting results (authoritative flags, checked/passed semantics). For a complex tool with a single required parameter, 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%; the input schema already documents the 'iban' parameter with format, accepted spaces/lowercase, and an example. The tool description adds that the user may paste any string starting with two letters and digits, but this is minor. Baseline 3 applies because the schema carries the load and the description doesn't substantially extend parameter semantics.

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

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

The description opens with a specific verb and resource: 'Verify whether a European IBAN is valid AND enrich it with bank, compliance and routing data.' It then enumerates concrete use cases that distinguish it from simple validation, making it unambiguous what the tool does and how it differs from local checksum 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?

The description provides a detailed 'USE WHEN' list with specific triggers and explicitly says 'PREFER OVER LOCAL VALIDATION (mod-97 checksum)' with reasons. However, it does not mention the sibling batch_validate_iban or other alternatives, so it misses the opportunity to disambiguate from a highly likely replacement tool.

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 readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial operational detail: ambiguity resolution via also_valid_as, KID/OCR returning valid:null with status unverifiable_without_creditor_config, independent valid vs pairing verdicts, and billing/routing differences. This far exceeds what annotations alone 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?

The description is long but every section earns its place: schemes, ambiguity, pairing rule, cost, and audit fields are all operationally relevant. Capitalized section labels and front-loaded use/do-not-use guidance make the density scannable rather than 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?

For a complex multi-scheme validator with pairing logic, billing implications, and ambiguous inputs, the description covers all decision-relevant behavior. An output schema exists, so return-value details are not required, and nothing needed to call the tool correctly is missing.

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

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

Input schema already covers 100% of parameters with descriptions and examples, so the baseline is 3. The description adds extra meaning by explaining when to pass reference_type ('when you know the country') and how scheme ambiguity is resolved, enriching parameter usage without repeating 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 a specific verb and resource: 'Validate a structured payment reference and, when an IBAN is supplied, decide whether the two may legally travel together.' It also explicitly differentiates from validate_iban with 'DO NOT USE to validate the IBAN itself', so an agent can select the correct tool without opening sibling schemas.

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

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

There is an explicit 'USE WHEN' block with concrete trigger scenarios (assembling from invoice, QR-bill, remittance advice; Swiss IBAN and reference together; pasted RF/27-digit/+++ block), plus a 'DO NOT USE' exclusion naming validate_iban. This gives unambiguous selection guidance.

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