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

Annotations already cover readOnly/idempotent/openWorld, and the description goes well beyond them: it discloses x402 pricing (0.003 USDC), the API-key credit alternative, a free daily quota, and the data sources (CBS, Kadaster). It also flags the differing aggregation levels (neighbourhood WOZ vs municipal sale prices), which is exactly the kind of trait that prevents misreading results.

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?

Sentences are front-loaded: trigger first, then what is returned, then scope caveat, inputs, sources, and cost. Dense but every sentence carries information; the payment sentence is slightly packed with two mechanisms (USDC and API credits) plus a free tier.

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 returns, and it does: WOZ with trend, yearly municipal sale prices benchmarked nationally. Missing only minor practicalities such as units/currency or the time granularity of the WOZ trend.

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 both parameters are already described with examples, so the description adds nothing except restating 'postcode or CBS buurt code'. It does not clarify that both parameters are optional in the schema but that one is effectively needed, which is the one genuinely useful thing it could have added.

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?

Opens with a concrete trigger and resource: average WOZ in the neighbourhood plus average sale prices per municipality vs national. It also draws a boundary ('Context for an asking price, not a valuation of one home'), which separates it from valuation-oriented siblings like nl_home_report. It never names a sibling, so differentiation is implied rather than explicit.

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?

'Use when the user asks what homes cost in a Dutch area' gives a clear activation condition, and 'not a valuation of one home' provides an explicit exclusion. What's missing is routing guidance toward alternatives (nl_home_basic, nl_rent_check) when the user actually wants a single property or rent.

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