Invoice & Payment ID Validator

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the description's job is to add context — it does, explaining the decision output, the plain-English reasons, the specific fraud patterns detected, and that live=true performs an external VIES registry lookup (consistent with openWorldHint). It does not mention latency, rate limits or failure behavior when VIES is unreachable, which is the main remaining gap for a network-dependent tool.

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?

Front-loaded with the decision ('One call before paying a supplier') followed by what is checked, what it catches, and the minimal-input rule. It is dense but every sentence carries distinct information; no restatement of the name or title.

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?

There is no output schema, so the description must carry the return contract — and it does, naming the three verdict values and the accompanying plain-English reasons. Combined with the fraud patterns and the live-lookup caveat, an agent has enough to call and interpret the result without further documentation.

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 eight fields and baseline would be 3. The description adds non-obvious semantics the schema cannot express: all fields are optional and 'only one field is needed', and the tool degrades gracefully on partial invoice data — that materially changes how an agent should populate the arguments.

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 ('validates the IBAN, BIC, VAT and EIN ... cross-checks them against each other') and a concrete output ('verdict pay / review / hold'), which cleanly separates it from the single-field siblings validate_iban, validate_bic, validate_eu_vat, validate_gb_vat and validate_ein. An agent can tell this is the aggregate/combined check without opening any schema.

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

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

'One call before paying a supplier' gives clear situational context, and 'Pass whatever the invoice has; only one field is needed' tells the agent how to invoke it with partial data. It strongly implies it supersedes the per-field validators but never names them or states an explicit when-not (e.g. 'use validate_iban alone if you only want syntax checking'), so it stops short of a 5.

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, so the safety profile is covered. The description adds substantive behavioral context beyond that by naming the actual validations performed (8/11-char structure, ISO country, test-BIC flag) and the cross-country fraud signal. It stops short of describing failure behavior or return shape.

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?

Two tightly packed sentences, front-loaded with what is validated and followed by the optional cross-check. Every clause carries information; nothing is padding.

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 no output schema, the description carries the burden of explaining what the caller gets back, and it does not — an agent cannot tell whether this returns a boolean, a structured check breakdown, or throws on invalid input. The input side is fully covered, but the result side is a real gap.

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 3; the description earns above it by explaining the purpose of the optional iban parameter (country match as a fraud/typo signal), which adds rationale the schema's terse 'cross-check country' does not convey.

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 precise verb (validate) plus the resource (BIC/SWIFT code) and even enumerates the checks performed: structure, ISO country, test-BIC flag. Against siblings like validate_iban and validate_ein the resource boundary is unmistakable without opening any schema.

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

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

The description gives conditional guidance for the optional parameter ('Pass the IBAN too and it checks...'), which is genuinely useful, but it never states when an agent should reach for this tool versus an alternative or what workflow it fits (e.g. pre-payment verification). Usage is implied rather than spelled out.

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, non-destructive and closed-world behavior, so the description's real contribution is the caveat that EINs have no check digit and validation therefore catches typos and fake prefixes but not every invalid number. That is exactly the limitation an agent needs before treating a pass as proof of a real EIN. It stops short of describing the return value or any rate/permission considerations.

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?

Two tight sentences; the positive statement of what is validated comes first and the scope caveat second. No filler, boilerplate, or restatement of the tool name.

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 one-parameter read-only validator this covers what is checked and how far the result can be trusted. With no output schema present, the description is slightly short of fully self-sufficient because it never says what a result looks like (boolean, normalized EIN, or failure reason).

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 a single parameter with 100% schema description coverage ('EIN, with or without dash') plus a format example, so the schema carries the burden. The description's '9-digit format' phrasing is about validation logic rather than the input's accepted syntax, adding little beyond the schema. Baseline 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?

States a specific verb (Validate) and resource (US Employer Identification Number) and even specifies the exact checks performed: 9-digit format and a valid IRS campus prefix. Against siblings named validate_bic, validate_iban, validate_eu_vat and validate_gb_vat, the resource noun alone makes it unambiguous which validator to pick.

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?

Usage is only implied: an agent should call this when it has an EIN to check. No explicit when-to-use, when-not-to-use, or named alternative is given, though the single-purpose nature and distinctive resource name make misrouting unlikely.

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 (which already cover readOnly/idempotent/openWorld), the description discloses operationally important behavior: offline vs registry-backed checking, throttling risk on the live path, the fields the live path can return, and — most valuable — that failures surface as vies.checked=false rather than a false 'invalid'. That failure semantic is exactly the kind of context annotations cannot carry.

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?

Two sentences with zero filler; the default behavior is front-loaded and the live-mode caveats are packed into a single parenthetical. Every clause carries information the agent needs.

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?

There is no output schema, and the description partially compensates by naming the fields the live path returns and the failure signal. It does not describe the shape of the offline result (e.g. what a valid/invalid format check returns), leaving a small gap for a tool whose callers must interpret the response.

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, but the description earns extra credit by explaining the tradeoff of live (slower, throttled, extra returned fields) and clarifying that value carries a country prefix and is validated against 27 states + XI. It adds real meaning over the one-line schema descriptions.

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 (validate an EU VAT ID) plus the exact scope (27 member states + XI) and the two modes of operation. The scope cleanly separates it from siblings like validate_gb_vat and validate_ein without the agent needing to open any schema.

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

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

Explicitly tells the agent when to flip live=true and why not to by default: it is slower and may be throttled, while the offline check is the default. It does not explicitly route the agent to sibling validators (e.g. GB numbers belong to validate_gb_vat), so it falls just short of full alternative guidance.

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

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

The annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely useful behavioral context: the specific validation passes performed, including format, branch/government/health-authority type handling, and the HMRC mod-97 / 9755 checksum. It does not describe what the tool returns, which is a minor gap given there is no output schema.

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

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

A single front-loaded sentence that names the action, the target, and the exact checks performed. Every clause earns its place with 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 one-parameter, read-only validation tool with full schema coverage, the description gives enough to invoke it correctly and understand what it checks. The only shortfall is the absence of any hint about the response (e.g., boolean or reason codes), which matters because no output schema exists to fill that gap.

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 a single parameter with 100% schema coverage, so the schema already documents 'value' including an example ('GB980780684'). The description adds the format prefix context (GB) but no syntax or normalization details beyond what the schema and its example convey, which is the expected baseline when the schema does the heavy lifting.

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 ('Validate') plus a precisely scoped resource ('a UK (GB) VAT registration number'), and the parenthetical GB qualifier cleanly separates it from the validate_eu_vat sibling. An agent can identify exactly what this tool operates on without opening the schema.

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

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

Usage context is only implied: the agent infers it should be used when validating a UK VAT number. Given the sibling list contains validate_eu_vat and validate_ein, an explicit statement of when to prefer this over the EU variant would have earned a higher score, but no such routing is provided.

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 this a read-only, idempotent, non-destructive operation, so the safety profile is covered. The description adds genuine extra value beyond that: the specific validation rules applied and the dual success/error return shape (normalized IBAN, country, BBAN, or machine-readable error codes).

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?

Three tight sentences, front-loaded with the operation and checks, then the return shape, then the usage cue. No redundant or filler text.

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 validation tool with no output schema, the description covers what is validated, the accepted input (implied by schema), and the return payload including error codes. Nothing 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% and the schema already documents the single 'value' parameter with an example and 'spaces allowed' note. The description only clarifies that the value is an International Bank Account Number, adding little beyond the schema, so the 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?

States a specific verb (Validate) and resource (IBAN), and enumerates the actual checks performed: mod-97 checksum, per-country length, SEPA membership. This clearly distinguishes it from siblings like validate_bic, validate_ein, and the VAT validators.

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?

Gives a concrete use context ('before paying an invoice or saving supplier bank details'), which is clear guidance. It does not, however, name alternatives or exclusions (e.g., 'use validate_bic for the BIC counterpart'), so it stops short of full routing guidance.

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