costkits-mcp

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds meaningful context beyond that: it is stateless (no persistence or mutation side effects) and it returns not just one number but a breakdown plus p25/p75 scenarios. With no output schema, disclosing those return semantics is genuinely useful, though edge cases (e.g. how copay interacts with coinsurance, ordering of deductible/OOP application) are left unstated.

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 the core purpose and scoping label before the usage note. No filler; each sentence contributes either the what or the when.

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 8-parameter tool with no output schema, the description adequately covers inputs, outputs, and the stateless nature, and the schema carries the parameter detail. What is missing is how the p25/p75 scenarios are derived and how optional fields like copay or oop_met change the result, which would help an agent set expectations.

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 all 8 parameters, including optional copay, oop_met, deductible_met, and preventive_exception, are already documented in the schema. The description restates the required inputs (deductible, coinsurance, OOP max) but adds no extra meaning such as interaction rules or units beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific verb and resource ('Stateless insurance math', 'calculate liability') and states exactly what it returns: patient responsibility, plan payment, the breakdown, and p25/p75 scenarios. It implicitly separates itself from sibling estimate tools by scoping to inputs you already have, but it never names an alternative like full_estimate or estimate_procedure_cost, so the differentiation is inference-based rather than explicit.

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

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

'Use when you already have a dollar amount (e.g. from an EOB or a prior estimate)' gives a clear precondition that tells the agent when this tool applies versus one that generates an estimate from scratch. There is no explicit when-not guidance or named alternative, which keeps it 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 it read-only, non-destructive and closed-world, but the description adds substantial context beyond them: it is a screening estimate, not an eligibility decision, hospital limits vary, and it explicitly warns not to request names, account numbers or bill details (a privacy constraint the annotations cannot 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?

Three tight sentences, front-loaded with what it does and returns, followed by the trigger condition and the data-privacy constraint. No filler and nothing repeated from structured 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?

With no output schema, the description carries the return-value burden and delivers it fully: percent of poverty guidelines, typical hospital coverage range, federal rule caveats, and next steps. 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 description coverage is 100%, so the schema already documents all three parameters including the state-code detail and income bounds. The description only restates that household size and annual household income are needed, adding no syntax or format detail beyond the schema – 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?

States a specific verb (screen) and resource (household for hospital financial assistance / charity care), then enumerates exactly what it returns: income as a percent of federal poverty guidelines, typical policy coverage range, IRS 501(r) guarantees, and next steps. This clearly distinguishes it from siblings like calculate_liability, get_coverage, and demo_estimate.

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 a concrete triggering condition: 'Use when a user asks whether they might qualify for help paying a hospital bill,' and clarifies the screening-vs-decision boundary. It does not name a sibling alternative or state when not to use it, so it falls short of 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral facts beyond that: no API key required, the data is a static sample, and the intended use is connectivity/shape verification, which an agent could not infer from 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 short sentences, zero waste, with the identity of the sample and the no-key guarantee front-loaded before the usage instruction.

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-param demo tool with no output schema, the definition covers what is needed: what it returns (sample data), that no auth is needed, and that it is for inspecting response shape. A note on whether the sample value is ever updated would be the only marginal addition.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate, and the schema is trivially complete.

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

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

Names a specific verb and resource ('Static sample cost estimate... colonoscopy in Connecticut') plus the source ('CostKits API'), which cleanly separates it from siblings like estimate_procedure_cost and full_estimate that return real data.

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

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

Explicitly states the use case ('use it to verify connectivity and see the response shape') and the key precondition ('Works with NO API key'), which is exactly what routes an agent here over the keyed estimate tools. It does not name a specific alternative tool, 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 establish readOnly/non-destructive/closed-world, so the bar is lower, and the description still adds real value: data provenance (hospital price transparency and Medicare data), the vintage disclosure, and the explicit caveat that these are estimates, not quotes. It does not cover latency, coverage gaps by state, or error 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?

Three sentences, front-loaded with the primary return shape, then the conditional patient-share behavior, then the input requirements. Slight redundancy in restating the required/optional split already present in the schema, but 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 no output schema, the description carries the return-value burden and does so: it enumerates the range fields, billing components, vintage, and the conditional patient share. Combined with the estimate-not-quote disclaimer, an agent has enough to call it and set expectations 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 the baseline is 3, but the description adds meaning beyond the schema: it states that deductible/coinsurance/OOP inputs are user-supplied optional figures that only conditionally trigger a patient-share result, and that ZIP is used 'only to refine the local estimate'. That clarifies the conditional role of the optional parameters better than the field descriptions alone.

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

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

The description names a specific verb (returns) plus concrete outputs: an allowed-amount range (low/median/high) for ONE procedure in ONE US state, billing components, and data vintage. Scope ('one medical procedure in one US state') helps distinguish it from broader siblings like full_estimate, but no sibling is named 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?

It clarifies the required-vs-optional split and that plan figures 'are used only for this one calculation', which is useful conditional guidance. However it never states when to prefer this over full_estimate, demo_estimate, or calculate_liability, nor when to route procedure-name matching through resolve_procedure (that hint lives only in the schema).

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/openWorldHint annotations, the description discloses crucial behavioral traits: dollar amounts are NOT returned, the list is partial, and it is explicitly not a ranking or recommendation. It also defines the pricing_status enumeration semantics ('observed' vs 'estimated' vs 'none'), which is exactly the kind of value semantics annotations cannot carry.

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 tight sentences with zero filler; the core behavior is front-loaded and the caveats (no dollar amounts, partial list) follow in priority order. Every sentence carries information an agent needs.

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 no output schema, the description carries the return-value burden well, naming the returned fields and explaining pricing_status. It is slightly incomplete on failure modes (e.g., unknown procedure slug, and the existence of resolve_procedure as a prerequisite) and on ordering/pagination behavior.

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 all three parameters are already documented in the schema, giving a baseline of 3. The description reinforces the limit (up to 5) and single-state scope but adds no format or syntax detail 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?

States a specific verb (Lists), resource (facilities/providers), and scope (up to 5 in one US state that perform a procedure), plus the exact return fields. An agent can distinguish it immediately from the singular get_provider and from pricing tools like estimate_procedure_cost without opening any schema.

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

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

Scope is implied ('up to 5', 'one US state') but there is no explicit when-to-use guidance and no alternative named, even though siblings like get_provider, estimate_procedure_cost, and resolve_procedure overlap in the provider/cost domain. The agent must infer that this is a discovery/shortlist call rather than a pricing call.

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 readOnly/non-destructive/closed-world, so the bar is low. The description adds genuinely new context: that the call is metered (a cost/billing trait) and that liability output is gated on supplying the plan_* inputs. It says nothing about size of response or latency for an eight-parameter aggregate.

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 tight sentences, front-loaded with the composite purpose before the cost rationale and the parameter caveat. Every sentence carries weight, though 'get the complete picture' is slightly redundant with the first sentence's enumeration.

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 eight-parameter aggregating tool with no output schema, the description does not describe the shape of the returned composite (how procedure/cost/providers/liability are bundled). It covers the fields selector and liability prerequisites, but return-value expectations rest on inference.

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%: state, procedure, fields, and plan_coinsurance are documented, but plan_oop_max, plan_oop_met, plan_deductible, and plan_deductible_met are undocumented in both schema and description. The description partially compensates by grouping them as 'plan_* inputs' and tying them to the liability field, which is the right signal but not full coverage.

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 composite behavior: chaining procedure ontology, cost, providers, and patient liability into a single call, which lets an agent distinguish it from the narrower siblings like estimate_procedure_cost, find_providers, and calculate_liability. It stops short of naming those siblings explicitly, so differentiation must be inferred.

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

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

It gives a clear selection rationale ('cheapest way (one metered request) to get the complete picture') and a conditional rule for the liability portion ('liability requires the plan_* inputs'). It does not state when to prefer a narrower sibling instead, so the guidance is strong but not exhaustive.

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 safety profile is covered. The description adds nothing beyond that about behavior — no note on rate limits, coverage gaps for unknown carriers, or whether missing data returns an empty result. The 'triggers' explanation is output semantics rather than 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?

One dense sentence that front-loads the purpose before enumerating aspects; every clause carries information. The embedded parentheticals are slightly heavy but readable and justified.

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 no output schema and 75% schema coverage, the description covers the most ambiguous input (aspect) well and clarifies the two non-required params implicitly. plan_type's effect on results is the main unexplained gap, leaving it just short of fully 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 coverage is 75% and the schema only labels 'aspect' with 'Default summary'. The description expands each enum value into what it actually returns (status+plain English, deductible/coinsurance/ACA preventive, age rules, billing-event triggers), which is genuine meaning beyond the schema. plan_type receives no description-level explanation, so not a 5.

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 ('insurance coverage rules') and its scope ('for a procedure/carrier combination'), which cleanly separates it from cost-estimation siblings like estimate_procedure_cost or calculate_liability. It does not name any sibling explicitly, so it stops 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?

The aspect list implicitly guides how to pick a mode, and 'triggers' is flagged as 'the highest-signal aspect', which is useful routing advice. However, there is no statement of when to prefer this tool over full_estimate / estimate_procedure_cost, nor any exclusion or prerequisite (e.g., carrier must come from list_carriers).

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds meaningful behavioral detail beyond that: it characterizes the returned payload per aspect (billing rules/cost drivers, expected bills, full ontology) and flags which is best for grounding answers, which matters since there is no 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?

Dense but front-loaded: the core purpose comes first, followed by the aspect breakdown. Every clause earns its place, though the semicolon-separated aspect list reads as a run-on and could be slightly easier to scan.

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 only two parameters, full schema coverage, and annotations covering the safety profile, the main remaining burden is explaining return content, which the aspect descriptions handle well. The one notable gap is how the caller obtains a valid canonical slug (likely via resolve_procedure), which 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining what each 'aspect' enum value actually returns rather than just repeating the schema's 'Default facts'. It does not add anything about slug format or how to obtain a canonical slug, which the schema only lightly covers.

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 and scope: 'Structured knowledge about one procedure,' with a clear verb-like intent of retrieving details for a single slug. It does not, however, distinguish itself from the sibling 'resolve_procedure' or 'list_procedures', leaving the agent to infer which retrieval tool to pick.

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 real guidance on aspect selection ('facts' is 'best for grounding an answer'), which is useful decision support. But it never states when to call this tool at all versus resolve_procedure/list_procedures, or what prerequisite (a resolved canonical slug) it needs, so usage context 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, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds two useful pieces of context beyond the annotations: that the data is "public" (no auth/credential requirement) and which fields are returned (name, specialty, address, entity type), partially compensating for the missing 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?

A single front-loaded sentence with zero filler; the resource, the lookup key, and the returned fields all appear in the first clause. Nothing needs to be trimmed and nothing is buried.

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 one-parameter read tool with full annotation coverage, the description supplies what's missing from structured data: the returned field set. It omits only edge behavior (e.g., what happens when the NPI is unknown or invalid), which is a minor gap.

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 only parameter's description ("10-digit NPI number") is duplicated verbatim from the schema. The description adds no format, validation, or sourcing detail beyond what the schema already provides, 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?

"Public profile for a single provider" names the resource and the retrieval key (10-digit NPI), and "single provider" implicitly contrasts with the sibling find_providers search tool. It lacks an explicit verb (get/list) and never names the alternative, so differentiation is inferable rather than stated.

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 "by 10-digit NPI number" implies the precondition for use (you must already know the NPI), but there is no explicit when-to-use guidance and no mention of find_providers as the alternative when only a name is known. Usage is implied, not stated.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds genuinely new context the annotations lack: it is available on the Free plan and functions as an API-key sanity check. It does not describe return ordering or format, but for a trivial list tool this is adequate.

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 with no waste; the core purpose (all supported carrier keys) is front-loaded, followed by the operational caveat about the Free plan.

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?

No output schema exists, but the description conveys what is returned (carrier keys with examples) and when the call is useful. For a no-parameter enumeration tool this is nearly complete, missing only trivial detail like ordering or count.

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

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

The tool takes zero parameters, so the schema requires no documentation and the baseline is 4. The description's parenthetical example keys add meaningful value by showing the shape of the returned values.

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 (list) and resource (insurance carrier keys) and even enumerates example values (aetna, cigna, bcbs, medicare). It is clearly distinguishable from siblings like get_coverage or find_providers, though it never explicitly contrasts itself with them.

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?

Provides concrete usage context: it works on the Free plan and serves as an API-key sanity check, implying it should be called to validate credentials or discover valid carrier keys before using coverage tools. No explicit when-not or named alternative, so 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 cover the safety profile (readOnly, non-destructive, closed-world), so the description's added value is the behavioral context: the catalog is a fixed size of 30 and results are paginated. It does not, however, disclose ordering, default page size, or whether cursor is required for subsequent pages.

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?

One front-loaded sentence naming the resource, the size, the returned fields, and the pagination trait. No filler, nothing redundant against the name.

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 no output schema, the description usefully enumerates the return fields and flags pagination, which is the key thing an agent needs for a list endpoint. Minor gaps remain around default limit, maximum page size, and ordering.

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% – only cursor is documented in the schema, while limit has no description and no stated default or bound. '(paginated)' hints that limit/cursor drive paging but adds no semantics beyond the schema; it does not compensate for the undocumented limit 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 resource and scope: the full catalog of 30 procedures, plus the fields returned (slugs, display names, categories, CPT codes). This is distinguishable from the singular siblings get_procedure_details and resolve_procedure, though the differentiation is implied by 'full catalog' rather than stated 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 'the full CostKits catalog' implies bulk enumeration and therefore when this is preferable to a detail lookup, but it never names an alternative or states an exclusion. Usage must be inferred from the sibling set rather than read in the 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 the safe read-only, closed-world profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds genuine behavioral context beyond them: a confidence score is returned, alternatives are offered, and best_match is null on a miss — the most important edge case for a resolver.

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 tight sentences: the primary action and output shape come first, the null-on-miss edge case second. Every clause carries information; nothing is padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly compensates by naming the returned fields (best_match, alternatives, confidence). It stops short of explaining how the confidence score should be interpreted or what a caller should do when best_match is null, which would round out a resolver contract.

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 there is only one parameter, so the baseline is 3; the description earns a notch above by demonstrating the acceptable free-text form ('knee mri', 'gallbladder removal'), clarifying that lay phrasing rather than codes is expected.

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 precise verb+resource ('Maps a free-text procedure name ... to a CostKits catalog slug') and illustrates the input space with two realistic examples. It is clearly distinct from sibling catalog tools like list_procedures or get_procedure_details, though it never names those siblings to make the boundary explicit.

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

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

Usage is only implied: an agent can infer that this is the normalizer to run before any tool needing a catalog slug, but the description never states when to use it versus listing/detail tools, nor any prerequisites or exclusions.

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