Zorgverzekering.chat: Dutch health insurance

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

Annotations already declare a safe, idempotent, closed-world read, so the description doesn't need to re-state that. It does add real behaviour the annotations can't: the response includes assumptions (aannames) and warnings such as provisional premiums, children under 18 pay no basic premium or deductible, and the tool frames itself as information rather than advice. It doesn't say anything about computational cost or what a partial/invalid policy id yields, which keeps it short of 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 purpose and outputs are front-loaded in the first sentence and every clause carries information; there is no filler. It is admittedly dense — one very long sentence followed by a second — so an agent has to parse a lot, but nothing is genuinely wasteful.

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, return shape needn't be explained, and the description covers the input contract, safety framing and the no-health-data rule well. The one gap is how this tool relates operationally to get_polis / zoek_basisverzekeringen (where the required policy ids come from), which an agent must infer from the sibling list.

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, but the description still earns more: it constrains the scenario to 1–8 persons with year of birth and chosen policy ids, notes that collectiviteitskorting applies to supplementary only, and states that verwachtGebruik is optional and must never contain diagnoses, medicines or free text. That adds decision-relevant meaning beyond the field 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 opening sentence names a specific verb (calculates) and enumerates exactly which cost components are produced — basic/supplementary premiums, collectiviteitskorting, eigen risico, eigen bijdragen, non-reimbursed care — per person and in total. That scope distinguishes it from the comparison siblings like vergelijk_polissen and vergelijk_jaren, which don't produce an itemised annual total.

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 explicit conditional guidance for the optional care-usage input ('only if the user volunteers it'), a hard exclusion ('Do not ask about health'), and routes the agent to get_intake_schema for the allowed questions and categories. What's missing is any statement of when to prefer this tool over vergelijk_jaren or vergelijk_polissen, so the sibling choice is still left to inference.

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?

Beyond the annotations (already declaring readOnly, idempotent, non-destructive), it discloses result provenance via herkomst (insurer publication, zorgzoeker, cache) plus retrieval dates, and warns contracts can change during the year so the user should confirm with the insurer. It also frames the output as informational, not advice, and clarifies that a null herkomst means no contract data exists rather than a transient failure.

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 core capability is front-loaded in the first sentence, with provenance and the null-herkomst caveat following logically. It is slightly long, and the closing 'information, not advice' sentence is tangential to invocation, though it does clarify the tool's role.

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 read-only lookup tool with a full output schema, the description covers what is needed: inputs' provenance, what a result contains (herkomst and date), what null means, and the staleness caveat. Nothing essential for correct invocation 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 description coverage is 100%, so the schema already documents agbCode, polisIds, zorgsoort, jaar and taal. The description only restates the meaning of a few of these (AGB code, per basic policy, zorgsoort) without adding format, defaults, or edge-case guidance beyond what the schema provides.

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: it checks per basic policy whether an AGB-coded care provider is contracted for a zorgsoort, and reports the reimbursement percentage without a contract. This is clearly distinct from the sibling zoek_zorgaanbieder, which the description implicitly references as the source of the AGB code.

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?

The description gives clear usage context: it points to zoek_zorgaanbieder and zoek_basisverzekeringen as sources for the inputs, and warns that if herkomst is null the dataset has no contract information (status onbekend) and re-calling will not change that. It lacks an explicit 'use this instead of X' exclusion relative to sibling tools, but the workflow and the anti-retry rule are clearly stated.

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, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavior: a hard 500-character cap on the returned passage, the response language default, and the fact that URL, version and date accompany the quote. What it does not disclose is what happens when the bronId or anchor is unknown or the passage exceeds the cap (truncation? error?), which is the main behavioral unknown for a lookup 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?

Three sentences, front-loaded with the resource, size cap and language, then the provenance instruction, then the informational-not-advice framing. Little waste, though the closing disclaimer is longer than it needs to be for the operational guidance it conveys.

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, the description needn't describe the return shape, and the annotations cover the safety profile, so the remaining burden is modest. It discharges that burden well by specifying the character cap, quoting language and provenance of identifiers. Only error conditions and the taal-vs-'in Dutch' interaction are left 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 description coverage is 100%, so each parameter is already documented, including the anchor example 'p.14' and the taal enum. The description's only added semantic is that bronId and anchor come from another tool's bronnen list, which closely restates the schema text for bronId. It also says the passage is 'in Dutch' while the schema exposes an en option, a small imprecision that could confuse an agent about whether taal actually changes the output.

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 pairs a specific verb with a specific resource: it returns a short quoted passage (capped at 500 characters) from an official source document, and enumerates the document types (modelovereenkomst, vergoedingenwijzer, premium overview, government publication). It also states what accompanies the quote (URL, version, date). It never names a sibling such as get_polis or get_wettelijke_parameters, so the boundary with those tools is left to inference.

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 a clear triggering condition: quote and cite exact wording, using a bronId and anchor taken from the bronnen list of another tool response. That establishes the upstream workflow step precisely. It stops short of an explicit when-not or a named alternative for retrieving whole documents rather than a passage.

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?

Beyond the readOnly/idempotent annotations, it discloses meaningful behavior: questions are ordered, each carries allowed values and its mapped Scenario field, and the tool deliberately 'provides information, not advice' with the user signing up with the insurer themselves. That is a substantive scope/liability constraint an agent could not infer from annotations, though nothing is said about the size or format of the returned list.

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 response shape is front-loaded in the first clause and the operating rules follow in short imperatives. The long mid-sentence enumeration of intake topics is dense but each item is load-bearing for planning the conversation, so little could be cut without loss.

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 no explanation, and the safety profile is fully covered by annotations. The description supplies the domain fields, ordering rule and the advice disclaimer, leaving only minor gaps such as whether the questions are re-requestable or stateful across calls.

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 single parameter 'taal' has 100% schema description coverage with its enum and default documented, so the schema already does the work. The description never references language at all, adding no meaning beyond the structured field, making baseline 3 correct.

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 ('Returns the ordered intake questionnaire') and ties it explicitly to its downstream consumer, 'building a Scenario for bereken_jaarkosten'. The enumeration of what the questionnaire covers (insurance year, persons, deductible, collectiviteit, payment term) makes it unmistakable against siblings like bereken_jaarkosten or get_polis.

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 operating guidance: 'Ask only what is needed, in this order', and restricts planned care questions to cases where 'the user offers it', explicitly excluding diagnoses. It implies the follow-up (berecken_jaarkosten scenario building) rather than naming when not to use this tool, so it stops just short of full when/when-not coverage.

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 readOnly, idempotent, non-destructive, and closed-world, so safety is covered. The description does add real domain behavior beyond them: variant=true lines sit under a category but must be excluded from calculations/comparisons, gesloten=true means closed to new customers while existing policyholders retain it, and it sets a scope boundary ('information, not advice'). That is solid added value, though nothing is said about error behavior for unknown or unavailable polisIds.

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?

It is front-loaded with the core action and contains no filler, but the body is one long run-on sentence with a deeply nested parenthetical on dekkingen/variant that is hard to parse on first read. A short bulleted breakdown of the returned components would preserve the content with far less cognitive load.

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 rich single-record read tool with an output schema, an annotated safety profile, and fully described parameters, this is complete: it explains the meaning of non-obvious flags (variant, gesloten), states the source-id/get_bron linkage, and sets scope expectations. An agent has everything needed to call it 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 coverage is 100%, so both polisId and taal are already documented with format, example, and enum. The description adds only indirect meaning — that the summary comes back 'in the requested language' — without new syntax or constraints, so the baseline of 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?

Names a specific verb and resource ('Returns the full record of one basic policy ... or one supplementary or dental package') and enumerates the returned components: premiums per deductible/age band, non-contracted care reimbursement, dekkingen, wachttijd, acceptatie, gesloten, summary, and per-field source id. An agent can immediately separate this single-record detail lookup from the zoek_*/vergelijk_* 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?

Usage is implied rather than stated: the singular record plus the note that each field carries a source id 'that get_bron can quote' signals a follow-up lookup role and a cross-tool workflow. However, the description never says to obtain polisId from zoek_basisverzekeringen/zoek_aanvullende_pakketten first (that hint lives only in the schema), nor when to prefer this over vergelijk_polissen or bereken_jaarkosten.

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?

The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world lookup. The description adds useful behavioral context beyond those annotations: it explains the meaning of provisional status and the scope boundary that this provides information rather than advice. It does not describe error handling or freshness guarantees, but the remaining gap is minor given the strong annotation coverage.

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 description is front-loaded with the core purpose and then lists the returned parameter categories in a dense but useful way. Every sentence contributes relevant scope or usage guidance. It is somewhat long, but the length is justified by the number of distinct statutory parameters covered.

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 that there is an output schema and rich annotations, the description need not explain return formatting. It still provides a complete picture of what is returned, the meaning of provisional status, and the information-not-advice boundary. Nothing an agent needs in order to call this lookup correctly appears to be 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 description coverage is 100%, and the schema already explains that 'jaar' is the insurance year and that users often mean the coming year during switching season, as well as the 'taal' enum. The description reinforces that results are for an insurance year but adds little parameter-specific meaning beyond what the schema already provides. A baseline 3 is appropriate when the schema does the heavy lifting.

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 uses a specific verb and resource: it returns statutory Dutch health insurance parameters for an insurance year. It enumerates the exact contents, including deductible amounts, care exempt from deductible, zorgtoeslag limits, co-payments, premium publication date, and switching deadline, so the agent can confidently distinguish this from calculation and comparison 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?

It explicitly says to use this tool instead of the model's own knowledge for these amounts, which is a strong usage instruction. It also explains that status 'voorlopig' means provisional until parliament has voted. It does not name alternative sibling tools or state when not to use it, so it falls short of full when/when-not/alternatives guidance.

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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. The description adds real context beyond that: the 'provides information, not advice' disclaimer and the note that the user signs up with the insurer themselves, which shapes how the agent should present results. It does not discuss result volume or whether the list is exhaustive per year, which is the only remaining gap.

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?

Three sentences, no filler: the first defines the payload, the second states the routing use, the third sets the advisory boundary. The most actionable information (what you get, why you'd call it) is front-loaded before the disclaimer.

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-only list tool with a full output schema and complete annotations, this description covers everything an agent needs: what is returned, the year scoping, and the intended downstream use of verzekeraarId. No explanation of return values is required because an output schema exists.

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 `jaar` parameter already documents the switching-season interpretation, so the schema carries the parameter burden. The description only implies year-scoping ('for an insurance year') and adds nothing about `taal` or output language selection. Baseline 3 is appropriate when the schema is this complete.

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 specific verb and resource ('Lists all Dutch health insurers') and then enumerates exactly what each record carries: insurer group (concern), policy types (natura, restitutie, combinatie, budget), counts of basic policies and supplementary packages, and ratings with source. This is far more specific than the sibling tools zoek_basisverzekeringen or vergelijk_polissen, so an agent can distinguish them without reading schemas.

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 states the primary use case: 'resolve an insurer name to a verzekeraarId for the other tools', which is exactly the routing information an agent needs to pick this tool before the insurer-specific siblings. It does not, however, name when NOT to use it or contrast it directly with zoek_basisverzekeringen/vergelijk_polissen, so it stops short of full alternative routing.

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, non-destructive and closed-world, so the safety profile is fully covered. The description adds the 'information, not advice' stance and the scope of compared data, which is useful framing for how results should be surfaced. It says nothing about result size, missing-year handling, or errors, so it remains a modest addition.

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?

Three short sentences, front-loaded with the core comparison and its dimensions, then context, then the advisory disclaimer. Nothing is redundant, though the disclaimer sentence is the only borderline one and still earns its place for compliance framing.

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, full parameter documentation and complete annotations, the description only needs to convey purpose and usage framing, which it does. A minor gap is that it doesn't clarify what happens if a year pair isn't available for the policy, but nothing essential for a correct call 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 description coverage is 100%, with jaarA/jaarB, polisId pattern and taal enum all documented in the schema. The description only restates the two-year comparison with an example year pair, adding no format or constraint meaning beyond the schema. Baseline 3 is appropriate.

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 ('shows what changed in a policy between two insurance years') and enumerates the compared dimensions — premium, coverage per category, non-contracted care reimbursement, conditions. This clearly separates it from siblings like vergelijk_polissen (different policies) and bereken_jaarkosten (cost calculation) without needing the schemas.

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 concrete usage context — the switching season (overstapseizoen) and the explanatory goal of why a policy got pricier or lost coverage — plus a clear framing that it informs rather than advises. It never names an alternative tool or an explicit exclusion case, so the agent must infer when to pick vergelijk_polissen or bereken_jaarkosten instead.

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, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds genuine behavioral value by disclosing the output shape ('returns only the differences') and the advisory boundary. It does not say what happens on invalid input, e.g. mismatched years or mixing basic and supplementary ids.

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 the core action and scope, followed by the aspect enumeration and the advisory disclaimer, all in two sentences with no filler. The aspect list with Dutch terms is slightly long but pays for itself by mapping terms to the enum.

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, return values need no explanation, and the description wisely states only the 'differences only' behavior. Combined with rich annotations and full schema coverage this is nearly complete; the only missing piece is failure behavior for year mismatches or mixed policy types.

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's '2 to 4 policies of the same insurance year' and 'all basic policies or all supplementary packages' restate the polisIds schema text, and the aspect list mirrors the aspecten enum rather than adding semantics such as default behavior or cost of narrowing aspects.

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 (compares), resource (policies), cardinality bound (2 to 4), scope (same insurance year) and the exact return shape (only differences, grouped by aspect). An agent can distinguish this from sibling vergelijk_jaren (compares years) or get_polis (single policy) without opening a 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?

Gives clear usage context: 'works for basic policies or for supplementary packages', plus the 'information, not advice' boundary which tells the agent not to present results as a recommendation. It stops short of naming explicit alternatives (e.g. use get_polis for a single policy, vergelijk_jaren for year-over-year), so no true when-not guidance.

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?

Beyond the read-only and non-destructive annotations, it discloses important matching behavior: all requirements must be met, only main coverage lines are checked, extra lines have variant true, and closed packages are omitted. It also explains pagination and limits the tool's role to information rather than advice or enrollment.

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 description is front-loaded with the search purpose and contains no filler, with each subsequent sentence addressing matching, results, exclusions, input constraints, pagination, or scope. It is nevertheless a dense single paragraph, and the detailed return-field list is less necessary because an output schema is present.

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 complex filtered search with ten parameters, the definition supplies the essential matching semantics, representative inputs, result behavior, exclusions, and pagination model. Together with the fully described input schema and output schema, it gives an agent enough context to invoke the 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?

Although schema description coverage is 100%, the description adds useful guidance by connecting eisen to concrete categorie, minAantal, and minBedragCent combinations and prohibiting diagnoses or medicines as category inputs. Some other parameter discussion, such as age-based premiums and limit/cursor pagination, largely repeats the schema.

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 uses a specific verb and resource: it finds Dutch supplementary and dental insurance packages satisfying all coverage requirements. This clearly distinguishes it from siblings for basic insurance, policy retrieval, and policy comparison.

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 usage context through worked physiotherapy and dental examples, and explicitly says to use taxonomy category codes rather than diagnoses or medicines. It does not explicitly route users to alternatives such as zoek_basisverzekeringen or vergelijk_polissen when their needs fall outside this search.

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, non-destructive, closed-world behavior, so the bar is lower, yet the description adds real context: pagination via limit/cursor, that premium is priced at the chosen voluntary deductible, that afsluitUrl is only populated over the REST API, and the meta.sorteersleutel disclosure obligation. The main omission is that it does not warn about the response size or the consequences of a large limit beyond the paginated note.

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 purpose, then results, then filtering/sorting, then the advisory disclaimer, so the most important information comes first. It is a single dense paragraph with some unavoidable jargon repetition of schema field names, but no sentence is truly wasted; splitting into short bullets would improve scanability slightly.

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 10-parameter search with an output schema and full annotations, the description supplies everything still needed to call it correctly: deductible-driven pricing, pagination contract, sort-key reporting, domain caveat that covered care is identical by law, and the non-advisory stance. Return-value details are already in the output schema, and the extra mention of afsluitUrl is a useful quirk rather than redundancy.

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 baseline is 3, but the description adds meaning beyond the schema: eigenRisico is described as the basis for premium pricing and as stacking on the mandatory deductible, minVergoedingNietGecontracteerd is explained as applying to zorgsoort when given and otherwise to all care types, and zorgkeuze is defined via reimbursement of non-contracted care. These are semantic clarifications the enum/description fields only partially convey.

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 specific verb and resource ('Searches Dutch basic health insurance policies (basisverzekering) for an insurance year') and scopes it to basic policies only, implicitly distinguishing it from zoek_aanvullende_pakketten and vergelijk_polissen. It also states what the search actually varies on (premium and provider choice, not covered care), so an agent understands the differentiator without opening a 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?

Gives concrete usage context: filter by type, insurer, reimbursement and zorgsoort, sort by one of three keys, and always report the sort key to the user. It also sets an explicit boundary ('Provides information, not advice: the user makes the decision and signs up with the insurer themselves'). It never names sibling tools like vergelijk_polissen or bereken_jaarkosten as alternatives, so routing between tools is left to inference.

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 readOnly/idempotent/non-destructive/openWorld=false, so the safety profile is covered; the description adds the conditional output trait that a distance is only returned when a postcode is supplied, plus a scope disclaimer (information, not advice) that matters for a consumer insurance context. It says nothing about paging beyond the limit parameter or about empty-result behavior, so it is not exhaustive.

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 purpose, then search axes, then return values, then the workflow handoff and disclaimer — a sensible order with no filler sentences. The closing disclaimer is policy boilerplate that only marginally earns its space.

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 six documented parameters, an output schema and full annotations, the description supplies what the structured fields cannot: the multi-criteria requirement, the distance-on-postcode behavior, and the handoff to check_zorgaanbieder. Missing only pagination semantics and clarification of whether zorgsoort can be used alone.

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 zorgsoort examples and the postcode pattern is already documented; the description largely restates those axes. The one genuine addition beyond the schema is the cross-parameter constraint that at least one of naam/plaats/postcode must be given, and the link between postcode and distance — enough to stay at baseline rather than above it.

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?

"Searches Dutch care providers (zorgaanbieders)... in the national AGB register" gives a specific verb, resource and data source, then enumerates the four search axes (name, city, postcode, care type) and what comes back (AGB code, address, distance). It explicitly routes the agent to check_zorgaanbieder for the follow-up, so it is distinguishable from siblings without opening a 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?

States a precondition ("Provide at least one of naam, plaats or postcode") and the next step ("pass the AGB code to check_zorgaanbieder"), which is real when-to-use guidance and names the alternative tool. It stops short of any when-not-to-use condition and leaves ambiguous whether zorgsoort alone is a valid sole criterion, even though the schema marks nothing required.

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