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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds genuine behavioral context by describing exactly what a response contains (last value, prior period, year-ago value, recent measurements, CSV link) and flagging the 'waar gemeten' caveat that some points may be missing. Since no output schema exists, this payload description is doing real work. It omits granularity/frequency details (how many 'laatste metingen', what period each step covers).

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 what the tool returns, then the series list, then the municipality caveat — a sensible order for an agent scanning it. Dense but every clause carries information; the series enumeration duplicates the enum in the schema and is the only clearly redundant element.

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 read tool with no output schema, the return-value description is solid, but the municipality behaviour is left ambiguous (does it return that municipality's series, or filter rows?) and the list of municipality-capable series is materially incomplete versus the schema. Those two gaps matter because gemeente is the only non-trivial decision an agent makes here.

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 schema already documents both parameters. The description adds the municipality dimension and its scope, but this is where it conflicts with the schema: it claims gemeente applies to five series (vacatures, brandweer, energielabels, misdrijven, woninginbraken) while the enum description allows eight, adding inwoners, nieuwbouw and bijstand. That omission risks steering an agent away from valid requests.

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 the resource precisely (a NuActueel-measured figure over time) and enumerates the return payload: latest value, the period before it, a year earlier where measured, recent measurements and a CSV link. It even enumerates the 15 supported series, which tells an agent concretely what is retrievable. It stops short of naming a sibling tool, so the boundary with e.g. 'files', 'vacatures' or 'energie_stand' must be inferred from the enumeration.

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: the enumerated series and the note that some of them are available per municipality tell an agent what can be requested, but there is no explicit 'use this when…' versus an alternative sibling such as vacature_index or files. 'Waar gemeten' hints that data can be absent, but no fallback behaviour is specified.

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