vat_validate

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

With no annotations, the description carries the full burden and does well: it discloses the live VIES source, that a national format check runs first, that company name/address are returned only where the member state discloses them, and that the call is not charged when the member state service is unavailable. Pricing ($0.0045) and p99 latency (6000ms) are also given. It still omits error/non-found behavior and any auth or rate-limit notes.

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 key facts (what it validates, source, format pre-check, billing behavior, params, cost, latency) are front-loaded into a compact block with no filler. The trailing param/cost/latency list is slightly listy and overlaps the schema, but each item is decision-relevant for an agent weighing the call.

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 validation tool with no output schema and no annotations, the description covers the source of truth, return fields, partial-disclosure caveat, billing exception, cost, and latency. Only failure modes (invalid format, number not found, timeout) are left unaddressed, a minor 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 coverage is 100%, so the baseline is 3. The description adds concrete prefixed examples (NL004495445B01, DE811569869) and spells out the two accepted input shapes ('vat_number with prefix' or 'vat_number + country_code'), which meaningfully clarifies how the two parameters interact beyond the field-level 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?

The description names a specific verb and resource ('Validate an EU VAT identification number live against the official EU VIES service') and scopes it precisely to EU VAT IDs, which cleanly separates it from siblings like iban_validate, email_validate, and phone_validate. An agent can identify the tool's domain 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?

It gives clear context for invocation: the number may be passed with a country prefix or with a separate country_code, and it notes 'EL for Greece, XI for Northern Ireland' via the schema. There is no explicit when-not or named alternative (e.g. versus iban_validate for bank accounts), 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.