Opa Haardhout

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

Annotations already cover the safety profile (readOnly, idempotent, closed-world), so the bar is lower. The description still adds real behavior: phone numbers are deliberately masked to the last two digits, and the optional context field never changes the response. It does not cover error behavior for an invalid or unknown slug, which keeps it from a 5.

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 content is front-loaded with the core purpose first, which is good. However, the full Dutch and English versions duplicate every sentence rather than condensing to one language or a shorter bilingual form, roughly doubling length without adding information for the caller.

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?

An output schema exists, so return values need not be spelled out, yet the description summarizes the profile contents helpfully. Combined with annotations and the schema, an agent has everything needed to call it correctly; only failure modes for a bad slug are unaddressed.

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 both parameters are already documented in the schema, including the slug pattern and the context no-op caveat. The description restates that the lookup is by slug but adds no format or validation detail beyond the schema, so the 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 and resource ('Haal het volledige publieke profiel van één haardhout-aanbieder op met slug') and enumerates exactly what the profile contains: offering, price list, contact details, reviews, photos. It is clearly distinguishable from the sibling zoek_aanbieders, which is named as the discovery tool rather than the fetch tool.

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 routes the agent to zoek_aanbieders to obtain the slug, which is the main precondition for calling this tool. It also states an attribution requirement ('Vermeld bij gebruik: Bron opahaardhout.nl'). It lacks an explicit 'do not use when' case, but the single-purpose fetch use case is clear.

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 establish readOnlyHint, idempotentHint and a closed-world dataset, so the safety profile needs no explanation. The description does add genuinely useful semantics beyond them: what each band contains (median, p25, p75, min, max, n) and the crucial caveat that null means insufficient data rather than zero price. It remains silent on freshness or the period the benchmark covers, which matters for a price 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?

The key framing (what the prices are, how markets are split) is front-loaded before the structural detail and the null caveat. The full NL/EN duplication is wasteful for an agent, though it plausibly serves human readers and the Dutch attribution rule. No sentence is otherwise 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 an output schema present and no parameters, the description only needs to set expectations, and it does: scope, segmentation, band composition, and the null-means-sparse-data rule. The one meaningful omission is any statement of the reference period or update cadence, which an agent needs to judge whether these prices are current.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly avoids inventing parameter-like filtering language, implicitly signalling that all segments come back in one response.

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 states a specific resource and measure: firewood price benchmarks in EUR per m³, per wood species and market-wide, split by local/private sellers vs. webshops. That is far more than a restatement of the name. It stops short of naming which sibling (e.g. houtsoort_info) covers species characteristics rather than prices, so differentiation is inferable 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?

There is no explicit when-to-use, when-not, or alternative-tool guidance; the agent must infer that this tool answers price questions while zoek_aanbieders and aanbieder_details answer listing questions. The remark that the two markets 'verschillen fors' hints at picking the right segment, but that is interpretive guidance, not tool-selection guidance. Only the attribution instruction ('Vermeld bij gebruik: Bron opahaardhout.nl') functions as an operational directive.

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 a closed world, so safety is covered. The description adds context beyond them: what each profile contains and the source-attribution obligation that affects how the result should be presented. It doesn't mention pagination or result ordering, but with 15 fixed species that is a minor omission.

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?

Each language block is one tight sentence listing fields plus one for invocation and one for sibling routing; nothing is padding. The cost is that the full content is duplicated across NL and EN, roughly doubling length, though that appears to be an intentional bilingual convention rather than 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?

An output schema exists, so the field list is a helpful overview rather than a required return-value explanation. Input behavior, alternative tool routing and attribution are all present. Complete enough for a single optional-parameter lookup tool.

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 enum plus its description already explain that the field is optional and what omission means. The description restates that same omit-vs-supply behavior in both languages without adding format or syntax detail. Baseline 3 is appropriate when the schema carries the semantics.

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 states a concrete resource and verb ('brandprofielen en stooktips per houtsoort') and enumerates the dimensions covered (warmte, brandduur, droogtijd, kWh/kg, vonkvorming, rook, geschiktheid). It explicitly distinguishes itself from the sibling houtprijzen, so an agent can pick the right tool 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?

Both invocation modes are spelled out: omit the argument to get all species, supply one to get a single profile. It also routes price questions to houtprijzen and adds an attribution requirement ('Vermeld bij gebruik: Bron opahaardhout.nl'), which is guidance an agent would otherwise have no way to know.

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 only reveal that this is a non-destructive write; the description goes much further by disclosing that failures never block the answer, that the report cannot affect ranking or result ordering, that reports steer re-verification priority, and that emails/phone numbers in free text are stripped. It also explains the 60-day staleness threshold and the conditional price band.

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 opening is well front-loaded with timing and optionality, but the entire body is duplicated verbatim in Dutch and English, roughly doubling length without adding information. The bilingual approach may serve the audience, but the repetition is heavy for a five-parameter feedback tool.

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 an output schema and full annotation set already present, the description covers everything else an agent needs: when to call, that it is non-blocking, that it never alters results, and the attribution line required when using it. Nothing material is left unexplained.

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 every parameter is already documented in the input schema, which sets the baseline at 3. The description reinforces the intent of the report (freshness caveat, price band when a wood species appears in the query) but adds no parameter-level detail the schema lacks.

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 states a specific verb and object ('meld optioneel welke vermeldingen relevant waren' / 'report which listings you actually used') and immediately describes what comes back. It is clearly a post-answer feedback tool, distinguishable at a glance from the four search/info siblings.

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?

Timing guidance is explicit ('Na het beantwoorden van je gebruiker'), and optionality is stated three times ('vrijwillig, nooit verplicht, blokkeert nooit'). What is missing is any mention of the sibling tools or of a situation where an agent might reasonably choose not to call it beyond 'never required'.

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 cover read-only, idempotent and closed-world, so the bar is lower; the description still adds real behavior: distance sorting appends afstandKm, a radius drops sellers with unknown locations, and zoekintentie never affects results. It also states the attribution requirement ('Bron opahaardhout.nl'), which no structured field carries.

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 lead information (verb, scope, filters, distance mechanics, attribution) is front-loaded and useful, but the full text is duplicated verbatim in Dutch and English, roughly doubling length with no incremental meaning for an agent.

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 15 optional parameters, an output schema and full annotation coverage, the description supplies what structured data cannot: distance-versus-radius interaction, the afstandKm side effect, exclusion of location-less sellers, and the source attribution. Only the sibling-choice context 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%, so every parameter including the postcode/lat-lng exclusivity and the enum vocabularies is already documented. The description restates the filter set and distance mechanics without adding syntax or format detail beyond the schema, which is the baseline 3 case.

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 ('Zoek haardhout-aanbieders in Nederland') and even quantifies scope (563 indexed), so the agent knows exactly what it queries. Sibling differentiation is left implicit – it never says how it differs from aanbieder_details or houtprijzen – which keeps it out of 5 territory.

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 concrete mechanical guidance: pass a postcode OR lat+lng to sort by distance and optionally afstand to cut off far-away sellers. It does not say when to prefer this tool over aanbieder_details or the other siblings, nor when not to use it, so usage is implied rather than routed.

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