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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-redundant context: it is free and never bills credits, and it authenticates via the connector sign-in or X-API-Key when self-hosted. It doesn't say how many 'recent transactions' are returned or what happens with an invalid key.

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

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

Three short sentences, front-loaded with the returned fields and followed by the two facts an agent most needs (no billing, auth method). No filler or restatement of the title.

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 burden of describing return values and does so by listing the five data points. Auth and cost are covered; the only gaps are the size/window of 'recent transactions' and error behavior for an unauthenticated call.

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 and the schema is empty, so there is no parameter semantics to document; a baseline of 4 applies. The description correctly signals that no inputs are needed by framing the call as a pure account read.

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

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

States a specific verb and resource ('Check your MyMedi-AI account') and enumerates exactly what comes back: credit balance, USD equivalent, transaction count, recent transactions, last activity. That enumeration distinguishes it from sibling tools like buy_credits, which mutates rather than reports.

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

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

Usage is implied by the name and the 'check your account' phrasing, and 'Free — never bills credits' implicitly steers agents away from buy_credits for balance inquiries. However, there is no explicit when-to-use/when-not-to-use statement or named alternative.

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?

Adds genuinely non-obvious behavior beyond the annotations: the call itself is free, checkout happens in the browser, and credits post automatically after checkout — this materially clarifies the destructiveHint=false and non-idempotent profile. It does not mention that repeat calls spawn multiple independent sessions, and there is mild tension with openWorldHint=false given the described Stripe hand-off, though that is a debatable interpretation rather than a clear 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?

Front-loaded with the key fact (free to call, returns a link) before the pricing details, and every sentence is relevant. It is somewhat dense with dollar figures duplicated from the schema, which is the only waste.

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 supplies the return value (checkoutUrl) and post-checkout outcome, which is what an agent needs to chain a payment flow. It omits precedence when both amount and package are supplied, a real ambiguity in a 0-required-parameter schema.

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 description largely restates the same amounts, package tiers and $0.001/credit conversion already documented in the schema properties. It adds little syntax or selection guidance 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?

States a specific verb and resource ('Top up your MyMedi-AI credits') and immediately names the concrete mechanism and return value ('Creates a Stripe Checkout session and returns a checkoutUrl'). No sibling tool touches billing, so an agent can identify it at a glance.

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?

Explains the crucial usage fact that calling it charges nothing and that the agent must open the URL for payment to complete, and presents the two acquisition paths (amount vs package) as alternatives. It does not state exclusions or prerequisites (e.g. account must be authenticated), 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?

Adds real behavior beyond the annotations: what is checked, that a missing fee-schedule CPT or unlisted DMEPOS modifier is a warning rather than an error, per-claim limits, and what the response contains. It does not address the non-idempotent hint (idempotentHint=false on a pure validation), leaving a small unexplained trait.

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 and front-loaded, with the core check stated first and exclusions/edge cases after. A few clauses (limit counts, warning/error detail) are packed tightly but each carries decision-relevant 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?

For a single nested-parameter, read-only validator with no output schema, the description covers inputs expected, limits, validation rules, warning-vs-error semantics, and return shape. An agent has everything needed to call it correctly and interpret results.

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 the schema does not: which code systems each array expects (ICD-10-CM vs CPT/HCPCS Level II), that modifiers must be well-formed, and that the date of service cannot be in the future. Cardinality limits restate schema maxItems, which is redundant but harmless.

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

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

States a specific verb and resource ('pre-submission check of a claim's codes and dates') and immediately bounds scope ('no patient or provider identifiers needed or accepted'). It is clearly distinguishable from code_validate / code_validate_batch, which operate on codes rather than a full claim.

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 strong when-to-use context (pre-submission) and explicit exclusions — no NCCI PTP/MUE edits, no medical necessity or prior authorization — which tells an agent when to reach for pa_required_check or compliance tools instead. It stops short of naming those siblings explicitly.

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

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

Beyond the annotations (which already declare readOnly/no-destructive/openWorld=false), the description discloses genuinely non-obvious behavior: results are curated, capped at 5 per system with a 0-1 relevanceScore, weak matches are dropped so groups can be empty, and a call with no related codes is refunded. That refund/billing detail is especially valuable and explains the idempotentHint=false annotation. It does not explain ordering or whether the code type is auto-detected.

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

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

It is one dense run-on paragraph mixing purpose, output semantics, and provenance; the two distinct result groups (linkedCodes, crossReferences) would be much clearer as separate structured lines. The closing 'Source: the MyMedi-AI code database (ICD-10-CM, CPT and HCPCS Level II code sets)' partly repeats code systems already stated up front.

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 burden of explaining returns, and it does: both result groups, the per-system cap, relevanceScore range, and the empty/refund case. What remains thin is the shape of the linkedCodes entries (DME families, cited LCD/NCD sources) and how code system is inferred from the input.

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?

Only one parameter, and schema coverage is 100% with concrete examples ('M79.3', '99213', 'E0601') already in the schema. The description adds no syntax or normalization guidance beyond the schema, so the 3 baseline for high coverage 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?

Opens with a specific resource and scope: 'Related codes for an ICD-10-CM, CPT or HCPCS Level II code, across the three code systems,' which tells an agent exactly what it returns and distinguishes it from single-code lookups by its cross-system, related-code scope. It never names a sibling (code_lookup, code_suggest, code_lookup_basic) to sharpen the boundary, 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?

Usage is only implied by the resource name; the bulk of the text describes return structure (linkedCodes vs crossReferences) rather than when to choose this over code_lookup or code_suggest. There are no explicit exclusions or preconditions (e.g., whether the code must already be valid).

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 (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the description goes beyond them usefully: it discloses the data source and freshness ("current CMS DMEPOS fee schedule quarter") and the branch-dependent response shape (national min–max per modifier RR/NU/UE vs. exact state non-rural/rural rates). It does not cover error behavior for unknown or expired codes.

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

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

Front-loaded with the core action and return fields, then the conditional fee-schedule detail. Three sentences, all carrying information; only the parenthetical code-system list mildly duplicates the title.

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?

There is no output schema, so the description correctly takes on the burden of listing return values (description, category, active status, related codes, fee schedule) and does so. Minor gap: no mention of what happens for invalid/retired codes or when fee data is unavailable for a given code type.

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

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

Schema coverage is 100%, so baseline would be 3; the description earns an extra point by explaining the semantic consequence of the `state` parameter — that supplying it switches the output from a national range to exact state-level non-rural and rural rates, and only applies to DMEPOS codes. It adds nothing new for `code` or `codeType`, which the schema already documents.

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 ("look up") and resource (a medical code) and enumerates the exact code systems it accepts (ICD-10, CPT, HCPCS), then names the returned fields. It is clearly distinguishable from siblings like drug_lookup or pa_required_check, but it does not distinguish itself from the very similar code_lookup_basic, code_reimbursement, or fee_schedule_lookup.

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 when-to-use guidance and no named alternatives, despite three close siblings (code_lookup_basic, code_reimbursement, fee_schedule_lookup) that an agent could easily confuse it with. The conditional state/DMEPOS behavior is described, but that is invocation behavior, not tool selection guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations: it says the lookup is free, needs no API key, and returns only basic metadata fields.

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 short and front-loaded, with the core action and returned fields stated first. The phrase 'Basic metadata only' slightly repeats the opening, but overall it is efficient.

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 one-parameter read operation with full schema coverage and rich annotations, the description provides enough context by naming the returned fields and noting cost/auth constraints. It does not explain sibling routing or error behavior, but those are minor gaps for this tool's complexity.

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 sole parameter is already documented with an example. The description repeats that a medical code is looked up but adds no extra format, validation, or edge-case details 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 states a clear verb and resource: looking up basic metadata for a medical code, and lists the returned fields. It distinguishes itself somewhat with 'Basic metadata only' but does not explicitly contrast with the sibling code_lookup or code_lookup_batch tools.

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 'Basic metadata only. Free, no API key required' implies the tool is for lightweight, unauthenticated lookups. However, it gives no explicit when-to-use or when-not-to-use guidance and does not point to code_lookup for richer results.

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

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

Beyond the annotations, the description discloses important behavioral details: pricing is per code at $0.001 × code count, the maximum is 25, and the full charge is refunded when every code misses. It also summarizes the per-item return fields, including DMEPOS fee schedule behavior when a state is supplied.

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 tightly written sentences. It is front-loaded with the core lookup purpose, then adds return behavior, pricing, maximum, and refund condition without redundant restatement.

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 appropriately enumerates what each item returns and explains the cost model and batch limit. It does not describe error behavior for invalid codes or partial misses beyond the all-codes-miss refund, but it is otherwise complete for correct invocation.

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 input schema already documents all three parameters, including the codes list, state filter, and codeType enum. The description adds only limited extra parameter meaning, such as reinforcing that state affects DMEPOS fee schedule output, so it meets the baseline rather than exceeding it.

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

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

The description opens with a specific verb and resource: look up a list of medical codes across ICD-10, CPT, and HCPCS. The phrase "in one call" clearly distinguishes this batch operation from single-code lookup siblings, and the supported code systems are 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 description makes the batch use case clear by saying it looks up a list of codes in one call and enforces a 25-code maximum. It does not explicitly name single-code alternatives or state when validation rather than lookup is appropriate, so it lacks full routing guidance despite clear 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 declare read-only, closed-world, non-destructive behavior, so the safety profile is covered. The description adds genuinely useful provenance (CMS RVU files, PFS conversion factor) and states what is returned. It does not disclose data-year/freshness limits or behavior for unknown/unsupported codes, and it silently narrows the title's 'PFS + OPPS' claim to PFS only.

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

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

Three short sentences, front-loaded with the action and result, with provenance last. Slightly redundant: 'PFS conversion factor' and 'Medicare PFS (CMS RVU files)' restate the same source twice.

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 names the return fields (RVUs, estimated payment), which is a real contribution. It still leaves gaps an agent would care about: whether OPPS facility rates are covered as the title implies, which payment year the RVU files represent, and error handling for invalid codes.

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%, including examples for `code` and an enum plus auto-detection note for `codeType`, so the schema carries the semantics. The description adds nothing about code formats, auto-detection, or what happens when codeType conflicts with the supplied code.

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

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

States a specific verb and resource ('Look up Medicare reimbursement rates for a medical code') and even names the output (RVU values, estimated payment). However, it does not distinguish itself from siblings like reimbursement_basic or fee_schedule_lookup, which an agent could easily confuse it with.

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 when-to-use or when-not-to-use guidance is given, and no alternative sibling is named. The agent must infer from the name alone whether to call this or reimbursement_basic / fee_schedule_lookup / code_lookup_basic.

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

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

Annotations already declare readOnly, non-destructive, closed-world and non-idempotent behavior, so the safety profile is covered. The description adds real context beyond that: relevance ranking with relevanceScore 0-1, grouping of best-per-mentioned-entity, default-code behavior for bare conditions, weak matches omitted, and automatic refund when nothing matches. That is meaningful but mostly ranking semantics rather than operational constraints like latency or 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?

Front-loaded with the core verb+resource and mechanism, and every clause carries information. It is, however, a single dense paragraph with long parentheticals and nested exceptions that make the ranking rules harder to parse than necessary.

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?

There is no output schema, and the description compensates by explaining the return ordering, the relevanceScore field, grouping behavior, and omission of weak matches — everything an agent needs to interpret results. Given only three simple parameters, nothing material is left undocumented.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds interpretation the schema lacks: what kinds of text the description parameter accepts (natural sentences, abbreviations, side/sex qualifiers) and the effective 500-character/10-term search behavior behind it. It says nothing extra about limit or codeType beyond the schema, which keeps it at 4 rather than 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?

The description opens with a specific verb+resource ("Suggest ICD-10-CM, CPT and HCPCS Level II codes from a clinical or equipment description") and even names the mechanism (term search over the CMS database, no language model). It is clearly distinguishable from lookup-style siblings by emphasizing natural-language input, but it never names or contrasts an actual sibling such as code_lookup or code_lookup_basic.

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

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

It gives concrete guidance on what input works: natural sentences, abbreviations, alternate forms, typed side/sex/"without", 500-character cap and 10-term search limit, plus an example. It stops short of explicit when-to-use/when-not or routing to alternatives like code_lookup for exact-code resolution.

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, idempotentHint false, destructiveHint false, so the safety profile is covered. The description adds important behavioral context beyond annotations: it applies termination and effective dates, explains that a code deleted after the date of service still validates, states the default date is today, and mentions the asOf result field and return fields (valid, active, warnings, errors). This is solid behavioral disclosure for a read-only validation tool.

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

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

Three sentences, front-loaded with the primary purpose and key date logic, then the date parameter default, then return fields. No wasted words; every sentence contributes useful 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?

Given no output schema, the description helpfully lists return fields (valid, active, warnings, errors) and explains date-of-service behavior and the asOf result. Annotations cover the safety profile. The main remaining gaps are the unexplained context object and the lack of detail on the codeType enum, but for typical use the definition is mostly 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 description coverage is 60%, so the baseline is 3. The description repeats the dateOfService format and default, and implies code types (ICD-10-CM, CPT, HCPCS) which maps to the codeType enum, but it does not explain the context object, the duplicate dateOfService/date_of_service parameters, or the codeType enum values. It adds some value but doesn't compensate for the remaining schema 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 states a specific verb (Check/validate) and resource (ICD-10-CM, CPT, HCPCS Level II code), and uses singular 'a code' which implicitly distinguishes it from the batch sibling code_validate_batch. An agent can immediately tell this validates one code's existence and validity on a date.

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

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

Usage is implied by 'Check that ... a code exists and is valid' but there is no explicit when-to-use versus alternatives like code_validate_batch or code_lookup, nor any stated exclusions or prerequisites. The description gives enough context to infer its purpose, but stops short of routing guidance.

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

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

Goes well beyond the readOnly/openWorld/idempotent annotations: discloses pricing ($0.005 per code, capped at 25), the fields returned per item, that dateOfService is applied uniformly with today as default, and that an invalid code is still a billable answer (valid:false). That last point is unusually valuable behavioral context for a paid validation call.

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 dense sentences, all front-loaded with the verb and scope first, then return shape, then cost. Every sentence carries distinct information, though the 'each judged as in a single validation' clause is slightly awkward and the sentence packing makes it feel compressed.

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, so the description carries return-value burden and does it by enumerating valid, active, asOf, warnings, errors and codeDetails. Combined with cost and default-date semantics, an agent has what it needs to call correctly; only the duplicate date-parameter aliasing is left undocumented.

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 80%, so the baseline is 3; the description earns a bump by restating the date semantics with the default value and the uniform-application rule, and by tying array length to the price. codeType and the dateOfService/date_of_service aliasing are left entirely to 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 and resource ('Validate ... medical codes') plus the batch scope ('up to 25 in one call'), which implicitly separates it from the single-code code_validate and from code_lookup_batch. It also names the per-item judgement criteria (exists, valid on date of service), so an agent knows exactly what the tool decides.

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 batching context is clear (25-code cap, per-code price, date default) so an agent can tell this is the multi-code path and that cost scales with item count. It stops short of explicitly routing: neither code_validate nor code_lookup_batch is named, and there's no when-not to use it.

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?

Adds substantial context beyond the annotations: 250 credits per call, refund-on-refusal behavior for phased-in states and non-billable/discontinued codes, fail-closed semantics ('a fact not reported fails'), and confirmation that it evaluates reported facts rather than documents. These are operationally decisive details an agent cannot get from readOnlyHint/openWorldHint alone.

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

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

Front-loaded with the core verb and resource, and the dense clauses each carry distinct information (refusal cases, phase-in, cost, exclusions). The single long paragraph and nested parentheticals make it heavier than ideal, but little is genuinely expendable.

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?

Covers inputs, refusal paths, phase-in-by-state caveat, cost, and result semantics (per-requirement pass/fail with citation, overall result fail). With no output schema, the description nonetheless explains what comes back well enough for an agent to interpret the response.

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 real meaning: it explains that facts are true/false flags carrying no names, MBIs, signatures or values, and that an unreported fact is treated as a failure. That changes how an agent should populate and omit fields, which the schema alone does not convey.

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

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

States a specific verb and resource (audit one DMEPOS order's documentation) scoped to Original Medicare rules keyed off HCPCS code and date of service. It is clearly distinguishable from siblings such as pa_required_check or order_readiness_checklist because it self-describes as a citation-backed pass/fail audit of reported facts.

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

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

Gives concrete applicability conditions (which items require F2F/WOPD or prior auth, when a state is required, which codes get refused) and an explicit exclusion list (LCD coverage, medical necessity, proof of delivery, modifiers). It does not name an alternative sibling tool to use instead when the order falls outside scope, which keeps it below 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds value beyond that by enumerating the response payload (title, meaning, common DME causes, fixes, appealability, related codes) and stating the free/no-API-key access constraint, which is real operational context.

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

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

Three short sentences with zero waste: purpose first, return payload second, access constraint last. Every sentence earns its place 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?

With one parameter and no output schema, the description correctly compensates by listing the returned fields and noting no auth is required. Minor gap: it doesn't state what happens for an unrecognized code, so behavior on invalid input is unknown.

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 single parameter already carries an example set ("CO-50", "PR-1", "197"). The description adds nothing about code format, prefixes, or acceptable variants. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Explain a DME claim denial code (CARC)'. That is far more targeted than a generic code lookup and the acronym CARC anchors the domain. It doesn't name or contrast itself with siblings like code_lookup or code_reimbursement, so an agent must infer that this is the denial-specific explainer.

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

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

Usage is implied by the resource itself: this is the tool for denial codes. There is no explicit when-to-use vs when-not, and no reference to alternatives such as code_lookup for non-denial codes. Adequate but leaves routing to inference among 30 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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by naming the upstream source (CDC NNDSS weekly data on data.cdc.gov), which conveys provenance and update cadence. However, it says nothing about behavior with zero filters (only three optional parameters), result volume, or limits, which matters for an open-world lookup.

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 capability and closing with the data source. No filler or restated title text.

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 three simple optional parameters and no output schema, the description supplies the essential framing plus provenance. It is slightly incomplete in not addressing the all-optional call case (what an unfiltered query returns) or result granularity, but nothing critical is missing for a read-only lookup.

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 each parameter is already documented in the schema, and the baseline of 3 applies. The description's 'by condition and geography' mildly echoes the condition and state filters but never mentions the ICD-10 code auto-mapping parameter, so it adds no 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?

Specific verb (look up) plus specific resource (disease surveillance data, case counts and trends) and named scope (condition, geography). The CDC NNDSS source identifier makes it unambiguous against every sibling, none of which touch surveillance 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?

The 'by condition and geography' phrasing implies how to call it, but there is no explicit when-to-use guidance, no statement of when to use this instead of code_lookup or ner_extract, and no explanation of whether filters are combinable or optional. The agent must infer usage from the parameter list.

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 cover the safety profile (readOnly, non-destructive, open-world), and the description adds genuinely non-obvious behavior on top: only the FIRST matching label is returned, missing label sections come back as null rather than erroring, the summary is LLM-generated and labelled as such, and failed calls are refunded. The refund-on-failure and first-match-only semantics are the kind of detail an agent cannot get from any structured field.

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 sentences, each doing distinct work: what is returned, what the LLM adds, what it refuses to do, and what happens on failure. The returned-field enumeration is dense but front-loaded and necessary given there is no output schema.

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 itself and does so thoroughly, including null-section behavior and the LLM summary caveat. Failure modes (drug not found, openFDA or model unavailable) and the refund are also disclosed, leaving no obvious gap for an agent calling this correctly.

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

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

Schema coverage is 100%, so both parameters are already documented; the description reinforces the brand-vs-generic matching axis that searchField controls. It does not restate the default (brand_name) or the 2-char minimum, but the schema already carries those, so this is a modest addition 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?

States a specific verb and resource ('look up a drug by brand or generic name in openFDA') and then enumerates exactly what comes back: names, manufacturer, NDCs, route, substance, product type, and specific label sections. The exclusion sentence ('does not check interactions between drugs, makes no prior-authorization, coverage or cost determination') cleanly separates it from drug_interactions, pa_required_check and the reimbursement siblings.

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

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

Clearly delimits scope with three negative conditions (no treatment advice, no cross-drug interaction checking, no PA/coverage/cost determinations), which implicitly routes the agent to siblings for those needs. It never names an alternative tool explicitly or states the positive trigger condition (e.g. 'use when you need label text for a specific drug'), so routing is inferential rather than spelled out.

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

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

Beyond the readOnly/openWorld annotations, the description discloses the refusal-and-refund behavior for unknown drug names, the null result when a comparison cannot be computed, the exact disproportionality threshold (≥3 co-reports, lower bound >1 against every drug), and the brand-vs-generic non-merging rule. It also warns that FAERS reports are unverified, duplicable, and associational — meaningful context the 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?

Every sentence carries information, but the opening is a long dense clause chain that leads with return fields rather than a one-line statement of what the tool does. It is efficient yet slightly front-loading-poor.

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 one parameter, full schema coverage, and no output schema, the description still explains what is returned (counts, reactions, PRR with CI) and what edge cases produce (nulls, refusals). 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%, so the baseline is 3, but the description adds real semantic value: names are matched against the reported product name, and a brand such as Coumadin is not merged with warfarin. The normalization details are largely duplicated from the schema, which caps this at 4.

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

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

The description names the exact resource (FAERS reports naming drugs together) and the exact computation (coReportCount, top reactions, PRR with 95% CI versus each drug alone). This is clearly distinct from siblings like drug_lookup, drug_enrich, and drug_rxnorm, which do not compute disproportionality. An agent can identify this tool without opening the 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?

Usage context is clear: 2-5 drugs, combination-level analysis, and an explicit exclusion ('no substitute for a clinical drug-interaction reference'). It does not name a specific sibling tool to use instead for single-drug or interaction-reference needs, 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 readOnlyHint=true, openWorldHint=true, destructiveHint=false, so safety is covered. The description usefully adds data provenance (openFDA plus an internal code database), which tells the agent about source reliability. However, it does not explain the return shape, why idempotentHint is false, or any rate-limit/latency behavior for an external API.

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, no filler, with the data scope front-loaded and provenance placed second. It could be tightened by clarifying what the primary return value is, but there is no 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?

There is no output schema, so the description carries the burden of explaining what comes back. Listing three heterogeneous data types without saying how they are structured, combined, or paginated leaves a real gap for an agent deciding whether this single call suffices.

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 both drugName and searchField are fully documented in the schema, including the enum values and default. The description adds nothing about parameters, so baseline 3 applies.

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

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

The description names a verb and resource ('Look up drug information') and enumerates three data types (label data, adverse events, diagnosis codes), but it is ambiguous about whether all three are returned in one call or which one dominates. It also fails to distinguish the tool from siblings like drug_rxnorm, drug_interactions, and drug_enrich, which also look up 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?

No guidance is given on when to choose this tool over the many drug-related siblings (drug_rxnorm, drug_enrich, drug_interactions). There are no prerequisites, exclusions, or routing hints; the agent must infer everything from the name.

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=true, so the safety and external-dependency profile is covered; the description adds value by naming the underlying service (RxNav API, NLM) and by enumerating the returned concept fields since there is no output schema. It omits practical traits such as how multiple candidates are ranked, whether the primary RxCUI is deterministic, and any latency/rate-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?

Three short sentences, front-loaded with the verb and resource, then return shape, then the negative scope and source. No filler and no repetition of the title.

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, no-output-schema lookup tool this covers what the agent needs: what comes back, what it does not do, and where the data originates. The remaining gap is how ambiguous or multi-match names are handled and whether the 'primary RxCUI' is a best-match or a fixed selection.

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

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

There is a single parameter with 100% schema description coverage ('Drug name to look up (min 2 chars)'), so the schema already carries the semantics. The description only echoes 'a drug name' without adding guidance on what forms are accepted (brand vs generic, combination products, dosage forms), 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?

States a specific verb+resource ('Normalize a drug name with NIH RxNorm') and enumerates the return fields (RxCUI, name, synonym, term type, primary RxCUI). The explicit exclusion ('does not check interactions') cleanly separates it from the drug_interactions sibling, and the source attribution removes any ambiguity about which normalization system is used.

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 'does not check interactions' caveat gives the agent an explicit routing signal toward drug_interactions, which is real usage guidance. It stops short of distinguishing this from ambiguous siblings like drug_lookup and drug_enrich, leaving the agent to infer which one is the right normalization path.

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

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

Annotations already declare readOnly, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the output shape changes with the presence of state, and the data source is the current CMS DMEPOS quarter, which tells the agent about data freshness.

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 dense but well-structured three-sentence description; the core lookup, the state/modifier behavior, the data source, and the exclusion each appear once with no 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?

No output schema exists, so the description carries the burden of indicating what comes back, and it does describe exact per-state rates versus national ranges plus the data source. It could say more about return fields or units, but it is sufficient for correct invocation.

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 already documents the state exact-vs-national behavior and the RR/NU/UE modifier meanings, so the description largely restates what the schema provides. It adds only a slight interpretive gloss ('a modifier narrows the answer to rental or purchase'), consistent with the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource (look up the CMS DMEPOS fee schedule for a DME/orthotic/prosthetic HCPCS code) plus the domain boundaries (rental vs purchase, rural vs non-rural, per state). This clearly separates it from siblings like reimbursement_basic or code_reimbursement.

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?

Explains the operational choice between supplying a state (exact rates) versus omitting it (national min–max ranges), and gives an explicit exclusion: 'no professional-service (CPT) rates.' It does not name a specific alternative tool, which keeps it from 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?

Goes well beyond the annotations: it discloses that the NPPES query caps at 200 records so the figure is a floor rather than a true provider count, that the demand/opportunity text is LLM-generated and explicitly labelled, and that a failed call due to model unavailability is refunded (implying a per-call cost). Missing only latency or credit-amount detail to reach a 5.

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

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

Purpose is front-loaded in the opening clause, and the caveat sentences each carry a distinct constraint (truncation, LLM provenance, refund). The single dense opening sentence packs several ideas together, but little is redundant.

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 burden of describing returns, and it does name the components (matched-provider floor, demand outlook, underserved areas, opportunities). It stops short of specifying the response shape or ordering, leaving a small gap for a two-field analytical 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 description coverage is 100%, with the state enum and the specialty taxonomy/prefix-wildcard syntax already documented inline. The description adds nothing about parameter semantics beyond the schema, 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 states a specific verb and resource: a specialty snapshot for a US state combining a CMS NPPES query count with an LLM-generated demand outlook. It also carves out what it is not ("Not a CMS or quality measure"), which separates it from the lookup/validation siblings. An agent can tell what it produces without opening the 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?

Usage context is implied (market/demand sizing for a specialty in a state), and the negative framing rules out clinical/quality use. However, no sibling is named — an agent weighing provider_search or disease_surveillance gets no explicit routing guidance, and no prerequisites or when-not-to-call conditions are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, and the description is consistent with a pure advisory read. It adds context beyond the annotations: the output is editorial rather than payer policy, it is PHI-free, and it is free with no API key, which matters for call planning. It does not describe the shape of the returned guidance or any limits on modifier coverage.

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

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

Front-loaded with the resource and its covered modifier families, then moves to input mechanics and caveats. Dense but every clause carries information; the trailing 'Free, no API key required' is slightly promotional but still useful to an agent deciding whether it can call it.

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

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

All three optional parameters are documented at 100% coverage, annotations carry the safety profile, and no output schema exists so return values need not be specified. The main residual gap is that the description never indicates what the guidance response looks like (modifier list with rationale? ranked?), leaving the agent to discover output shape at call time.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: a code scopes guidance to that item's DMEPOS category, a category can be supplied directly as an alternative, and the scenario argument is a free-text situation phrase with worked examples ('ABN on file', 'bilateral'). The code-vs-category relationship is meaningfully clarified beyond the schema's one-line field docs.

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

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

States a specific verb and resource: 'Editorial guidance on DMEPOS billing modifiers,' then enumerates the exact modifier families covered (KX/GA/GY/GZ, RR/NU/UE, KH/KI/KJ, RT/LT). This is far more specific than any sibling (code_lookup, pa_required_check, code_validate) and an agent can tell instantly this is the modifier-interpretation tool, not a lookup or validation tool.

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?

Explains the two ways to scope a request — a HCPCS code (mapped to its DMEPOS category) or a category directly — and that a scenario phrase surfaces the relevant modifiers. It also sets an explicit boundary: 'Original editorial content, not payer policy,' which tells the agent when NOT to rely on it for authoritative payer determinations. It stops short of naming sibling tools to redirect to.

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, closed-world behavior, and the description adds substantial context: code-set checking, inCodeSet and codeSets output, modifier handling, date and medication-indicator extraction, and PHI-free constraints. It discloses behavior well beyond the annotations without contradicting them.

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

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

The description is front-loaded with the core extraction purpose and then supplies necessary edge-case rules. It is dense and somewhat run-on, but the detail is largely justified by the complexity of code extraction.

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 still explains the returned entity types, code-set membership fields, codeSets metadata, dates, and medication indicators. It is complete enough for an agent to understand what the tool returns and when to use it.

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

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

Schema coverage is 100%, so both parameters are already documented in the input schema. The description does not add parameter-specific syntax or filtering details beyond what the schema provides, so the baseline of 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 and resource: extract medical codes already present in de-identified text and check them against the MyMedi-AI code database. It explicitly distinguishes extraction from inference/suggestion, which separates it from sibling tools like code_suggest.

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

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

It gives clear usage context: de-identified text only, no drug-name extraction, and no inference or suggestion of codes. It does not explicitly name sibling alternatives, but the exclusions make the intended use 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 carry readOnly/idempotent/closed-world, but the description adds genuinely non-obvious behavior: it returns blank requirement definitions rather than a patient-specific determination, is PHI-free by construction, is free and needs no API key, and returns null for paRequired on state-phased items until a state is supplied. That null-semantics disclosure is the kind of edge case an agent would otherwise misread as a false negative.

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

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

A single dense paragraph that front-loads the core definition and then tacks on scope, nullability, and cost facts — no wasted sentences. Minor redundancy: 'free' appears both in the title and again as 'Free, no API key required' at the end, which could be folded into one place.

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

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

With no output schema, the description does the necessary work of telling the agent what comes back (SWO elements per 42 CFR 410.38(d), F2F/WOPD status, PA-list status) and even names one return field (paRequired). It stops short of describing the output shape or the other field names/types, which for a three-part checklist would help an agent consume the result.

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 and the schema already explains code, state enum, and the today default for dateOfService. The description still earns credit by explaining the conditional interaction between state and the returned paRequired field, which is the one parameter behavior the schema cannot express.

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 first clause gives a specific verb and resource ('Blank pre-delivery checklist for a HCPCS DMEPOS code') and then enumerates the three things returned: SWO elements, F2F/WOPD list membership, and prior-authorization list membership. It is clear what the tool is, though it never names the overlapping sibling 'pa_required_check', so an agent must infer from the description alone that this is the broader multi-element checklist rather than the single PA boolean.

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?

Useful operational cues are present ('Requirement definitions only; it takes no patient data', 'Some items are phased in by state: for those, paRequired is null until a state is given', which implies supplying state matters). However, there is no explicit when-to-use vs. when-to-skip framing and no named alternative among the many PA siblings, so routing is implied rather than 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 (readOnlyHint true, destructive false), yet the description adds genuinely non-obvious behavior: per-code pricing ($0.01 × codes, max 100), that unknown/non-HCPCS codes are flagged but still billed, and that output is PHI-free JSON. It stops short of describing error handling or latency, so not a 5.

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

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

Front-loads the core mapping action, then layers the state caveat, output shape, pricing, and scope in a dense but logical order. Nearly every sentence carries distinct information, though the long second sentence is somewhat run-on.

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 well: it enumerates per-code return fields (PA requirement and effective date, F2F/WOPD, documentation gates, denial-risk flags), the catalog-level summary, and the paRequiredInSomeStates fallback. An agent has enough to decide whether the result answers its question.

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 each parameter is already documented (codes 1-100, state for phased-in items, dateOfService default today). The description's explanation of the state-dependent branch reinforces the schema rather than adding new parameter syntax or constraints, 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?

States a specific verb and resource — mapping a supplier HCPCS catalog against the CMS PA and F2F/WOPD lists on a date of service — with explicit scope (up to 100 codes, Original Medicare FFS). It does not name a sibling to differentiate from pa_required_check or pa_required_check-style tools, so the boundary has to be inferred from the batch 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?

The state caveat ('with a state the answer is definitive; without one they are reported as required in some states') implies when to supply the state parameter, and the 100-code cap implies batching. But there is no explicit when-to-use versus pa_required_check/pa_predict, and no prerequisites are stated beyond scope.

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?

Goes well past the readOnly/openWorld annotations: it discloses the privacy boundary (own organization only, never other customers), the minimum cohort of 10, the no-organization/no-cohort edge case, the refund on the no-rate path, that the recommendation states CMS requirement only, that no coverage determination is made, and the Original Medicare FFS scope. That is exactly the extra context 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?

Front-loaded with the core purpose, but it is a single dense run-on of em-dash clauses with some repetition ("never from other customers' records" restates the own-organization point) and a parenthetical about refunds buried mid-sentence. Correct information, harder to scan than it needs to be.

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 itself, and it does: it describes the rate-plus-cohort-size-plus-confidence payload on one path and the CMS status/category/review-timeframe payload plus a no-rate report on the other. Nothing an agent needs to interpret either response 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 explains procedureCode as CPT/HCPCS and payerId as a payer category rather than a payer ID number. The description reinforces that the cohort is scoped to the organization's own decided PAs, but adds no format, validation, or edge-case 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+resource: a historical prior-auth approval rate for a procedure code drawn from the caller's own organization's decided PAs. It also names the fallback payload (CMS Required Prior Authorization List status, category, review timeframes), which helps distinguish it from pa_required_check and pa_status, though it never names those siblings outright.

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 makes the two operating regimes explicit — a cohort of at least 10 decided PAs yields a rate, otherwise CMS facts are returned — but it never says when to pick this tool over pa_required_check, pa_status, or pa_exposure_report. Usage is implied by the data-availability conditions rather than stated as selection guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantial context on top: no API key needed, no cost, the null-return behavior for state-phased items, and the FFS-only scope that excludes Medicare Advantage. This tells the agent exactly what it will and will not get back before calling.

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 tight sentences, front-loaded with the core check and followed by return values, the state caveat, and scope. No repetition of the title or 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?

With no output schema, the description carries the return-value burden and does it: paRequired flag, category, nationwide-since date, and list version are all enumerated. Combined with the null caveat and scope limit, an agent has everything needed to call and interpret the result.

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 the consequence the schema omits: omitting state yields paRequired = null for phased-in items rather than a wrong answer. That is meaningful semantics beyond the enum list and the 'default today' note.

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

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

States a specific verb and resource: checks whether a HCPCS code appears on the current CMS Required Prior Authorization List under 42 CFR 414.234, and names the exact return fields. This clearly separates it from siblings like pa_predict (prediction) and pa_status (status of a submitted request), since it is a deterministic list lookup.

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

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

Gives clear operating context: a date of service defaulting to today, the condition under which state must be supplied (state-phased items), and a scope limitation (Original Medicare FFS). It does not explicitly name pa_predict or pa_status as alternatives, so routing between the three prior-auth tools still requires inference.

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

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

Annotations already cover read-only, non-destructive, non-open-world behavior, so the description's added value is the miss case: returns not-found/refunded when the PA was never entered in the web app, and the fact that no payer round-trip occurs. That is genuine behavioral context beyond the annotations, though the oddity of idempotentHint=false for a status read is left unaddressed.

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 core action, then return content, then exclusions and the miss case. No filler or restatement of the title.

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

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

For a read-only lookup with no output schema, the description supplies the returned data shape (status, dates, expiration info) and the not-found behavior, which is what an agent needs to interpret results. Minor gap: it does not clarify which parameter wins if both id and tracking number are supplied.

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

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

Schema coverage is 100%, so both trackingNumber and authorizationId are documented in the schema itself; the description only mentions the PA-id path and never explains the tracking-number alternative or how the two relate. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 (check) and resource (prior authorization status) with an explicit scope qualifier: PAs tracked in the MyMedi-AI web workspace, addressed by MyMedi-AI PA id. It also names what it is not (no payer query, no PA-requirement determination), which separates it from pa_required_check and pa_predict without opening either schema.

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

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

Clearly says when to use it (PA already entered in the web app) and gives explicit exclusions ('does not query payers or say whether a code requires prior authorization'), which routes the agent away from it toward the requirement-check tools. It never names the alternative sibling tools directly, so the routing is inferential rather than explicit.

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

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

Annotations already cover read-only, non-destructive and open-world, yet the description goes further: the LLM output is labelled as an estimate, the model receives only provider type (never name or NPI), and failed calls are refunded. It does not explain why idempotentHint=false (presumably non-deterministic LLM output) or mention cost/latency, which would have completed the picture.

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

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

Front-loaded with the core lookup, then the enrichment, then constraints (privacy, disclaimer, refund). Dense but nearly every clause carries information; the absence of headings or line separation makes the caveats easy to skim past.

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 1-parameter read-only tool with no output schema, it names the registry fields returned and the three enrichment outputs, plus failure behavior. Only the shape of the returned estimate and its cost remain unspecified.

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 single npi parameter is already documented as a '10-digit NPI number'. The description adds only that the number resolves against the NPPES registry, no extra format or validation guidance — 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?

States a specific verb+resource (look up a provider by NPI in the CMS NPPES registry) and enumerates the fields returned plus the AI-generated additions (specialty demand, network gaps, referral categories). It does not name or differentiate against the obvious sibling provider_search, so an agent must infer which to pick for name-based lookups.

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 NPI-keyed framing plus 'Not a CMS or quality measure' implies when it applies, but there is no explicit when-to-use/when-not or routing to provider_search for non-NPI searches. Usage is inferable rather than stated.

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

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

Annotations already declare readOnly=true, destructive=false, openWorld=true, so the safety profile is covered. The description usefully discloses the return shape (totals, type breakdown, top companies) and the upstream source, but omits things that matter for CMS data: reporting-year coverage/lag, whether results are empty for physicians with no payments, and idempotency/mutability of upstream data.

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 plus a source tag, with the purpose and return contents front-loaded and zero filler. Every clause earns its place.

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

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

With one parameter, full schema coverage, and no output schema, the description's summary of returned fields (totals, breakdown, top companies) fills the output-schema gap well. A note on data year/freshness and the no-payments case would make it 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 100% and the single npi parameter is fully documented as a 10-digit NPI, so the schema carries the load. The description adds nothing about the parameter (e.g., format validation, whether name lookup is possible), which is acceptable at this coverage level but not a value-add.

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?

"Look up pharmaceutical and device company payments to a physician" states a specific verb and resource, and the Sunshine Act/CMS attribution makes the data source unambiguous. It is clearly distinct from code/drug/claims siblings, though it does not explicitly separate itself from the closer provider_search/provider_enrich tools.

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

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

Usage is implied by the required single parameter (a physician NPI), but the description never says when to prefer this over provider_enrich or how it relates to any other payment/compliance tool. No exclusions, prerequisites, or alternative routing are given.

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

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

The annotations already declare this as a read-only, open-world, non-destructive search, so the safety profile is covered. The description adds that the data source is the NPI provider directory, but does not disclose result limits, ordering, authentication needs, or other search behavior beyond the general field categories.

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, front-loaded with the core action and followed by the supported search dimensions. There is no filler or repetition.

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 seven-parameter, all-optional read-only search, the description is adequate but thin. It omits routing guidance versus provider_enrich and does not clarify whether at least one search field is expected, leaving some operational uncertainty despite the annotations and schema covering the rest.

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 43%, so the description must add meaning. It partially compensates by grouping searches into name, specialty, and location, which maps conceptually to the undocumented name and city parameters, but it does not clarify all optional combinations or the limit parameter beyond what the schema already states.

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

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

States a specific verb and resource: search the NPI provider directory, and clarifies the searchable dimensions (name, specialty, location). It is clear against a generic tool list, but does not explicitly distinguish itself from sibling tools such as provider_enrich.

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 by saying it finds healthcare providers by name, specialty, or location, but it gives no explicit when-to-use guidance, prerequisites, or exclusions. It also does not tell the agent when to prefer provider_search over provider_enrich or other provider-related 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-structured context: the data provenance (CMS PFS RVU x conversion factor, current DMEPOS fee schedule quarter), that DMEPOS results are state-fee ranges, and that no API key is needed. It does not state error behavior for unknown codes or the currency/units, which keeps it short of a 5.

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

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

Two sentences, front-loaded with the purpose, with the formula parentheticals earning their place by establishing data provenance. The second sentence is dense and long, but every clause conveys distinct information about what is returned.

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, so the description must carry the return-value burden, and it does: facility vs non-facility amounts, rental/purchase ranges, and min–max across state fees. Missing details are minor (currency, behavior on invalid/unsupported codes, whether state-level lookup lives in a sibling 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?

With one parameter at 100% schema coverage, the schema already documents 'code'. The description still adds meaning by clarifying that the single input accepts both professional service codes (CPT-style) and DME items like E/K/L codes, and that the returned metric differs by code family. That is useful beyond the schema's bare example.

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

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

States a specific verb and resource ('Look up Medicare payment for a code') and names the two payment families it covers (PFS professional and DMEPOS). It does not explicitly differentiate itself from sibling tools like code_reimbursement or fee_schedule_lookup, so an agent must infer from 'national' and 'basic' naming which sibling 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?

Usage is implied rather than stated: the agent learns it is for Medicare payment on a code and that DME E/K/L codes are in scope. 'Free, no API key required' is a useful selection signal against paid siblings such as code_reimbursement, but there is no explicit when-to-use / when-not-to-use / alternative-tool routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the safety and externality profile is covered. The description contributes the external data source and the shape of returned trial records, but says nothing about result limits, pagination, or what happens when no selector is supplied; the 'active' wording also conflicts mildly with the COMPLETED status option.

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

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

Three short sentences with the capability and selectors front-loaded, followed by return contents and provenance. Every sentence carries distinct information and nothing is repeated from the schema verbatim.

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 sentence enumerating NCT ID, phase, enrollment, and eligibility usefully compensates and lets an agent judge result usefulness. Minor gap: all five parameters are optional, and the description never clarifies the behavior or error when none of condition/code/intervention is provided.

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 five parameters, including ICD-10 auto-mapping and the 50-result cap. The description restates three of the five selectors but adds no syntax, format, or precedence guidance (e.g., what happens if both code and condition are given), 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?

States a specific verb and resource (search clinical trials) plus the three selector inputs and the source registry, so it is clearly distinguishable from the drug/code siblings. The one flaw is the framing as 'active clinical trials' when the schema's status enum includes COMPLETED and NOT_YET_RECRUITING, so the stated scope slightly undersells what the tool retrieves.

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?

Naming condition, ICD-10 code, and intervention implies how to drive the tool, and the title ties it to ClinicalTrials.gov. But there is no explicit when-to-use guidance, no statement about needing at least one selector, and no routing to or away from any sibling tool.

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