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

Beyond the readOnly/idempotent annotations, the description discloses deep behavioral nuance: bic: null collapses three distinct meanings, authoritative is only trustworthy for CH/LI/DE regisries, match prefix with candidates > 1 signals possible mis-assignment, bic.address is the legal seat and may differ from the register city, and LEI null means 'no file on record' not 'none exists'. It even discloses cost and the 'does not confirm account exists or ownership' limitation. 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 it is front-loaded with purpose and uses clear section labels — USE WHEN, PREFER OVER, RETURNS, LIMITS, IMPORTANT, COST — that make it scannable for an agent. Nearly every sentence carries opational value; the main bloat is the field-by-field enumeration of the return struct (address { street, post_code, ... } that duplicates the existing output schema, 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 high semantic complexity and an existing output schema, the description is exceptionally complete: it covers the three-way null-BIC interpretation, country-specific authoritative register rules, match ambiguity, SEPA/VoP return fields, risk indicators, account-verification caveats, and even cost/free-tier behavior. There is no example or explicit non-European-IBAN boundary, but the 'European IBAN' scope plus exhaustive caveat coverage leaves very little to inference.

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 iban parameter including automatic space/hyphen stripping, so the baseline is 3. The description adds only a marginal input-format hint in the USE WHEN section ('any string starting with two letters and digits') and says basically nothing else about parameter semantics 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 first sentence gives a specific verb+resource+scope: 'Verify whether a European IBAN is valid AND enrich it with bank, compliance and routing data.' The enrichment clause clearly separates it from validation-only or lookup-only siblings like lookup_bic and check_ compliance.

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?

An explicit 'USE WHEN:' list enumerates seven concrete trigger scenarios, from 'user mentions an IBAN' to 'pastes any string starting with two letters and digits,' and 'PREFER OVER LOCAL VALIDATION (mod-97 checksum)' gives a reasoned when-not to use local fallback. The description does not, however, name sibling tools such as lookup_bic or check_ compliance as explicit alternatives when those are the correct choice, so it stops short of 5.

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