ibanforge

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond annotations: the batch limit of 100, cost per IBAN, and the return shape including count and valid_count. It does not cover partial failure behavior, but the references to 'same shape as validate_iban' imply per-IBAN validity 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 well-structured with clear labels ('USE WHEN:', 'RETURNS:'). Every sentence serves a purpose: stating the operation, cost benefit, use cases, and return format. It is concise despite covering several aspects, with no 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?

The tool is simple (one parameter) and benefits from an output schema (marked as present). The description explains the return shape explicitly (results array, count, valid_count) and references the sibling validate_iban for shape consistency. Combined with schema and annotations, the agent has all necessary information to invoke it 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 description coverage is 100% (the only parameter 'ibans' is fully described as 'Array of IBANs (1-100)' in the schema). The description repeats this constraint without adding new meaning or usage details beyond what the schema provides. The minimum viable baseline of 3 applies.

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 'Validate up to 100 IBANs in a single call' with a specific verb, resource, and scope. It distinguishes from sibling tool validate_iban by highlighting the batch capability and cost efficiency.

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 provides 'USE WHEN' scenarios, listing specific cases like pasting a list, cleaning CSV/spreadsheets, deduping, or triaging payout lists. It also gives a clear threshold ('more than 2-3 times in a row') when to prefer batch over single validation, and implicitly indicates single IBANs should use validate_iban.

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, so the description's job is to add context. It clearly states the informational-only nature, the exact checks performed (OFAC, FATF, SEPA Instant, VoP), and the return structure including risk_score semantics and flags. 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?

Well-structured with clear sections (purpose, USE WHEN, NOT, CHECKS, RETURNS). Front-loaded with the main purpose. Every sentence adds value, and the length is justified by the tool's complexity. No redundancy or 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?

Given the single parameter, high schema coverage, safety annotations, and presence of an output schema, the description is comprehensive. It covers usage scenarios, limitations, exact checks, and return values. Even without the output schema, the description provides a detailed preview of the response object.

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% with 'IBAN to check', so the baseline is 3. The description does not add additional parameter meaning or format details; it only reinforces that the IBAN is the subject of the compliance check. No new information 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?

Specific verb+resource: 'Run a full pre-flight compliance check on an IBAN'. Clearly distinguishes from siblings by focusing on compliance (sanctions, reachability, VoP) rather than plain validation or lookup. Includes the payment context and use cases.

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' section lists concrete scenarios (about to send payment, asks about IBAN safety, sanctions screening, SEPA Instant success, risk score). Gives an explicit exclusion: 'NOT A REGULATED AML/CFT PRODUCT' and names alternative tools (Refinitiv, Acuris, ComplyAdvantage).

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 false. The description adds behavioral context beyond these: it notes that fields are returned 'where available', discloses the data sources and refresh frequency ('121,000+ BIC entries... refreshed monthly'), and implies completeness limits. This adds value without contradicting 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 slightly longer than minimal but well-structured with labeled sections (USE WHEN, DO NOT USE, BACKED BY). Each part contributes useful context: purpose, usage boundaries, and data reliability. It is front-loaded and not verbose, earning a high but not perfect score due to the data-source background not being strictly necessary for tool invocation.

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, the presence of an output schema, and comprehensive annotations, the description covers all needed aspects: main purpose, when to use, when not to use with an alternative, data coverage, and refresh cadence. No significant gaps remain for an agent to correctly select and invoke this 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 coverage is 100% (one parameter with a description). The description adds semantic value by specifying the allowed format '8 or 11 chars, alphanumeric' and providing concrete examples ('UBSWCHZH80A', 'DEUTDEFF'). This helps the agent validate input beyond the schema's generic length statement.

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 verb 'Resolve' and the resource 'BIC/SWIFT code', listing the specific output fields (bank name, country, city, LEI, address). It explicitly distinguishes itself from siblings by stating 'DO NOT USE for IBAN inputs — call validate_iban instead', and the context of IBAN vs BIC differentiates it from validate_iban.

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

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

The description provides explicit 'USE WHEN' conditions ('user already has a BIC/SWIFT... asks which bank it belongs to, where the bank is, or its LEI') and a clear exclusion with a named alternative ('DO NOT USE for IBAN inputs — call validate_iban instead'). This goes beyond implied usage and directly guides the agent on when to select 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond these: data source ('SIX BankMaster'), refresh cadence ('refreshed monthly'), coverage ('1,100+ entries'), and the return structure. However, it does not disclose error behaviors for invalid IIDs or rate limits, but the existing annotation coverage lowers the bar.

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 clearly labeled sections (USE WHEN, data claims, RETURNS, scope). It is front-loaded with the core purpose and uses the space efficiently. The promotional phrase 'THE DEEPEST SWISS CLEARING DATA IN ANY PUBLIC API' is somewhat unnecessary but not distracting. Overall, every section earns its place for 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?

For a single-parameter lookup tool with an output schema, the description is exceptionally complete. It lays out the exact return fields (institution, address, bic, payment_services, sic_iid, qr_iid, valid_on), specifies the data source and refresh cycle, and enumerates the use cases. Nothing essential is missing for an agent to decide when and how to invoke 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?

Input schema describes the only parameter as 'Swiss IID (1-5 digit number),' which covers 100% of the schema. The description adds the synonym 'BC-Nummer / IID,' reiterates the digit range, and specifies that it applies only to CH and LI institutions, giving additional meaning beyond the bare schema definition.

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: 'Resolve a Swiss BC-Nummer / IID (1 to 5 digits) into the underlying institution.' It clearly differentiates from sibling tools like lookup_bic by emphasizing Swiss-specific data and payment-rail participation, and the USE WHEN section further clarifies its niche.

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 an explicit 'USE WHEN' list covering multiple concrete scenarios (e.g., user mentions BC-Nummer, pastes a CH/LI IBAN clearing code, asks about Swiss instant transfers, QR-IID resolution). It also provides a when-not via 'Only relevant for CH and LI accounts.' Although it doesn't name sibling alternatives directly, the scope and triggers are explicit.

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 destructiveHint=false, but the description goes far beyond with rich behavioral context: it explains the meaning of null BIC (collapsing multiple cases), the authoritative vs. non-authoritative bank code checks, the match prefix ambiguity, and the limit that it does not confirm account ownership or existence. This provides significant value beyond the structured 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 sections (USE WHEN, PREFER OVER, RETURNS, LIMITS, IMPORTANT) and front-loaded with purpose and usage. Every paragraph adds value, though some sections (especially the IMPORTANT note on null BIC) could be trimmed without losing critical information. Slightly verbose but organized.

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 (validation, enrichment, SEPA, compliance, risk indicators), the description covers all major aspects: return fields, edge cases (null BIC, not_in_register semantics), limitations, and disambiguation of match. The existence of an output schema and the detailed RETURNS list make this description fully sufficient for an agent.

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 parameter 'iban', and the schema already describes that spaces/hyphens are stripped automatically. The description does not add additional parameter-specific meaning beyond examples in the USE WHEN list, so it relies on the schema. 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 clear, specific statement: 'Verify whether a European IBAN is valid AND enrich it with bank, compliance and routing data.' It goes beyond a tautology and distinguishes the tool from siblings like lookup_bic (which likely only resolves BIC) and check_compliance (which may focus on compliance checks) by combining validation and enrichment.

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' list covering many scenarios, and it contrasts with local mod-97 validation, explaining why this tool is preferred. However, it does not mention sibling tools like batch_validate_iban or lookup_bic as alternatives, so an agent might not know when to choose those instead (e.g., for batch processing).

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