coverage-rights

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond annotations: deterministic resolution, fail-closed handling for unsupported or ambiguous routes, and the specific coverage categories it distinguishes. No contradiction is present.

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 dense sentences with no filler. The front-loaded verb 'Deterministically resolve' immediately communicates the action, and every phrase contributes to scope, output, or behavioral boundaries.

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 an 11-parameter tool with no output schema, the description still lists the returned categories (appeal route, missing facts, filing recipient, deadlines, external-review status, verified grounds) and coverage scope. It is sufficient for selection and invocation, though it does not explain parameter prerequisites or offer usage examples.

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 64% of parameters and most parameters have enums, so the structured schema does much of the work. The description reinforces the coverage-program taxonomy and denial reasons but does not add per-parameter syntax or clarify undocumented fields like state or current_status beyond what enums imply.

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 opens with 'Deterministically resolve the governing appeal route, missing facts, filing recipient, deadlines, current external-review status, and verified grounds,' providing a specific verb and clear object. It distinguishes this tool from siblings like get_state_external_review and get_insurer_metrics by enumerating coverage programs and appeal-route scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit 'use when' or 'use instead' guidance. The intended context is inferable from the coverage list and appeal-route focus, but exclusions and alternatives are not stated, so guidance 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 declare readOnlyHint=true and destructiveHint=false. Description adds context about return data (overturn rates, most-fought treatments) but does not disclose additional behavioral traits beyond 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?

Two sentences with no wasted words. Front-loaded with key 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?

Simple tool with one parameter and good schema/annotations. Description adequately explains return value. Lacks differentiation from sibling tools but is otherwise complete.

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 covers the single parameter slug with 100% coverage. Description adds example values (obesity, autism, hepatitis-c), adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool returns external-review outcomes for a medical condition, including overturn rates and most-fought treatments. It uses specific verbs and is easily distinguishable from siblings like get_treatment_outcomes.

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?

Implies use for condition outcome info but lacks explicit when-to-use or when-not-to-use guidance compared to sibling tools. No alternatives mentioned.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive. The description adds valuable behavioral details: returns FDA indications, denial reasons, appeal arguments, step-therapy framing, and external review record. This extra context helps the agent understand the tool's scope beyond safety.

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 with front-loaded key information. The list of drug names is somewhat lengthy but relevant. Could be slightly more concise by grouping, but overall efficient and clearly structured.

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 no output schema, the description adequately explains the return value: FDA indications, denial reasons, winning appeals, step-therapy exception, and external review record. It covers key aspects but could mention ordering or that results are in text/structured form.

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% with a clear description for the single parameter 'drug'. The description's mention 'Accepts a brand or generic name' is redundant with the schema. No additional parameter semantics are provided, so score at baseline 3.

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 it returns drug-specific denial patterns and appeal strategies, listing specific drug classes (GLP-1s, IBD biologics) and what it provides (FDA indications, denial reasons, winning appeals, step-therapy, external review). It distinguishes itself from siblings like get_appeal_rights (general appeal rights) and get_condition_outcomes (outcomes) by focusing on the denial playbook for high-friction medications.

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 use for medications 'plans fight hardest over' and names specific drugs, providing clear context. However, it does not explicitly state when not to use it or give alternatives among siblings. The agent can infer its niche from sibling names, but explicit guidance would improve.

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, idempotentHint, and destructiveHint, so the tool is safe and idempotent. The description adds valuable behavioral context: the data is 'verified', from a specific regulatory disclosure, includes 'source URLs and scope notes', and covers 'contract/plan-level rows where collected'. This goes beyond what annotations 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?

The description is a single sentence that front-loads the main purpose and key metrics. It is informative without being verbose, though breaking it into two sentences could improve readability slightly. Overall, it earns its place without extraneous 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?

Given a single parameter, no output schema, and ample annotations, the description provides sufficient context: metrics, source, scope, and included extra data (URLs, notes). It does not specify the return format, but for a simple tool, the description is complete enough for an agent to understand what the tool returns.

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 only parameter 'slug' is fully described in the schema ('Insurer slug from list_insurers, e.g. 'unitedhealthcare''). The description does not add new parameter meaning beyond the schema, but the schema coverage is 100%, so the baseline of 3 applies. The description implicitly reinforces the slug source, but that's already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get', the resource 'insurer's verified CY2025 prior-authorization metrics', and specifies the exact metrics included (denial rate, appeal overturn rate, decision times). It distinguishes from siblings like 'get_appeal_rights' (appeals) and 'rank_denial_rates' (ranking) by focusing on a specific insurer's detailed metrics from a particular disclosure.

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 the tool is for retrieving metrics for a specific insurer using a slug, and mentions the data source ('CMS-0057-F disclosure') and inclusion of 'scope notes'. It does not explicitly state when to use versus alternatives (e.g., use 'list_insurers' first), but the context from sibling names and the slug parameter makes the usage reasonably clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds crucial behavioral context: verified detail covers 10 states; other states return the list. No contradiction.

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 key info, no wasted words. Efficient and easy to parse.

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 tool (1 param, no output schema), the description fully explains what it returns, coverage limitations, and fallback behavior. No missing context given the annotations.

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% with a clear parameter description. The description adds no extra semantic meaning beyond implying the parameter is used for lookup, so 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 clearly states the resource (state external review process) and action (get details: filing deadline, regulator contact, key facts). It specifies coverage and fallback behavior, distinguishing it from sibling tools that handle appeals, conditions, drugs, etc.

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 implicitly tells when to use (for state external review details) and mentions fallback for uncovered states, but lacks explicit when-not-to-use or alternative tool names.

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 and idempotentHint. The description adds that the data is from published CA IMR decisions (2001–2026), which provides useful context about scope and source.

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 with no wasted words. The first sentence explains what the tool does, the second explains input requirements. Perfectly front-loaded.

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 single-parameter tool with no output schema, the description covers the data source, scope, and how to use the input. It's nearly complete; missing explicit output structure but not required.

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%, as the slug parameter is well-documented with examples. The description adds examples of category vs specific slugs and reinforces finding slugs via search_outcomes, adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves external-review outcomes for a treatment, with specific data about insurer denial overturn rates. It distinguishes from siblings like get_condition_outcomes and get_insurer_metrics by focusing on treatments and drugs.

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 states it accepts category or treatment slugs and directs users to search_outcomes to find slugs. Though it doesn't mention when not to use, the guidance is clear and contextual.

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. Description adds context about the specific data (CMS-0057-F metrics), providing useful detail beyond 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?

Single sentence effectively communicates purpose and scope, with no extraneous 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?

Description is complete for a simple list tool with no parameters and no output schema, though more explicit return structure would be beneficial.

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?

No parameters exist, so baseline 4 applies. Description adds value by indicating the output includes insurer names and availability flag.

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?

Description clearly states the tool lists tracked U.S. health insurers and includes a specific metric availability flag, distinguishing it from sibling tools that focus on specific data retrieval.

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 clear: use to get the list of insurers with metric availability. No explicit alternatives or exclusions, but context is sufficient given tool simplicity.

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, non-destructive, idempotent behavior. The description adds valuable behavioral context beyond annotations: ranks are cohort-relative, each row includes cohort, rank, source scope, calculation method, and source link, and cross-cohort comparisons are invalid. This provides useful detail on data structure and limitations.

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 three sentences, each adding essential information: what the data is, what each row contains, and a critical usage warning. No redundant phrases or filler; every sentence earns its place and the key purpose is front-loaded.

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 zero-parameter, no-output-schema tool, the description is complete. It specifies the data year, ranking approach, row contents (cohort, rank, source scope, calculation method, source link), and warns against cross-cohort comparison. The agent has enough context to invoke the tool and interpret results without further clarification.

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, so the baseline is 4. The description focuses on the data content and interpretation rather than parameter usage, which is appropriate given there are no parameters to document.

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 insurer prior-authorization denial rates for CY2025, ranked within compatible reporting cohorts. It specifies the resource (denial rates), action (ranking), and scope (cohorts), which distinguishes it from sibling tools that focus on other metrics like appeal rights or condition outcomes.

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 includes an explicit usage constraint: 'Never compare ranks across cohorts,' guiding correct interpretation. It does not name alternative tools, but the tool's purpose is clear from the name and description, so the context is sufficient. A minor gap is not explicitly stating when to use this instead of sibling tools, though it is 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 declare readOnlyHint=true and destructiveHint=false, so the description does not add much beyond confirming return values (slugs and overturn rates). No contradictions, but minimal extra behavioral disclosure.

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 convey the purpose and output efficiently. No wasted words, though the return-value detail could be slightly more structured.

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 (search) with good annotations. The description covers the output purpose (slugs for other tools) and overturn rates, which is adequate. Lacks details on result format or pagination, but these are reasonable omissions.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions; it merely restates that search is by name.

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 that the tool searches treatments and conditions by name, and specifies that it returns slugs for get_treatment_outcomes and get_condition_outcomes along with headline overturn rates. This distinguishes it from sibling tools that consume those slugs.

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?

No explicit guidance on when to use this tool versus alternatives (e.g., get_treatment_outcomes, get_condition_outcomes). The description implies a search role but lacks when-not-to-use or prerequisite context.

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