vhis

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds useful context about the source and nature of the content (licensed advisers, scheme rules, guidance rather than terms), but says nothing about freshness, coverage limits, or what happens when no notes match.

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?

Two compact sentences, front-loaded with the resource and scope, ending on the key disambiguation 'Guidance, not plan terms'. Every clause carries information, with no 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 return-value detail is not required. But with three parameters at 0% schema coverage and no annotation burden relief for input semantics, the description should explain at least the topic filter and the role of brand/question; it does so only obliquely via the content 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 0%, so the description must compensate. It lists content areas that partially overlap the topic enum (underwriting, claims), but never explains the topic, brand, or question parameters, nor how they combine to filter results. Two of three parameters are entirely undocumented in both structured fields and prose.

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 concrete resource (curated notes from licensed advisers and scheme rules) and enumerates the content domains (underwriting, conditions, switching, claims, tax), so an agent knows what it returns. It explicitly contrasts with 'plan terms', differentiating it from plan_terms siblings, though it does not distinguish itself from search/search_plan_terms.

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 phrase 'Guidance, not plan terms' implies the boundary against plan_terms, letting an agent infer when to prefer this tool. However, there is no explicit when-to-use, no stated preconditions, and no naming of the alternative tools, leaving usage largely inferred.

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, so the safety profile is covered. The description adds genuinely new context: a public-server key is required and a missing key yields a key_required response with guidance on obtaining one, which is auth behavior the annotations do not convey.

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 differs and why to use it, then the auth caveat. The telegraphic comma-list style is dense but every clause carries information; nothing is wasted.

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-value explanation is unnecessary, and the description covers the essential extras: the comparison dimensions, usage intent, and the key requirement. What remains missing is explicit routing against sibling tools, but overall it is sufficient to call 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 that comparisons typically need rate-record context and that option_ids come from an earlier result, but the schema already documents age, gender, smoker, and option_ids semantics, adding little beyond 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?

Names a specific verb (compare) and enumerates exactly what is compared: premium now and at 65, next-year range, deductible, room class, limits, area, and each insurer's rate record. This is far more specific than siblings like find_plans or price_plans, so an agent can tell them apart 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?

States clear usage contexts ("which is better", "why is one cheaper") and even gives a behavioral instruction ("state the trade-off and let the person choose"). It does not, however, explicitly name or exclude sibling tools like find_plans or price_plans, so the when-not path 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 indicate this is a write operation (readOnlyHint=false, idempotentHint=false), and the description adds meaningful behavioral context: it emails multiple parties, returns a WhatsApp link and reference, and fails with key_required if no key is present. It does not contradict annotations. It could go further by describing whether the operation is reversible or what happens on duplicate calls, but the disclosed side effects are substantial.

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, each carrying distinct information: what the tool does, when to call it, and what to avoid plus the key failure mode. The most important operational constraints are front-loaded. No filler or repetition of schema fields.

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 tool with 8 parameters and an output schema, the description covers the essential workflow: prerequisites, side effects, the health-detail prohibition, and the key requirement. It doesn't spell out the exact return structure, but an output schema exists, so that burden is reduced. The only notable gap is that it doesn't explicitly say what happens if the person hasn't given consent, though that is strongly implied by 'only call it once they have said they want to be contacted'.

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 only 25%, so the description must compensate. It does: it clarifies that name and a phone/email are prerequisites, that the note must never contain health details, and that option_id is 'the plan they want to talk about'. It doesn't explain every parameter (e.g., age, gender, preferred_contact), but the most safety-critical and workflow-critical parameters are covered.

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 ('pass the person to a licensed adviser') and names the concrete side effects: saves the enquiry, emails the shortlist, emails the adviser, returns a WhatsApp link and a reference. It clearly distinguishes this from sibling tools like find_plans or compare_plans, which are about plan discovery rather than handing off a lead.

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 explicit preconditions: only call once the person has given a name and a phone number or email and has said they want to be contacted. It also states a hard exclusion ('Never put a health detail in the note') and explains the key requirement. This is strong when-to-use guidance that an agent can act on without ambiguity.

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 readOnly, idempotent, non-destructive and openWorld=false, so the bar is lower; the description still adds meaningful behavior: an API key is required on the public server, and without one the tool returns key_required with instructions on obtaining a key. It also discloses the caveat that the schedule figure holds only unless the insurer refiles.

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?

Two dense sentences with no filler; the primary output (age+1 premium) is front-loaded and the auth caveat follows. Slightly packed with parenthetical qualifiers, but every clause carries information.

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 not be detailed, and annotations carry the safety profile, yet the description still covers output shape, the refiling caveat, and the key_required failure path. Complete enough for an agent to call 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 baseline is 3, but the description adds real meaning by explaining that the first figure is priced at age+1, clarifying how the required age parameter is consumed relative to the schedules.

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 outcome: the premium at age+1 on the current schedule plus a low/mid/high range derived from the plan's own rate changes since 2021. This clearly distinguishes it from siblings like premium_history (past data) and insurer_increases (insurer-wide), though it never names those alternatives explicitly.

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 renewal framing implies when the tool is useful, but there is no explicit when-to-use/when-not guidance and no mention of siblings such as price_plans or premium_history. Usage is left to inference from the output description.

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=true, idempotentHint=true, destructiveHint=false, and closed-world behavior, so the safety profile is fully covered structurally. The description adds useful content context (it returns filed terms with clause page numbers) but says nothing about auth, rate limits, or edge cases beyond what annotations and the output schema provide.

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?

A single front-loaded sentence with no filler; the content scope is stated immediately and every clause earns its place.

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 annotations covering safety, an output schema covering return shape, and full parameter documentation, the description only needs to orient the agent on what this retrieves. It does that well, though it stops short of explicitly routing the agent away from list-oriented siblings.

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?

There is a single parameter with 100% schema coverage; the schema itself explains the id format with an example ('F00070-06-000-02') and its origin in search. The description adds nothing beyond that baseline, so a 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 concrete resource and its scope: 'the full record behind a search id' plus what that record contains ('what the plan pays and every term as filed, with the page of each clause'). This clearly distinguishes a single-record retrieval from list-oriented siblings like search or plan_terms, though it never names an alternative tool explicitly.

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 phrase 'behind a search id' implies the prerequisite workflow (obtain an id from search, then fetch), which the schema reinforces. However, there is no explicit when-to-use/when-not guidance and no named alternatives such as plan_terms or search_plan_terms, so usage is only implied.

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 the safety profile (readOnly, idempotent, non-destructive, closed world), so the bar is lower. The description adds real behavioral context the annotations cannot: coverage comes from each plan's Benefit Schedule, cost is the published premium for every year from this age, and a second cost figure applies the insurer's filed rate changes. It says nothing about auth needs, rate limits, or result determinism.

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 tool's identity, then the output shape, then the cost methodology, then the one actionable instruction about inputs. Every sentence carries information, though the premium/rate-change sentence is dense and could be tighter.

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 13-parameter tool with 85% schema coverage, full annotations, and an output schema, the description still manages to disclose the computation model and the shape of the result (three explained picks over a ranked list). Nothing an agent needs to call this correctly 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 85%, so the schema already documents nearly every parameter and the baseline is 3. The description adds a semantic rule the schema does not encode — pass only what the person actually said — which steers the agent away from fabricating values for the nullable budget, needs, insurers, and territory fields.

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+resource ("The plan finder") and states exactly what it does: ranks every eligible VHIS plan on coverage and cost and returns three explained picks plus a ranked list. That is far more than a restatement of the name, but it never names a sibling (price_plans, compare_plans, plan_options) to draw the boundary explicitly, so an agent must infer the distinction.

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?

"Age is the only thing it needs; pass whatever else the person has actually said" is clear invocation guidance: it tells the agent the sole required input and that the remaining 12 parameters should only be populated from what the user actually stated, not invented. It stops short of saying when to prefer this over price_plans or compare_plans.

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 the read-only, idempotent, non-destructive, closed-world profile, so the safety burden is covered. The description adds genuine behavioral context — the 2021 data horizon, the year-by-year granularity, and the lowest-to-highest ranking order — but does not discuss freshness, update cadence, or what happens when a brand has no matching record.

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?

A single dense sentence with zero filler, front-loading the primary resource before the secondary market-table mode. It is slightly overloaded with two distinct outputs in one clause, but every phrase earns its place.

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 formatting need not be described, and annotations cover the safety profile. The description supplies data scope, granularity, and ordering, which is nearly everything an agent needs, though the brand-vs-market selection could be stated more explicitly.

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 brand parameter already documents examples (Bupa, AIA, AXA) and the omit-for-market behavior. The description reinforces that split but adds no syntax or format detail beyond the schema, so 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?

The description names the specific resource (an insurer's rate record across its VHIS plans since 2021) and the second mode (the market table ranking every insurer by average annual change). It is clear what the tool returns, but it doesn't explicitly contrast itself with siblings like premium_history or list_insurers, so the agent must infer the boundary.

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 description mentions both the single-insurer record and the market table, and the brand parameter is optional, so an agent can infer omitting brand yields the market view. There is no explicit when-to-use guidance or named alternative tool.

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 read-only, idempotent, closed-world, and non-destructive behavior. The description adds scope by indicating it lists only insurers the server can actually price and includes counts, which is useful context beyond annotations, but it does not disclose auth requirements, pagination, or other behavioral traits.

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 a single, front-loaded sentence that efficiently states the returned data and its primary extra detail. No words are wasted.

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 no-parameter list tool with a full output schema and complete annotations, the description is sufficient. It states what the tool returns, and the output schema handles return value details while annotations cover safety.

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 has zero parameters and the schema description coverage is 100%, so the baseline score is 4. There are no parameters for the description to clarify.

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 (every insurer this server can price) and adds that each includes counts of certified plans and rate tables. It clearly identifies the tool as a list operation for insurers, but does not explicitly differentiate itself from sibling tools like insurer_increases or find_plans.

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 provides no when-to-use guidance, no alternatives, and no prerequisites. It only describes what is returned, leaving the agent to infer when this tool is appropriate versus other insurer or plan tools.

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 the full safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds provenance (figures come from the plan's own Benefit Schedule) and the granularity of the result, but says nothing about failure modes for a bad/unknown cert or rate limits; with an output schema present, return-shape detail is not needed here.

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 the core purpose, then the enumeration of covered items, then example queries — a sensible order. The middle sentence is long and runs several categories together, but almost every clause carries distinct information.

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 handling return values, annotations handling safety, and a single well-documented required parameter, the description covers purpose, scope, and usage context adequately. A minor gap is no guidance on what happens when the cert is unknown or how this differs from sibling term/option lookups.

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 single `cert` parameter is fully documented in-schema with a format example (F00070, F00070-06-000-02). The description adds no parameter-level meaning, which is the expected baseline when the schema does all the work.

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+resource: it returns what a single plan pays, item by item, sourced from that plan's own Benefit Schedule, and enumerates the exact benefit categories (room and board, hospital charges, surgeon's fee, imaging, cancer, psychiatric) plus limits and room class. This is far more specific than a name restatement, though it never explicitly contrasts itself with near-neighbors like plan_terms, plan_options, or compare_plans.

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 triggering questions — "what does this cover", "is surgery covered in full", "does it include outpatient" — which tells the agent the right situations to reach for this tool. There is no explicit when-not guidance or named alternative (e.g. use compare_plans for multiple plans), 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.

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuine behavioral context beyond that: pricing is age-conditional ('when an age is given') and the response includes premium projections every five years out to twenty years, which shapes how an agent interprets 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?

A single dense sentence that front-loads the resource and then the returned fields. It is efficient with no filler, though the trailing clause about five-to-twenty-year projections is slightly compressed and takes a second read.

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 format needn't be described, and annotations cover the safety profile, so the description's job is narrower. It covers what the tool does and the key pricing behavior, but omits guidance on when to prefer it over sibling pricing tools.

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 75%, so the schema already documents cert, gender and smoker. The description adds meaning for the undocumented age parameter ('priced at this age when an age is given'), clarifying it is optional and changes the output, but adds nothing beyond the schema for the other three. Baseline 3 for high coverage 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 the resource (every option sold under one certification number) and enumerates the fields returned (room class, deductible, area) plus the pricing behavior, so the agent knows exactly what this returns. It does not explicitly differentiate from siblings like price_plans or compare_plans, which is the only thing keeping it from a 5.

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: you need a cert (from an earlier result) and optionally an age to get age-priced figures. However, there is no explicit when-to-use vs. when-not, and no mention of the closest alternatives (price_plans, compare_plans), so the agent must infer the 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 readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile needs no restating. The description adds genuinely new behavioral context: results are field-by-field with per-field page provenance, and the agent is told to cite pages. It stays silent on formatting or length of the filed terms, so not 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?

Front-loaded with the core statement of what the tool returns, then usage guidance. The long field enumeration is large but earns its place by scoping what the agent can look up; only minor trimming would improve it.

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 structure need not be explained, and annotations cover the safety profile. With one documented parameter and usage contexts spelled out, the definition is nearly complete; only the relationship to overlapping siblings is left implicit.

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 single cert parameter is already documented with format examples (F00070 / F00070-06-000-02). The description adds nothing about the parameter, so the baseline 3 for high-coverage schemas 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+resource (the plan's terms as filed with the Health Bureau, returned field by field) and enumerates the exact fields covered, so an agent knows precisely what it retrieves. It does not explicitly name how it differs from overlapping siblings like plan_coverage or search_plan_terms, so it falls short of full sibling differentiation.

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 contexts – 'does it cover X', 'what is the rule on Y', and terms comparisons – plus the instruction to cite the page. This is clear positive guidance, but it stops short of exclusions or naming the alternative tool for keyword-style lookups.

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 destructiveHint=false, so the safety profile is covered. The description adds the analytical framing (age held constant, changes vs average) but says nothing about data limitations, coverage gaps, or how missing schedules are handled; with annotations carrying the behavioral burden, this lands at an adequate 3.

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?

Two sentences, front-loaded with what it returns before the usage cue, with no filler. The mid-sentence catalogue of outputs is dense but each item is informative, so it earns its length.

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 explained, yet the description anticipates the agent's needs by naming the per-schedule and aggregate figures it produces. Combined with annotations for the safety profile and the schema for parameter formats, nothing essential 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 75% and the schema already documents cert, gender and smoker. The description only implicitly clarifies the age parameter ('the premium at this age ... with the age held constant'), which is useful but shallow; the baseline 3 is appropriate when the schema does most of the work.

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 resource (a plan's premium record) and enumerates exactly what it returns: each filed schedule, the premium at a held-constant age, year-on-year changes, and the average. It also scopes the data with 'since 2021', which meaningfully separates it from sibling tools like insurer_increases and estimate_renewal.

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 use cases in the insurer's own question form ('has this gone up', 'is this insurer stable'), which tells the agent when a historical-record read is the right call. It stops short of naming alternatives or stating when not to use it (e.g. versus insurer_increases for insurer-level trends), so it isn't a full 5.

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 the safety profile (readOnly, idempotent, non-destructive), but the description adds value beyond them: the API key requirement on the public server and the specific key_required error behaviour with a pointer to getting a key. It doesn't mention result-count or pagination behaviour, so it stops just short of exemplary.

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 front-loaded sentences: ranking semantics first, then when to use it, then the sibling alternative and the auth caveat. No filler and no repetition of schema content.

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 description covers scope, selection criteria and the key failure mode. With 9 parameters it could do slightly more to signal that ranking ignores coverage in the returned ordering, but nothing an agent needs to call it correctly 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 78% across 9 parameters, so the schema does most of the work and the baseline is 3. The description only indirectly touches parameters ('one insurer's prices' hints at insurers, 'ranked by annual premium' frames the limit/one_per_product defaults) and adds no format or syntax detail.

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 with scope: 'Every matching plan ranked by annual premium alone, with no view on coverage.' It explicitly contrasts itself with find_plans, so an agent can distinguish it from the sibling without opening either 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?

Names concrete triggers ('asks for the cheapest, for a full list, or for one insurer's prices') and the exclusion condition ('When what the plan covers matters, use find_plans'). The routing decision is fully spelled out.

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 the safety profile is covered structurally. The description adds the result shape (id, title, page link, clause text) and the intended search-then-fetch workflow, which is useful beyond annotations, though the field list partially duplicates the output schema.

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 and the fetch hand-off are front-loaded in the first two sentences. The final sentence about client naming conventions is slightly meta but justifies the duplicate tool, so it earns most of 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?

An output schema exists, so return values need not be re-explained, and the description covers the search-then-fetch workflow and sibling disambiguation. The one gap is that limit is neither described nor acknowledged, leaving a required behavioral detail (pagination via limit) 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 50%: query is documented inline with an example, but limit has no description in the schema and the tool description never mentions it. The description adds no parameter guidance at all, so the limit semantics (default 10, max 20) must be inferred from the schema alone. Baseline 3 for partial coverage with a largely self-evident integer parameter.

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 ("Search every certified plan document and return matching records") and enumerates the returned fields (id, title, page link, clause text). It explicitly distinguishes itself from both siblings it overlaps with: fetch (for full records by id) and search_plan_terms (same search, richer output).

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 an explicit routing rule: "Call fetch with an id for that plan's full record," which tells the agent exactly when to chain to the sibling. It also explains the relationship to search_plan_terms and why the alias exists, removing any ambiguity about which search variant to pick.

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 the safety profile is covered. The description adds that results are verbatim clauses with citation metadata (plan, Part, Section, page, link), which is useful behavioral context beyond the annotations.

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, zero filler, front-loaded with the verb and resource followed by output shape, use cases and the mandatory-usage rule. Every sentence earns its place.

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?

Purpose, return contents and usage triggers are all stated, and an output schema exists so return values need no further explanation. The only gap is the undocumented 'limit' parameter, which is minor.

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 75% and the schema already explains cert, brand and question with examples. The description adds no parameter-level detail, and 'limit' carries no description in either place. 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 states a specific verb and resource ('search the official Terms and Benefits of the certified plans') and specifies the return shape (clauses with plan, Part, Section, page, link). It does not explicitly differentiate itself from siblings like plan_terms or search, but the scope is clear enough to distinguish it.

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 names concrete trigger topics (exclusions, waiting periods, limits, room class rules, territorial scope, definitions, renewal, cancellation) and adds a strong directive: 'Never state what a plan says without it.' This gives clear context for when to reach for it, though it does not name an alternative sibling for comparison.

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. The description adds meaningful provenance (government price transparency platform), confirms figures are actual billed amounts rather than estimates, and warns of several-fold variation between hospitals. It does not describe output format (output schema exists) or auth needs.

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 what the tool returns. The first sentence is somewhat run-on but every clause earns its place by clarifying the split fees and plan payment. No wasted preamble.

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 the output schema handles return values and annotations carry the safety profile, the description supplies necessary domain context: actual government-published bills, hospital-level variability, and a presentation warning. Complete enough for a read-only retrieval tool, though it could note invocation combinations more explicitly.

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 fully documents both cert and procedure parameters. The description reiterates the plan-payment aspect of cert but adds no syntax, format, or constraint details beyond what the schema provides. Baseline 3 applies 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?

States a specific resource: Hong Kong private hospital billed amounts per procedure, split into doctor and hospital fees, plus what a named plan pays. It clearly distinguishes from estimates ('not an estimate'), but lacks explicit sibling tool names or a leading imperative verb, so it falls short of a 5.

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?

Contrasts with estimates ('not an estimate') and cautions against quoting a single hospital figure without naming the hospital, giving implied usage context. However, it does not name alternative tools (e.g., estimate_renewal, price_plans) or state when to avoid this tool, leaving usage to inference.

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