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?

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 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?

The description discloses substantial non-obvious behavior beyond the readOnly/idempotent annotations: it does NOT confirm the account exists or belongs to a person, 'passed false' does not make valid false, a BIC outside a national_register pairing is advisory, and source/free_of_charge license conditions must travel with the data. These caveats directly prevent an agent from overclaiming results.

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 USE WHEN, PREFER OVER, RETURNS, LIMITS, and COST sections, and it is front-loaded with the core purpose. Some embedded clarifications, such as the modulus and official_identity field semantics, are dense, but they earn their place given the enrichment output.

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 is remarkably complete: it covers what the tool does and does not do, explains authoritative vs advisory BIC data, defines edge-case semantics like checked false, warns about payee verification, includes licensing obligations, and mentions cost/API-key conditions. The output schema covers return shape, while the description supplies the surrounding context an agent needs to use the result safely.

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 documents the sole iban parameter with 100% coverage, including acceptance of spaces/lowercase and an example. The description reinforces that a user string starting with two letters and digits is a trigger, but it adds little parameter syntax or format 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?

The description opens with a specific verb-resource pairing: 'Verify whether a European IBAN is valid AND enrich it with bank, compliance and routing data.' It goes beyond a generic validate statement by enumerating the kinds of enrichment (BIC, issuer type, SEPA, VoP, risk indicators) and explicitly contrasts itself with local mod-97 checks, so an agent can distinguish it from validation helpers and sibling lookups.

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 an explicit 'USE WHEN' trigger list covering mentions of IBANs, typo checks, bank identification, neobank/EMI detection, SEPA reachability, and VoP, and it says to PREFER it over local mod-97 validation because mod-97 cannot resolve BIC/SWIFT or compliance risk. It does not explicitly compare against sibling tools like lookup_bic or batch_validate_iban, so the alternative guidance is partially complete.

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.