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

With only a title annotation, the description carries the full burden and does so thoroughly. It discloses return behavior (free preview only, never full report), size limits (5MB decode, 20,000 rows), cost structure, checkout flow, and that it never pays automatically. This is 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 long but well-structured, with the core purpose front-loaded and sections for USE WHEN, HOW, LIMITS, RETURNS, and COST. Every section earns its place; though it could be trimmed, the density is justified by the tool's complexity.

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

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

The description covers everything an agent needs: what it does, when to use it, how to call it (including encoding and filename), what it returns (even naming fields), limits, pricing, and the checkout/polling flow. Given the output schema exists, it also explains return values beyond the schema, making it fully complete.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds practical meaning: it instructs to base64-encode the raw bytes without a data: prefix, explains that the filename extension decides parsing, and clarifies the lang default. This enriches the schema without redundancy.

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: 'Audit an entire creditor/supplier payment file (CSV or XLSX) row by row' and lists the exact checks performed. It also distinguishes itself from single-IBAN tools by noting checks that 'a single IBAN call cannot make', making its scope 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?

The 'USE WHEN' section explicitly tells when to call this tool: when the user has a spreadsheet/export of creditor accounts and wants it checked before payments, or when they use phrases like 'audit my creditor file'. It also implicitly excludes single-IBAN use by contrasting with those tools, giving clear selection 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 non-destructive behavior, and the description adds rich behavior beyond them: the download is non-null only when paid AND `session_id` matches the paying session, and payment confirmation can happen immediately via `session_id`. 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 purpose, uses labeled sections (USE WHEN, RETURNS, COST), and every sentence earns its place. It includes the return condition and the session_id nuance without fluff.

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

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

For a two-parameter read-only status tool with an output schema present, the description covers when to use it, what it returns, the conditional download availability, and the payment-confirmation edge case. No critical behavior an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters well. The description reinforces that `session_id` comes from the Checkout success redirect and can avoid webhook delay, but this largely mirrors the schema's own parameter descriptions rather than adding substantial new meaning.

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

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

The description states a specific verb and resource: 'Check the status of a creditor-file audit job created by audit_creditor_file.' It also defines the core return value ('whether it is paid, and the download link once it is'), which cleanly distinguishes it from the creating sibling tool.

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

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

It gives an explicit 'USE WHEN' trigger: following up on a `job` id after a human may have paid through the Checkout URL. It also explains when to pass `session_id` to avoid waiting for the webhook. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds crucial behavioral context beyond that: the 100-IBAN limit, the cost structure (USDC per IBAN, or credits/requests), and the exact return shape (results, count, valid_count, cost_usdc). No contradiction with annotations.

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

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

The description is well-structured with clear sections (first sentence, USE WHEN, RETURNS, COST). It front-loads the core action and then provides decision-relevant details. Every sentence adds value—no fluff or redundancy—making it appropriately concise for a complex batch tool.

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

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

For a tool with a single array parameter, an output schema, and cost implications, the description is complete. It covers when to use it, what it returns, the cost model, and the limit. The agent has everything needed to invoke it correctly without additional lookups. The output schema is not shown but the return shape is explicitly described.

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

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

The input schema covers the only parameter (ibans) with a clear description and constraints (1-100 items). The tool description does not add additional parameter-level meaning beyond restating the array and limit; it focuses on usage and cost. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Validate up to 100 IBANs in a single call.' It clearly distinguishes itself from the sibling validate_iban by emphasizing the batch nature and the explicit contrast in cost and usage. The purpose is unambiguous and immediately actionable.

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' scenarios (pasted lists, cleaning CSVs, deduping databases, triaging payout lists) and directly names the alternative (validate_iban) with a threshold ('more than 2-3 times in a row'). This gives the agent precise decision rules for tool selection.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this by calling it 'informational triage only' and noting it 'never' checks the payee's name. It also discloses the tool's scope and limitations (not regulated). However, it doesn't explicitly state that the tool is read-only or doesn't access external real-time data beyond what is implied, but given the strong annotation coverage, the description adds sufficient context.

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

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

The description is comprehensive but structured with clear sections (USE WHEN, NOT A, CHECKS, RETURNS, COST) making it easy to scan. It front-loads the purpose and usage, with detailed return info at the end. Every sentence adds value, though it's slightly long, but the structured format keeps it efficient.

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

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

Given the tool's complexity (multiple checks, risk scoring), the description is thorough. It details all checks performed, the return object with fields, and even the cost. The output schema exists, so description needn't list every field, but it highlights key ones. The description covers prerequisites (payment intent) and boundaries (not regulated). Nothing an agent needs to decide when to use this tool is missing.

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

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

The schema already describes the 'iban' parameter fully (100% coverage), but the description adds crucial context about what the tool does with that IBAN (e.g., checks against sanctions lists, returns risk score). It clarifies that the IBAN is used for more than just validation, enhancing the parameter's meaning beyond a simple string input.

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

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

The description clearly states the tool's purpose: running a pre-flight compliance triage on an IBAN, specifically for payment risk assessment. It is distinguished from siblings like validate_iban (which likely only validates IBAN format) and lookup_bic, by emphasizing sanctions screening and risk scoring. The verb 'run' and resource 'compliance triage' are specific and unambiguous.

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

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

The description includes explicit 'USE WHEN' examples and clearly states what the tool is NOT for (regulated AML/CFT screening), directing users to alternative tools (Refinitiv, Acuris, ComplyAdvantage). It also clarifies the boundary between this tool and the payee's bank for name checks, preventing misuse.

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?

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: data source provenance (GLEIF + national registers), the January 2018 SWIFT directory caveat, that only GLEIF rows carry an LEI, monthly refresh, and a cost. This is high-value behavioral transparency.

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

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

The description is longer than minimal but well-structured with labeled sections (USE WHEN, DO NOT USE, BACKED BY, RETURNS, COST). It front-loads the core purpose and keeps each section purposeful. The live counts link and cost are slightly extra but useful for agent decision-making.

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 simple one-parameter schema, rich annotations, output schema, and clear sibling context, the description covers everything an agent needs: what it does, when to use it, when not to use it, important data caveats, and return fields. No critical gaps.

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

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

Schema coverage is 100% and the input schema already describes the BIC parameter with format and examples. The description repeats the format and examples but does not add significant new meaning about the parameter beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description uses a specific verb ('Resolve') with a clear resource ('BIC/SWIFT code') and states the output fields (bank name, country, city, LEI, address). It clearly distinguishes itself from validate_iban by explicitly saying it is not for IBAN inputs.

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 (user has a BIC/SWIFT, asks which bank, location, or LEI) and an explicit DO NOT USE for IBAN with the named alternative 'validate_iban'. This is ideal 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?

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: the data source and refresh cadence (SIX BankMaster monthly), the live count link, the exact return shape, validity date, cost, and that it covers all BankMaster IIDs. This is exactly the kind of supplementary behavioral context that helps an agent decide and invoke.

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 organized into labeled sections (USE WHEN, BACKED BY, RETURNS, COST) that each carry useful decision-making information. It is front-loaded with the core purpose and expands into details an agent would need. Minor redundancy exists between the payment-rail enumeration and the RETURNS block, but nothing is wasted.

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

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

Given the single parameter, the presence of an output schema, and the read-only annotations, this description is complete: it covers when to call, what it resolves, what it returns, the source and freshness, cost, and applicability. An agent has enough context to select and invoke the tool correctly without additional external research.

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 describes the single `iid` parameter fully, including the 1-to-5 digit range, leading-zero stripping, and an example. The description reinforces the semantic context but does not add new parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Resolve a Swiss BC-Nummer / IID ... into the underlying institution.' It clearly distinguishes itself from a plain name/BIC lookup by noting it returns full payment-rail participation, and the sibling context makes the differentiation useful.

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 explicit, concrete triggers: Swiss BC-Nummer/IID mentions, CH/LI IBAN clearing codes, Swiss instant transfer routing, QR-IID resolution, and institution classification. It also excludes non-CH/LI accounts, but it does not explicitly name an alternative tool such as lookup_bic for when only a name or BIC lookup is needed.

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

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

The description is exceptionally transparent about polling behavior, retry semantics, and the one-time nature of the approved key. It also explains every possible response state and the correct agent action for each. Because annotations carry no behavioral hints, this description fully compensates.

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 highly structured with clear labeled sections: USE WHEN, HOW TO CALL IT, and WHAT THE ANSWERS MEAN. Every sentence conveys essential operational information with almost no filler.

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

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

For a polling tool with multiple response states and retry rules, the description covers all necessary scenarios: pending, approved, denied, expired, and invalid grant. It also clarifies the cost/allowance behavior, leaving no ambiguity about how to handle this tool correctly.

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

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

Schema coverage is 100% for the single optional parameter, and the description repeats the schema's guidance about leaving device_code empty to reuse the last request. It adds helpful calling cadence context but not new parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb+resource pair ('Collect the API key') and grounds it in the prior step ('request opened by request_api_key'). It clearly identifies the tool's distinct role among siblings like request_api_key.

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 states the exact precondition: call request_api_key and show the code to the human. It also gives concrete polling guidance ('once per minute is enough, never in a tight loop'), which tells the agent how to behave in practice.

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

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

With only a title annotation, the description carries full behavioral burden and meets it: it reveals that the tool starts a multi-step approval flow, that results must be read via `status`, that it is free and does not count against the allowance, and that the agent must not open links or fill forms. This goes well beyond a simple 'request an API key' statement.

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 structured with USE WHEN and WHAT YOU MUST DO sections, all critical instructions are front-loaded, and every sentence carries actionable information. No filler or repetition that detracts.

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 two optional parameters and a rich output, the description fully covers the decision to call, the post-call handling, the verbatim display requirement, and the prohibition on agent actions. It also clarifies that the tool works even after the allowance is exhausted, leaving no ambiguity.

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?

Both parameters (reason, client_name) are optional and already have descriptions in the schema, so the 100% schema coverage carries the meaning. The tool description adds context that these appear on the approval page but does not add new semantic content beyond the schema.

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

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

States a specific verb+resource: 'Start the process that gives this session its own free IBANforge API key'. This clearly distinguishes it from sibling tools like validate_iban or poll_api_key, and names the follow-up tool explicitly.

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

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

Includes an explicit 'USE WHEN' section with concrete triggers: 'you used up the free allowance, a call answers 402, or you are about to run more than a handful of validations.' It also names the alternative/follow-up poll_api_key and gives negative instructions, so an agent knows exactly when to call it.

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

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

With only a title annotation, the description carries the full behavioral burden, and it delivers: the tool is free, does not count against the allowance, works even after the allowance is spent, is read by a human, and offers on-chain refunds for verified data errors. This is rich behavioral context 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 front-loaded with purpose, followed by a clear 'USE WHEN' section and then high-value behavioral facts. Every sentence earns its place; the length is justified by the operational context an agent needs before sending feedback.

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 schema coverage and presence of an output schema, the description covers the essential operational context: what to report, when to report it, whether it costs anything, how it is handled, and what refund behavior applies. Nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters thoroughly. The description reinforces the high-level purpose of the error_type categories and mentions quota/payment blockers, but it does not add meaningful parameter-level detail beyond the schema.

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

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

The description states a specific verb and resource: 'Report a problem or a need directly to the IBANforge operators.' It enumerates concrete use cases (incorrect validation, stale data, latency, payment blockers) and is clearly distinct from all sibling validation/lookup/audit tools.

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

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

The description provides an explicit 'USE WHEN' section with concrete triggers: wrong-looking results, missing data, or a quota/payment/capability wall. It does not explicitly name alternatives or state when not to use the tool, but the context is clear enough for an agent to route correctly.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds substantial behavioral context: data provenance flags like 'basis says where the bank code to BIC pairing came from', 'authoritative', licensing conditions that must travel with data, and explicit limits about account existence. The rate-limits and x402 payment details also set accurate expectations about cost and access.

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 nearly every sentence carries operational value: use cases, field semantics, limitations, licensing, and cost. It is front-loaded with the core purpose and usage triggers. It could be broken into clearer sections rather than one dense block, which keeps it from a 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 tool with rich output and multiple edge cases, this description is complete: it explains the meaning of advisory vs authoritative BIC data, the GB modulus check behavior, official identity fields, next steps, and limitations. The presence of an output schema means return values do not need to be restated, and nothing an agent needs to safely invoke this tool is missing.

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

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

There is only one parameter and schema description coverage is 100%, so the schema already documents the input fully. The description adds general context about what the IBAN can include and how the result is enriched, but it does not need to compensate for an underspecified parameter, making the baseline 3 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: 'Verify whether an IBAN from any IBAN country is valid AND enrich it with bank, compliance and routing data.' It clearly separates this tool from related siblings by naming its enrichment capabilities (SEPA reachability, VoP, issuer type, clearing details) and by explicitly contrasting it with local mod-97 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 'USE WHEN' section enumerates concrete triggering conditions, and 'PREFER OVER LOCAL VALIDATION' explicitly tells the agent when this tool is the right choice relative to a simpler alternative. It also states what the tool does NOT do (confirm account existence or ownership), which prevents misuse.

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 show readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe. The description adds meaningful behavior beyond those hints: the pairing-verdict independence ('valid and pairing are INDEPENDENT verdicts'), the paid POST route when iban is supplied, the cost in USDC, the ambiguity resolution mechanism, and explicit instruction to relay source/as_of for auditability. 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 long but information-dense and earns its length: it covers schemes, ambiguity, pairing, cost, and unverifiable cases with clear topical markers. It is front-loaded with the primary purpose and USE WHEN/DO NOT USE guidance before lower-level scheme details. It could be slightly tightened, but no sentence is filler.

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

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

Despite having an output schema, the description covers what would otherwise be gaps: scheme-domain knowledge, ambiguity handling, independence of valid and pairing verdicts, the unverifiable case instruction, and the cost-bearing POST route. For a tool with 3 parameters, complex scheme logic, and a paid path, the description is adequately complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value above that baseline by explaining the scheme ambiguity (e.g., a bare 12-digit string is both Belgian OGM and a legal Finnish length), clarifying the passthrough behavior of the reference normalization (spaces/slashes stripped), and explaining the iban parameter's pairing effect and cost implication. It adds interpretive meaning rather than restating 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 uses a specific verb-resource pair ('Validate a structured payment reference') and immediately distinguishes the tool's scope from its sibling validate_iban by explicitly stating 'DO NOT USE to validate the IBAN itself — that is validate_iban.' It also enumerates the schemes and recognition modes, so an agent can tell exactly what is and is not this tool's job.

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 ('when assembling a payment instruction from an invoice, a QR-bill or a remittance advice; whenever a Swiss IBAN and a reference appear together') and when-not-to-use ('DO NOT USE to validate the IBAN itself') guidance, names the alternative tool, and gives a cost-based routing consideration. It also instructs not to relay 'unverifiable_without_creditor_config' verdicts as invalid, which is a critical usage rule.

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