ibanforge

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

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: detailed cost per IBAN, free tier limits, the exact return shape ({ results, count, valid_count }), and a note that results match validate_iban's shape. No contradictions with annotations.

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

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

The description is longer than average but well-structured with clear 'USE WHEN', 'RETURNS', and 'COST' sections. Every sentence contributes either usage guidance, return details, or pricing. The cost explanation is a bit detailed but relevant for decision-making. It is efficient despite the length.

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?

Combined with the output schema and annotations, the description provides everything needed to call the tool correctly: purpose, batch limit, trigger conditions, return shape, and cost considerations. There are no missing pieces that would cause an agent to misuse it.

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 describes the 'ibans' parameter as an array of 1-100 strings (100% coverage). The description repeats the 'up to 100' limit but does not add format, examples, or edge-case guidance beyond what the schema provides. This meets the baseline of 3 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 states a specific verb ('Validate'), a resource ('IBANs'), and a clear batch constraint ('up to 100 IBANs in a single call'). It also distinguishes itself from the sibling validate_iban by highlighting the batch nature and cost advantage, so an agent can immediately tell it apart.

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' scenarios: pasting a list, cleaning a CSV/spreadsheet, deduping a customer database, triaging a payout list. It also gives a concrete decision rule: use instead of validate_iban when calling it more than 2-3 times in a row, and notes the cost difference. This fully covers when-to-use and alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. The description adds valuable context beyond annotations: it details the check scope (sanctions, FATF, SEPA Instant reachability, VoP), explains the risk_score range and flags, and explicitly discloses the cost per call ($0.02). This level of disclosure exceeds what annotations alone 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 longer than average but well-structured with labeled sections (USE WHEN, NOT, CHECKS, RETURNS, COST). Key triggers are front-loaded, and the cost and free-tier details are at the end. It earns its length because each section conveys actionable information; however, some details like the free API key URL could be considered marginally ancillary, so it is just short of 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?

For a compliance-checking tool, the description covers the full context an agent needs: when to use it, what it checks, what it returns (including risk score semantics), and its cost. An output schema exists, so return-value explanation is not required, and the description still summarizes the return structure well. No critical information 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 only parameter 'iban' has full schema coverage with description 'IBAN to check', so the schema fully documents the parameter. The description does not add additional format requirements or constraints beyond the schema, but it does give context on how the IBAN is used in the checks. Given 100% coverage, 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: 'Run a full pre-flight compliance check on an IBAN before sending a SEPA / cross-border payment.' It clearly distinguishes itself from sibling tools by focusing on compliance triage, sanctions screening, and risk scoring, which no other sibling covers. The purpose is unambiguous and operational.

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 lists USE WHEN conditions including specific user intents like 'is this IBAN safe to pay?' and scenarios like SEPA Instant transfer success. It also gives a NOT A REGULATED AML/CFT PRODUCT exclusion and names alternatives (Refinitiv, Acuris, ComplyAdvantage) for regulated screening. This gives an agent clear decision rules for when to invoke this tool versus alternatives.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), and the description adds substantive behavioral context: verdict semantics ('not_applicable... never counts as a pass', 'conforms is true when no finding failed'), the deliberate cbpr+ omission with rationale, and the auditable source-string requirement. No contradiction with annotations; the read-only framing aligns perfectly.

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?

Long, but deliberately structured with labeled sections (USE WHEN, DO NOT USE, SCHEMES, VERDICTS, IMPORTANT, FREE, COST) and the core purpose front-loaded in the first sentence. The verdict-semantics and scheme-rationale sections are essential for correct invocation and interpretation; only the cost paragraph approaches borderline content, and it is clearly delimited.

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 full output schema, a nested input object, and both required params at 100% schema coverage, the description covers everything an agent needs: when to use, when not to, scheme identities, verdict semantics, the cbpr+ gap, auditability requirements, and cost. Even the November 2026 regulatory timeline orients the agent on why the check matters.

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 documents every field, satisfying the baseline. The description still adds value by expanding the scheme enum with publishing bodies ('sps (Swiss Payment Standards, SIX), hvps_plus (HVPS+ / T2, ECB), fedwire (Federal Reserve)') and explaining the deliberate absence of a cbpr+ option. The address sub-fields need no repetition since the schema already describes them fully.

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

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

States a specific verb and resource: 'Check a structured ISO 20022 postal address against a payment rail's published address rules, rule by rule, each verdict citing the document it comes from.' The DO NOT USE clause ('not postal reality') sharply distinguishes it from address-verification tools and from the sibling validate_iban/validate_payment_reference pair.

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 an explicit USE WHEN condition ('assembling a payment instruction... with a creditor or debtor address, to learn whether the rail accepts it BEFORE submitting') and an explicit DO NOT USE exclusion ('to verify that a street or town EXISTS'). It also instructs the agent on what to do with the output ('relay each finding's source string'), which is actionable usage guidance beyond mere 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 readOnly, idempotent, and non-destructive; the description goes further by disclosing rule-by-rule checking, citation of the SIX source per finding, special handling for combined addresses (proposed_structured), the full return contract, and cost/rate-limit behavior. No annotation contradiction.

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 portion earns its place and is scannable through explicit labels (USE WHEN, DO NOT USE, RETURNS, IMPORTANT, COST). Core purpose is front-loaded in the first sentence.

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 regulation-heavy validation tool, it covers use case, exclusions, deadline, return schema, required source relay, and cost. An agent has enough context to call it correctly and to route non-matching needs to validate_iban.

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 documents the payload structure to 100% (SPC line by line), so the baseline is 3. The description adds only the semantic framing that the payload is the text a QR-bill's code carries and starts with SPC, without adding new parameter format or edge-case details.

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 opening sentence names a specific verb ('Check'), a concrete resource ('a Swiss QR-bill payload'), and a distinguishing trait: it processes the SPC text rule by rule, citing SIX documents. This separates it from siblings such as validate_iban and validate_payment_reference without needing to open their 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?

It gives explicit USE WHEN conditions (scanned/generated QR-bill before paying or issuing, reference-IBAN matching, S vs K address forms) and an explicit DO NOT USE with the alternative (paid validate_iban). It also names the exact deadline context that should drive an agent to this 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?

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds substantial behavioral context: data sources and refresh cadence ('121,000+ BIC entries... refreshed monthly'), coverage limitations ('where available'), and cost/free-tier details including a link to generate a free API key. This goes well 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 longer than minimal, but well-structured with clear sections (core function, USE WHEN, DO NOT USE, BACKED BY, COST) and front-loaded with the primary purpose. Every section carries useful operational information. It is slightly verbose but earns its place, especially the cost and alternative-routing details.

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 what the tool does, when to use it, when to use a sibling, data sources, refresh cadence, cost, free-tier limits, and API key generation. With an output schema present, return-value documentation isn't needed. The definition is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% (the only parameter 'bic' is described as 'BIC/SWIFT code (8 or 11 chars)'). The description enhances this by specifying 'alphanumeric', providing concrete examples ('UBSWCHZH80A', 'DEUTDEFF'), and repeating the length constraint. The additional examples and format detail justify a score above the baseline of 3.

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

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

The description opens with a specific verb and resource: 'Resolve a BIC / SWIFT code into the underlying bank: name, country, city, LEI, and registered head-office address'. It clearly differentiates from the sibling validate_iban by explicitly stating 'DO NOT USE for IBAN inputs — call validate_iban instead'. An agent can easily understand what this 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 description explicitly states when to use it ('USE WHEN: the user already has a BIC/SWIFT... and asks which bank it belongs to, where the bank is, or its LEI for compliance/regulatory matching') and when not to ('DO NOT USE for IBAN inputs — call validate_iban instead'). This provides clear routing to the correct sibling tool, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context like data source (SIX BankMaster, refreshed monthly), depth of data (payment-rail participation), and cost per call. However, it does not disclose potential errors (e.g., invalid IID, not found) or response behavior in edge cases, but given strong annotations and output schema, a 3 is appropriate.

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

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

The description is dense and front-loads the core purpose and use cases. It includes multiple sections (USE WHEN, data source, RETURNS, COST) that are each relevant. It is longer than strictly necessary and repeats some information (e.g., 'CH and LI' appears twice), but every section adds operational value for an agent deciding to invoke the 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 single-parameter lookup tool with a rich output schema and clear annotations, the description covers the main context: when to use, data depth, source, existence of output schema, cost, and regional scope. Minor gaps include what happens on invalid IID or how the 'valid_on' field behaves, but the output schema handles return structure and the annotation set handles safety. Overall sufficiently complete for effective 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% for the single required parameter 'iid' — the schema already documents 'Swiss IID (1-5 digit number)'. The description reinforces this by mentioning 'BC-Nummer / IID (1 to 5 digits)' and noting QR-IID resolution, but adds no format or validation details beyond the schema. Baseline 3 is justified.

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 ('Resolve') and resource ('Swiss BC-Nummer / IID'), and immediately distinguishes the tool by listing precise use cases (IBAN clearing code, SIC/euroSIC routing, QR-IID, institution classification). It clearly differentiates from sibling lookup_bic by focusing on Swiss clearing data, not generic BIC 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 lists trigger conditions (user mentions BC-Nummer, CH/LI IBAN, SIC routing, QR-bill, classification) and states that it is 'Only relevant for CH and LI accounts', effectively providing exclusion criteria. This makes the decision boundary clear without needing to inspect sibling schemas.

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 are minimal (only title), so description carries full burden. It discloses that the tool is free, does not consume daily quota, works after limit, a human reads each report, and paid data errors are refunded on-chain. This provides useful behavioral context beyond the title 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?

Five sentences, front-loaded with purpose, then usage triggers, then behavioral notes. Every sentence adds distinct value, no redundancy. Efficient and well-structured.

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

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

Covers purpose, usage guidelines, key behavioral traits, and ties to parameter schema well. Output schema exists so return values are handled. Could mention that reports are anonymous if contact is omitted, but overall complete for a feedback tool.

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

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

Schema description coverage is 100% with all 7 parameters described. The description adds context like types of issues but does not enhance individual parameter meanings beyond schema. For example, 'error_type' enum values map to listed scenarios, but no extra guidance on format or examples 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?

Description clearly states the tool's purpose: 'Report a problem or a need directly to the IBANforge operators.' It lists specific scenarios (incorrect validation, missing data, latency) and distinguishes from sibling tools (validation/lookup) by focusing on feedback and operational issues.

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

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

Explicitly states when to use with 'USE WHEN' clause covering data errors, missing data, or blockers. Mentions it is free and does not count against daily free-tier limit. Does not explicitly mention when not to use or list alternatives, but the context of siblings makes the distinction 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 already mark the tool as read-only, idempotent, and non-destructive. The description goes well beyond this by detailing return semantics (e.g., bic: null collapsing three cases), authoritative flag meaning, LEI/address sourcing, cost per call, and free-tier limits. It also clarifies that validation does not confirm account existence or ownership. 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 well-structured with clear sections (USE WHEN, RETURNS, LIMITS, IMPORTANT, COST) and high information density. Every section earns its place given the tool's complexity, yet the length could be slightly trimmed to improve quick scanning for an AI agent.

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

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

The description is exceptionally complete for a tool that returns complex nested objects. It explains the meaning of key return fields (basis, authoritative, bic.address vs bic.city), handles edge cases (null BIC, not_in_register), and provides operational context (cost, free tiers, SEPA/VoP). Combined with the existing output schema, an agent has everything needed to call and interpret the tool correctly.

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

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

The input schema fully describes the single parameter 'iban' (with a description that notes spaces/hyphens are stripped). Since schema coverage is 100%, the description adds little parameter-specific semantics beyond what is already present, though the overall tool behavior enriches the meaning of the parameter in context.

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 ('Verify... AND enrich it with...') and clearly identifies the resource (European IBAN) and the added value (bank, compliance, routing data). It also distinguishes itself from siblings by listing the exact use cases and comparing with local 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 explicitly enumerates trigger scenarios, and the 'PREFER OVER LOCAL VALIDATION' section explains when not to use a mod-97 checksum instead. This provides clear guidance on when to select this tool over alternatives, including a direct comparison with batch_validate_iban and other siblings.

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 declare readOnlyHint=true and idempotentHint=true; the description goes far beyond by disclosing the independent valid/pairing verdicts, the unverifiable_without_creditor_config status for KID/OCR, and the ambiguity-resolution behavior (also_valid_as). It also explicitly warns not to call an unverifiable KID/OCR 'invalid,' which is a critical behavioral trait. 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 every section earns its place: USE WHEN, DO NOT USE, scheme specifics, ambiguity rules, pairing rule, cost model. It is front-loaded with the primary purpose and most critical operational guidance. The structure uses clear capital-letter section labels and short imperative sentences, making it scannable despite its density.

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 tool is complex with multiple schemes, pairing logic, and edge cases; the description covers all meaningful behavioral aspects, including the return fields (valid, pairing, source/as_of), the cost ($0, free tier quotas), and how it fits with sibling tools. Since an output schema exists, the description doesn't need to enumerate return fields, but it mentions the auditable fields, making it complete for an agent to decide and correctly interpret results.

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?

Although schema descriptions cover 100% of the 3 parameters, the description enriches meaning for each: reference explains stripping of spaces/slashes/+++ wrapper; iban's connection to the pairing rule is clarified; reference_type is given a usage hint ('Pass reference_type when you know the country') and a list of allowed values. The description also explains the interaction between iban and reference types, which no schema field could express.

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 opens with a specific verb-resource pair: 'Validate a structured payment reference and, when an IBAN is supplied, decide whether the two may legally travel together.' It clearly distinguishes from the sibling validate_iban by stating 'DO NOT USE to validate the IBAN itself — that is validate_iban.' The use cases (invoice, QR-bill, remittance advice) further define the tool's scope.

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

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

The description provides explicit USE WHEN scenarios, a DO NOT USE directive with the exact alternative tool name, and even explains the boundary for recognized-but-unverifiable schemes (Norwegian KID, Swedish OCR). It tells the agent exactly when to invoke this tool versus validate_iban, and when not to relay an unverifiable result as invalid.

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