Standard VAT rate changes across the EU

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

Annotations already cover safety (readOnly, idempotent, non-destructive), but the description adds genuine behavioral context: newest-first ordering, the per-change payload (old rate, new rate, first day of new rate), the 2016-01-01 coverage floor, and a data-freshness cutoff of 2026-10-04. This goes beyond what the annotations convey, though it does not discuss pagination or result size.

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-loads what the tool does, then usage, then output fields and data caveats — every sentence carries information. It is slightly dense, with the data-checked date and release caveat adding length, but nothing is pure 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?

Given an output schema exists, the description need not explain return values, yet it still names them. Combined with scope, ordering, coverage window, and freshness, an agent has everything needed to call and interpret this 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 description coverage is 100%, so the baseline is 3. The description restates the two filters ('optionally for one country and/or since a date') without adding format or edge-case detail beyond the schema's 'YYYY-MM-DD' and country-code notes.

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 ('List the changes of the standard VAT rate across the EU') with scope, ordering, and the exact fields returned. It is clearly distinguishable from siblings like get_standard_rate and get_rate_history, which return a rate or a full series rather than a change log.

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 a concrete trigger question ('which EU countries changed their VAT rate this year?') and a scoping exclusion ('Standard VAT rates only (not reduced rates), from 2016-01-01'). It does not explicitly name a sibling as the alternative for adjacent questions, 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.