vhis

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable context by noting the content is curated from advisers and scheme rules and is guidance rather than authoritative plan terms. This helps the agent understand the nature and reliability of the information without contradicting 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?

The description is a single sentence with no filler, front-loading the core resource ('Curated notes from licensed advisers and the scheme rules') before listing examples. It could be slightly more structured, but it is appropriately concise and each word adds meaning.

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?

The tool is simple with three optional parameters and an output schema, so the description does not need to explain return values. However, it lacks explicit guidance on how to combine parameters or when to use this tool over siblings like plan_terms. The negative statement about plan terms helps, but the context is still somewhat thin for an agent facing many sibling 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 description coverage is 0%, so the description must compensate for parameter meaning. It provides some topic examples (underwriting, claims, tax) that relate to the 'topic' parameter, but does not explain the 'brand' or 'question' parameters at all. It also doesn't mention that the topic parameter is constrained by a regex pattern. The description only partially clarifies the parameter semantics, leaving significant gaps.

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 clearly states the tool provides curated adviser notes and scheme rules, covering specific domains like underwriting, claims, and tax. It explicitly contrasts itself with plan terms ('Guidance, not plan terms'), which distinguishes it from siblings such as plan_terms and search_plan_terms. An agent can easily understand what this tool is for.

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 implies usage contexts by listing topics (underwriting, claims, switching, tax) and states it is 'guidance, not plan terms,' which hints at when not to use it. However, it never explicitly names alternative tools or provides clear when-to-use versus when-not-to-use guidance. The agent must infer selection criteria from the topic list and the negative statement.

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 declare readOnlyHint=true, so the description doesn't need to restate safety. It adds valuable behavioral context: the tool requires a key on the public server and returns key_required with user guidance if absent. It also implies the output is a side-by-side comparison of differences, which is useful. It doesn't detail output structure, but an output schema exists, so that's acceptable. Minor gap: no mention of how it handles invalid option_ids, but that's not a major omission.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the first defines scope, the second defines when to use it, the third discloses a critical prerequisite and failure mode. Information is front-loaded with the core purpose before the usage note. No fluff or repetition of schema details.

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 comparison tool with a full input schema and an output schema, the description covers the essential context: what is compared, when to use it, and the key requirement. The only notable omission is not naming a specific sibling alternative (e.g., price_plans) for when the user just wants prices, but the use-case framing is strong enough that an agent can infer the boundary. The key_required behavior is a nice completeness touch.

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 all four parameters. The description adds context for option_ids ('from an earlier result') and age ('as the premium schedules state it') indirectly, but mostly it reinforces what the schema says. Baseline 3 is appropriate because the schema carries the heavy lifting and the description doesn't add significant new parameter-level meaning.

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 ('compare') and resource ('plans'), and immediately clarifies what the comparison covers: 'premium now and at 65, next-year range, deductible, room class, limits, area and each insurer's rate record.' It also distinguishes itself from siblings by focusing on 'what actually differs' and the trade-off question, which is a clear differentiator from tools like find_plans or price_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 explicitly says when to use it: for 'which is better' and 'why is one cheaper' questions, and instructs the agent to 'state the trade-off and let the person choose.' It also names a prerequisite (a key on the public server) and the failure mode without it, which is strong usage guidance. It doesn't name a specific alternative tool, but the use-case framing is clear enough to route correctly among siblings.

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 declare readOnlyHint=true and openWorldHint=false, so the description doesn't need to restate safety. It adds valuable behavioral context: the estimate is 'certain unless the insurer refiles', the range is built from the plan's own rate changes since 2021, and the key_required error behavior is disclosed. This goes beyond the annotations and helps the agent anticipate failure modes.

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 two sentences with no wasted words. It front-loads the core computation, then the certainty condition, then the range methodology, then the key requirement. 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?

Given the output schema exists and annotations cover safety, the description is nearly complete. It explains the key requirement and the range construction. It could mention what the low/mid/high range represents more explicitly, but the output schema likely covers that. The description is sufficient for an agent to call 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?

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context about 'age plus one' and 'current schedule', which clarifies the age parameter's role, but doesn't add much beyond the schema. Baseline 3 is appropriate because the schema carries 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 ('estimate') and resource ('renewal premium at age plus one on the current schedule'), and clearly distinguishes it from siblings like price_plans and premium_history by explaining what it computes and its certainty condition. It also names the sibling insurer_increases implicitly by referencing the plan's own rate changes since 2021, which helps an agent differentiate.

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 explains when to use this tool: to estimate renewal cost at age plus one, and notes the key requirement on the public server. It doesn't explicitly say when not to use it or name alternatives, but the context signals and sibling list imply it's for renewal estimation rather than current pricing or historical premium data. The key requirement is a clear usage condition.

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 description goes beyond the readOnlyHint annotation by explaining how rankings are computed: coverage from Benefit Schedule and cost from published premiums with filed rate changes. It also discloses that age is the only required input, adding meaningful 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?

The description is two sentences, front-loaded with the core purpose, then explains data sources and the age requirement. It is efficient with no filler, though it could be slightly tighter. Scores a 4.

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 13 parameters and an output schema, the description covers the key behavior (ranking and return structure) and the data sources, while leaving parameter details to the schema. This is sufficient for an agent to call it correctly, so it scores a 4.

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 input schema already provides descriptions for 85% of parameters, so the baseline is 3. The description adds only a general usage hint ('pass whatever else the person has actually said') rather than specific parameter meaning, so it does not significantly enhance parameter understanding.

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 clearly states the tool ranks all eligible VHIS plans and returns three explained picks with a ranked list, using a specific verb and resource. However, it does not explicitly differentiate from sibling tools like compare_plans or price_plans, so it earns a 4 rather than 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?

The description provides guidance on what to pass ('Age is the only thing it needs; pass whatever else the person has actually said'), but it does not state when to use this tool versus alternatives like compare_plans or price_plans. There is no explicit exclusion or alternative routing, so it scores a 3.

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 readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context about the time range (since 2021), the yearly grouping, and the market-table ranking order, but it does not disclose anything about failure modes, pagination, or data freshness. This is acceptable for a read-only tool but does not go beyond what annotations already cover.

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 dense sentence with no filler or repetition. It packs several important details—time range, yearly granularity, insurer scope, and ranking order—into a compact form. It is not as crisp as a short imperative, but it is efficiently written.

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 simple read-only tool with one optional parameter and an output schema, the description provides enough information to understand what data will be returned: the insurer's year-by-year record and the ranked market table. The main missing piece is when to use this tool versus related siblings, but that gap is better captured under usage guidelines.

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 input schema fully documents the only parameter, brand, with examples and the omit-for-market-table behavior, so schema coverage is 100%. The tool description adds no meaningful parameter detail beyond what the schema already provides, 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?

The description clearly identifies the resource: an insurer's yearly rate record across VHIS plans since 2021, plus a ranked market table. It is specific enough to distinguish the general subject matter, though it lacks an explicit verb such as 'returns' or 'lists' and does not directly contrast against close siblings like premium_history.

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 offers no explicit guidance about when to choose this tool over related alternatives. The only usage hint, 'omit for the market table,' appears in the parameter schema rather than the tool description. An agent must infer when this tool is the right choice compared to premium_history or other rate-related 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 declare readOnlyHint=true, so the description doesn't need to repeat safety. It adds useful behavioral context by stating the list is exhaustive ('Every insurer this server can price') and describing the output composition (plan/rate-table counts), though it omits pagination or limit behavior.

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 17-word sentence that front-loads the scope ('Every insurer') and immediately states the key output details. No filler or redundancy.

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 zero parameters, no required arguments, an output schema present, and read-only annotations, the description provides everything an agent needs to invoke this tool correctly. Nothing important 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?

The tool has zero parameters and schema coverage is effectively 100% (empty object). With no parameters to explain, the description adds no parameter semantics, and the baseline of 4 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 ('list insurers') and scopes it precisely to 'Every insurer this server can price'. It also specifies the returned information (counts of certified plans and rate tables), distinguishing it 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 implies usage for discovering all available insurers, but it does not explicitly state when to use this tool versus alternatives such as find_plans or compare_plans. No when-not-to-use or alternative guidance is provided.

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 provide readOnlyHint=true, so no safety contradiction exists. The description adds significant behavioral detail beyond the annotation by listing the exact benefit items and limits the tool reports, as well as that it operates from the plan's own Benefit Schedule. This goes beyond the minimum and clarifies the tool's output scope, though it does not discuss rate limits, errors, or other less-visible behavior.

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 dense but purposeful, front-loading the core purpose ('What one plan actually pays, item by item') before enumerating specifics. The two sentences each carry information—the first defines scope and contents, the second gives usage examples. It could be slightly tighter, but it earns a high score for efficiency.

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 a single well-documented parameter, readOnlyHint annotations, an output schema present, and explicit usage guidance, the description is complete for an agent to invoke the tool correctly. Nothing necessary for selection or calling 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%; the only parameter (cert) is clearly described as a VHIS certification number from an earlier result with an example format. The description adds no further meaning to cert, so the 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 states a specific verb+resource: it reports what one plan actually pays, item by item from its Benefit Schedule, and enumerates covered categories (room/board, hospital, surgeon, imaging, cancer, psychiatric, limits, territory, extras). It also includes explicit example queries ('is surgery covered in full'), making the tool's purpose unmistakable and clearly distinct from siblings like compare_plans 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 gives clear usage contexts: 'Use it for "what does this cover", "is surgery covered in full", "does it include outpatient".' This tells an agent when to invoke the tool. It does not explicitly name alternatives or say when not to use it, so it earns 4 rather than 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 the operation read-only, and the description adds useful behavior: it returns every option under one cert and shows pricing at the supplied age plus premium projections in five-year steps to twenty years. This goes beyond the annotations and schema, though it doesn't address ordering, filtering, or error conditions.

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 compact sentence that front-loads the key scope ('Every option sold under one certification number') and then packs the useful details. It is slightly dense and grammatically awkward, but no word 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?

Given the readOnlyHint, the optional age parameter, and a rich output schema, the description says enough about what the caller gets and the projection cadence. It does not discuss edge cases such as missing age or null cert, but those are relatively minor for this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions already cover cert, gender, and smoker well (75% coverage). The description adds meaning mainly for age, clarifying that it controls the displayed current price and the projection horizon. That is helpful but not comprehensive, so it doesn't clearly rise above the baseline.

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 identifies a specific resource (one certification number) and the output content (all options with room class, deductible, area, current and projected premiums), so an agent can tell it returns a comprehensive option list for a single plan. It lacks an explicit verb and does not call out sibling tools, 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?

There is no guidance about when to choose plan_options over related tools such as price_plans, compare_plans, or plan_coverage, and no exclusions or prerequisites are stated. The only conditional clause ('when an age is given') describes parameter behavior, not usage context.

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 provide readOnlyHint=true and openWorldHint=false, so the description need not repeat safety. It adds valuable context by specifying the source ('as filed with the Health Bureau') and the output format ('with the page each came from'), and instructs users to cite the page. This enriches the behavioral profile 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?

The description is long but every element earns its place: it states the core function, lists the specific fields returned (demonstrating scope), provides clear usage scenarios, and includes the 'cite the page' instruction. It is front-loaded with the main purpose and flows logically from what to how to when. No fluff or redundancy.

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?

The description is complete for a read-only, single-parameter query tool. It covers what is returned (fields with page citations), when to use it (coverage questions, rule lookups, comparisons), and the input requirement (cert from an earlier result). The presence of an output schema means the description need not detail return types. Nothing an agent needs to invoke 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 coverage is 100% and the cert parameter is fully described as a VHIS certification number with examples. The description adds that it comes 'from an earlier result,' which is useful for an agent to understand the provenance. This goes beyond the schema's basic type/format description, so a 4 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 explicitly states the tool retrieves a plan's terms as filed with the Health Bureau, field by field with page citations, and enumerates the specific fields covered. It clearly distinguishes itself from siblings by stating it is for single-plan term lookups and comparisons, contrasting with tools like search_plan_terms which imply cross-plan search.

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 usage guidance: 'Use it for "does it cover X", "what is the rule on Y" and terms comparisons; cite the page.' This clearly indicates when to use it. However, it does not explicitly mention alternatives or when not to use it, such as when a broader search across plans is needed, which would route to search_plan_terms.

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 provide readOnlyHint=true and openWorldHint=false, so the description doesn't need to restate safety. It adds value by specifying the data scope (since 2021, age held constant, year-on-year changes) and the analytical purpose, which helps the agent set expectations for the response.

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 concise (two sentences), front-loads the key data points, and includes practical use cases. Every sentence adds value without redundancy.

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 annotations (read-only) and rich output schema (likely containing detailed premium history), the description covers the core purpose and usage. It could mention that results are read-only, but annotations handle that, so it's complete enough for an agent 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 75%, with cert, gender, and smoker having descriptions. The description adds context for 'age' (but not explicitly) and explains the analytical output. It doesn't detail parameter interactions, but given the high schema coverage, it provides sufficient supplemental meaning.

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 clearly states the tool shows a plan's premium history since 2021, including schedule filings, age-constant premium, year-on-year changes, and average. It distinguishes itself from related tools like 'insurer_increases' by focusing on a specific plan's premium movement, not insurer-wide increases.

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 explicitly states when to use it: for questions like 'has this gone up' and 'is this insurer stable'. It implies it is for premium trend analysis, differentiating it from sibling tools like 'estimate_renewal' (future projections) and 'insurer_increases' (insurer-level trends).

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 readOnlyHint=true annotation, the description discloses an authentication requirement, the specific error returned without a key, and the fact that the tool provides no view on coverage. These are meaningful behavioral facts not visible from annotations or 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?

Four short sentences, each earning its place: core behavior, use cases, alternative routing, and auth/error behavior. The most important discriminator is front-loaded, and there is 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?

For a tool with 9 parameters, an output schema, and many siblings, the description covers purpose, selection criteria, key alternative, and a critical failure mode. The output schema handles return values, and the annotations cover safety. 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 78%, and the schema already documents most parameters (age, room, gender, smoker, insurers, max_deductible, one_per_product). The description adds no parameter-level detail; it mainly clarifies the ranking behavior, which is output semantics rather than input meaning.

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 the tool ranks matching plans by annual premium only, explicitly excluding coverage considerations. It also names the sibling alternative find_plans, making the distinction crisp without requiring schema inspection.

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 when-to-use guidance: 'cheapest', 'full list', or 'one insurer's prices'. It also gives an exclusion: when coverage matters, use find_plans. This is as clear as usage guidance can get.

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 mark it read-only. The description adds that it only searches 'certified plans' and returns structured clause details with location metadata, which is useful behavioral context. It does not disclose rate limits or error behavior, but given readOnlyHint, the bar is lower.

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 two sentences, front-loaded with the core action, then a list of use cases and a strict rule. No wasted words.

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 need not detail return values. It covers the tool's purpose, scope (certified plans), output structure, and use cases, which is sufficient for a search tool. It doesn't mention pagination but the limit parameter handles that.

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 descriptions cover 75% of parameters, including examples for 'question' and scoping explanations for 'cert' and 'brand'. The description does not add parameter details beyond the schema, so it relies on the schema to explain the arguments.

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 ('Search'), resource ('official Terms and Benefits of the certified plans'), and output ('clauses, each with the plan, Part, Section, page and a link to that page'). It also lists specific use cases (exclusions, waiting periods, limits) that differentiate it from sibling tools like plan_coverage 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?

It explicitly says 'Use it for' followed by a list of plan-related topics, and instructs 'Never state what a plan says without it', making it clear when this tool must be used. It does not name alternatives, but the directive is unambiguous.

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