Medicare Coverage

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description adds significant value by specifying default model, BYO key requirement for Anthropic, and detailing the return structure (per-model score, confidence, signals, raw_response, combined view). No contradictions.

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 well-structured sentences with front-loaded purpose. Every sentence adds necessary information without redundancy. No wasted words.

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

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

Despite no output schema, the description sufficiently explains the return structure. For a tool with 4 parameters (all described) and clear purpose, the description is complete and leaves no ambiguity about inputs and outputs.

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%, baseline is 3. The description adds value by explaining the entity parameter ('The thing to ask about') with examples like 'Pipeworx' and clarifying the context parameter as a disambiguating phrase. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score (0-100). It uses specific verbs and resources ('probe one or more LLMs') and distinguishes itself from siblings like ask_pipeworx or deep_research by focusing on AI visibility audits rather than general Q&A.

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

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

The description explains when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides context about default vs. paid models. It doesn't explicitly state when not to use it, but the purpose is clear and unique among siblings.

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

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

Adds context beyond annotations: mentions routing to a large set of tools, returns structured answers with citation URIs, works on every tier, one fast call. Does not contradict any annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false).

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?

Packed with useful guidance but slightly long. Front-loaded with purpose and preference. Each sentence adds value, but could be condensed slightly.

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?

Despite no output schema, description explains return format: structured answer with citation URIs. Covers many use cases. For a complex tool that queries 5k+ tools, it is fairly 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% with all parameters documented as aliases for 'question'. Description adds that the question is in natural language and provides multiple example values, adding value 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?

Clearly states the tool routes factual questions to 5,245 tools across 1,369 sources, with examples of data types (SEC filings, FDA drugs, etc.). Differentiates from siblings ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides guidance on when to use this tool vs ask_pipeworx_grounded (hallucination-resistant single answer) and deep_research (broad/multi-part questions). Also lists example queries and use cases.

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 significant context beyond annotations: explains no active candidate, current exact match, fallback behavior, and the experimental edge. All consistent with readOnlyHint and idempotentHint.

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?

Some redundancy (e.g., 'identical universal router' repeated), but front-loaded with essential info and overall 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?

Given annotations and schema, description fully explains purpose, current state, usage, and fallback. No output schema needed as response shape is same as sibling.

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

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

Schema coverage is 100% with thorough parameter descriptions including aliases. Description does not add new meaning beyond stating it accepts the same arguments as ask_pipeworx.

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?

Describes itself as a beta version of ask_pipeworx with identical capabilities, clearly distinguishing its experimental nature from the stable ask_pipeworx sibling. Purpose is clear but slightly verbose.

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

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

Explicitly states to use like ask_pipeworx when wanting the newest routing, and mentions results are compared to stable router. Could be more explicit about when not to use.

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

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

The description adds significant behavioral context beyond the annotations: it explains the extraction process, refusal reasons, and one extra LLM call cost. It is fully consistent with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 well-structured and front-loaded with the core purpose. Every sentence adds value—covering mechanism, return format, usage guidance, and cost trade-off. It is appropriately sized for the tool's complexity.

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?

Despite no output schema, the description fully specifies the output format, including refusal reasons. Combined with high-quality annotations and schema, the description is complete for an agent to use the tool effectively.

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 parameters are well-documented in the schema. The description does not add additional meaning beyond what the schema already provides (it mentions aliases, which are also in the schema). Baseline score 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 clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the mechanism (extracts answer only from tool result) and distinguishes it from its sibling 'ask_pipeworx' by highlighting the refusal guarantees and use cases.

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

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

Explicitly states when to use this tool (high-stakes reads, quotes, citations, acted on) and when to prefer the sibling 'ask_pipeworx' (casual lookups) due to the extra LLM call cost. This provides clear decision criteria for the agent.

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, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral context: market resolution and classification, parallel data fan-out, low-confidence short-circuits, closed market handling, wide-spread tradeability warnings, and cancellation rule parsing. This far exceeds what annotations provide, giving the agent deep insight into behavior.

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

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

The description is highly comprehensive but verbose, running several paragraphs. It front-loads the core purpose and usage, then dives into classifiers, fan-out examples, response shapes, resolver contracts, and safety notes. Every sentence adds value, but the overall length may overwhelm an agent. A more structured format (e.g., bullet points) could improve readability.

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 complex tool with 3 parameters and no output schema, the description is remarkably complete. It covers input formats, market resolution, classification, parallel fan-out, response structure (market, analysis, evidence), confidence levels, parent event extraction, news field fallbacks, safety locks for low confidence/closed markets, illiquid spread warnings, and cancellation rule impact. No major gaps remain.

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

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

Schema coverage is 100% with clear descriptions for 'market', 'depth', and 'include_raw'. The description adds value by explaining the 'market' parameter accepts slug, URL, or question text, and provides context for 'depth' (quick vs thorough) and 'include_raw' (response size trade-offs). While the schema does most of the work, the description enhances usability.

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

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

The description explicitly states the tool researches Polymarket bets by pulling Pipeworx data. It clearly identifies the verb (research), resource (Polymarket bet / Pipeworx data), and scope (one call). The usage examples ('should I bet on X', 'what does the data say about Y') plus the classifier list differentiate from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides clear when-to-use scenarios (e.g., 'should I bet on X') and lists example markets. However, it does not explicitly state when not to use this tool or mention alternatives among the 40+ sibling tools, though the context strongly implies its specific data-fan-out purpose.

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 beyond annotations: explains parallel call, off-calendar fiscal year handling, data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, output includes paired data and citation URIs. No contradiction with annotations.

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

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

Front-loaded with trigger phrases and usage guidance. Each sentence adds value; no waste. Slightly long but effective. Could be trimmed slightly without losing key details.

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

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

For a 2-param tool with no output schema, description covers input format, data sources, sorting, output URIs, and efficiency benefits. Minor gap: could mention exact output structure, but overall 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 100% (baseline 3). Description adds context: tickers/CIKs for companies, generic/brand names for drugs, max 5 items. Explains enum behavior and data sources per type, adding value beyond schema.

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

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

Description clearly states purpose: side-by-side comparison of 2-5 companies/drugs. Includes trigger phrases ('compare X and Y', 'head to head') and distinguishes from sequential lookups. Distinguishes from sibling tools like entity_profile.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides clear when-to-use guidance and explains input format for companies vs drugs, plus limits (2-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?

Beyond annotations (readOnly, idempotent, destructiveHint false), the description discloses time expectations (15-90s), facet decomposition and parallel routing, gap recovery, contradiction scanning, semantic excerpting, citation formatting, and that results are empty for topics outside the structured catalog. This comprehensive disclosure adds significant value.

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 lengthy but packed with essential information; every sentence provides value for correct tool selection and usage. It is front-loaded with account requirements and alternatives, then details behavior and outputs. Slightly more conciseness could improve, but given tool complexity, it is well-structured.

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

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

For a complex tool with 2 parameters and no output schema, the description explains the return format (findings packet with evidence, confidence, source, gaps, contradictions, hop field, citation_uri), covers account prerequisites, timing, data source scope, and error scenarios (empty gaps). It is fully self-contained.

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% but the description enriches parameter meanings: it explains depth values in terms of facet counts (quick=3, standard=5, thorough=8) and behaviors (gap recovery, contradiction scan), and clarifies that the question parameter accepts broad/multi-part input since decomposition is the point. This exceeds baseline expectations.

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

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

The description clearly states the tool does grounded multi-source research across Pipeworx's 1369 structured data sources in one call, decomposing questions into facets and routing to parallel tools. It distinguishes itself from open-web search and sibling tools like ask_pipeworx, making the purpose unmistakable.

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

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

The description explicitly states when to use this tool (broad/multi-part questions over structured data) and when not to (single lookup: use ask_pipeworx; breaking/current news: prefer ask_pipeworx). It also notes the account requirement and directs unsigned-in users to ask_pipeworx, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral context by specifying that the tool returns top-N relevant tools with full input schemas and curated examples, ready to call directly. This goes beyond the annotations by detailing the return format.

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 purpose but contains a lengthy list of domains. While this list is informative, it could be slightly more concise. However, every sentence serves a purpose, and the structure is logical.

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

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

Given the tool's simplicity (single required parameter, no output schema), the description fully explains its function, expected input, return value (top-N tools with schemas), and usage context. It is complete for an agent to understand when and how 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 baseline 3. The description adds value by providing example queries ('look up FDA drug approvals', 'analyze housing market trends') and explaining that aliases are accepted. This helps the agent understand the query parameter's usage beyond the schema's definition.

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

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

The description clearly states the tool's purpose: finding tools by describing the data or task. It provides a comprehensive list of domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes from siblings by advising to 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description gives explicit usage scenarios ('Use when you need to browse, search, look up, or discover what tools exist for') and recommends calling this tool first. It lacks explicit when-not-to-use instructions but implies it's for discovery rather than direct data retrieval.

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, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral details: cross-source fan-out (SEC EDGAR, XBRL, USPTO, news, GLEIF), specific return fields, and the patent API sunset with soft-fail. No contradiction with annotations.

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

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

The description is front-loaded with purpose and examples, then systematically details the return data. While it is somewhat lengthy, every part adds value—except maybe the example list could be trimmed. Structure is logical and scannable for an AI agent.

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 explaining return values. It covers: CIK, company name, recent filings (with URIs), fundamentals, patents (with sunset caveat), news, and LEI. It could be more precise on format (e.g., fundamentals are sorted), but overall adequate for the 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 coverage is 100%, but the description adds meaning beyond the schema: for 'type', it notes only 'company' is supported and hints at future expansion; for 'value', it reiterates ticker/CIK format and explicitly warns against names, recommending resolve_entity. This adds clear guidance.

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

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

The description explicitly states the tool creates a 'full cross-source profile of a US public company in ONE parallel call' and provides concrete examples (e.g., 'tell me about X'). It distinguishes from siblings by urging precedence over chaining individual lookups and referencing resolve_entity for names.

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

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

The description includes clear directives: 'ALWAYS PREFER over chaining...when the user asks for a holistic view' and explicitly states that names are not supported, advising to use resolve_entity first. It also mentions soft-fail behavior for patents, providing complete usage context.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, so the agent knows the tool deletes data and can be retried safely. The description adds context about clearing 'sensitive data', which provides behavioral nuance. No contradiction with annotations.

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

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

The description is extremely concise: two sentences, each with distinct value. The first sentence states action and resource; the second provides usage guidance. No superfluous 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?

For a simple tool with one parameter and full annotation/schema coverage, the description is complete. It covers purpose, usage context, pairing, and the safety aspect of clearing sensitive data. No missing information.

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 parameter 'key' is described as 'Memory key to delete' in the schema. The description only mentions 'by key' (redundant) and provides no additional semantic detail beyond what the schema already offers. Baseline 3 is appropriate.

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

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

The description clearly states the tool deletes a memory by key ('Delete a previously stored memory by key'). It also distinguishes from siblings by naming 'remember' and 'recall' as paired tools, which differentiates it in the list of 30+ 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 description provides specific contexts for use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also mentions pairing with 'remember' and 'recall', which implicitly guides when not to use it. However, it does not explicitly state when not to use it or list alternatives beyond the pair.

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

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

The description explains the internal behavior: fetching the page, extracting title/description/key links, and emitting standard llms.txt markdown. This complements the annotations (readOnlyHint, idempotentHint, etc.) by detailing the steps involved. No contradictions with annotations; the description adds valuable context about the process and output.

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 succinct: three sentences covering purpose, process, and output, followed by a bullet list of use cases. It is front-loaded with the most critical information and contains no redundant or unnecessary details.

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

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

For a simple tool, the description covers key aspects: what it does, how it works (fetching and extraction), and the output format (standard llms.txt). It could mention error handling (e.g., unreachable URLs) or prerequisites, but these are minor omissions. Given no output schema, the description adequately explains the return value.

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

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

The input schema already describes both parameters (url, max_links) with clear descriptions and default/limits. The description does not add additional meaning or constraints beyond the schema. Therefore, it meets the baseline for high schema coverage.

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

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

The description clearly states the tool's function: generating an llms.txt file for a given URL. It specifies the output format (standard llms.txt markdown) and lists concrete use cases (client indexing, personal projects, competitor auditing). This effectively distinguishes it from siblings like 'ai_visibility_check' or 'scan_competitor_ai_presence', which serve different purposes.

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

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

The description provides explicit use cases, such as 'getting a client's site indexed by AI' or 'auditing a competitor'. This gives clear context on when to use the tool. However, it does not mention when not to use it or suggest alternative tools, though no direct alternatives exist among siblings.

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

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

Annotations already indicate read-only and non-destructive. Description adds that it returns specific fields and mentions optional include_inactive, adding value without contradiction.

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

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

Two sentences, front-loaded with purpose, no wasted words.

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

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

No output schema but description lists return fields. One optional parameter well-covered. Sibling tools provide context. Complete for a simple list 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 coverage is 100%, so baseline is 3. The description does not add parameter details beyond the schema; it only implicitly references include_inactive.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the return fields. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Provides clear guidance to use before adding more subscriptions or to find an id to cancel. No explicit when-not, but context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: the need for a CMS license token for licensed content and a disclaimer that code inclusion is billing guidance, not guaranteed coverage. This enhances transparency beyond annotations.

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

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

The description is two sentences: one for purpose and one for important caveats. No redundant words or irrelevant details. Highly 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?

With an output schema present, the description need not detail return values. It covers the main purpose, licensing, and a coverage disclaimer. However, the version parameter is undocumented in both schema and description, which is a minor gap.

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

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

Schema description coverage is 75% (three of four parameters described). The description reiterates the license token requirement but adds no new parameter semantics beyond the schema. Baseline 3 is appropriate as schema does most of the work.

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

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

The description clearly states it retrieves a single Medicare article with codes and contractor records. The verb 'Retrieve' and specific resource 'one CMS Medicare Coverage Article with its CPT/HCPCS codes' are precise, and the tool is well-distinguished from siblings like medicare_lcd_detail or medicare_coverage_states.

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

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

The description implies the tool is for retrieving a specific article with codes but does not explicitly state when to use it over alternatives like medicare_lcd_search or medicare_ncd_detail. The licensing note hints at prerequisites but lacks when-not-to-use 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 indicate readOnly, openWorld, idempotent, and non-destructive behavior, which cover safety and side effects. The description adds the context that it returns 'state identifiers for local coverage,' which is useful but not essential beyond annotations.

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

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

The description is a single sentence with no wasted words. It conveys the exact purpose and usage context efficiently.

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

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

The description is complete for a simple tool with no inputs and an output schema. It clearly states what the tool returns and its purpose, which is sufficient for an agent to understand its role among many Medicare sibling tools.

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

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

The tool has no parameters, and schema coverage is 100%. The description adds meaning by specifying that the output consists of state identifiers for local coverage, which compensates for the lack of parameters.

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

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

The description clearly states the verb 'list' and the resource 'CMS Coverage API state identifiers' with the specific purpose 'used to scope local Medicare coverage searches.' This distinguishes it from sibling tools like medicare_lcd_search or medicare_nca_search, which require state identifiers but do not list them.

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

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

The description implies that this tool should be used to obtain state identifiers before performing local coverage searches with other Medicare tools. However, it does not explicitly state when to use it versus alternatives or provide exclusion criteria, leaving usage somewhat implicit.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that timeline entries are about policy publication history and the token requirement for LCD. This adds value beyond annotations but does not disclose other traits like error handling or rate limits.

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 concise sentences, each earning its place: first states the core purpose, second adds critical constraints and clarification. No fluff or redundancy.

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

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

Given the complexity (4 params, conditional token requirement) and presence of an output schema, the description covers the essential aspects: what the tool retrieves, the token condition, and the meaning of timeline entries. A minor gap is the lack of explanation for the 'version' parameter, but overall it is sufficient.

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 low (25%): only _licenseToken has a description. The description compensates by explaining that LCD requires the token and implies document_type values (NCD, NCA, CAL, LCD). However, it does not clarify the meaning of the 'version' parameter or provide additional context for document_id.

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

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

The description clearly states the verb 'retrieve' and the specific resource 'official CMS version or revision history for an NCD, NCA, CAL, or LCD'. It distinguishes from sibling tools like medicare_ncd_detail which retrieve single document details, not revision history.

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

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

Explicitly notes that LCD revision history requires a CMS license token and clarifies that timeline entries describe policy publication history, not claims adjudication. This provides clear context on when to use and what the tool does not do, though it does not explicitly contrast with alternatives.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by specifying the exclusion of Medicare Advantage and clarifying the metric set. No contradictions with annotations.

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

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

The description is a single, well-structured sentence that conveys all essential information without extra words. Every phrase earns its place.

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

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

Given the existence of an output schema and annotations, the description is largely sufficient. It lacks detail on the exact meaning of each metric, but the output schema likely covers that. The description is complete enough for the 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 coverage is 0%, so the description must compensate. It implies hcpcs_code is required and the tool covers annual data, but does not explain from_year and to_year semantics beyond the example. The example provides some clarity, but explicit parameter descriptions are missing.

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 specifies the tool shows annual national Medicare FFS DME supplier, beneficiary, claim, service, and average-payment metrics for one HCPCS code. It explicitly distinguishes from total market demand or company revenue, and the purpose is clear and distinct from sibling 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 description mentions what the tool excludes (Medicare Advantage) and what it is not (total market demand or company revenue), but does not provide explicit guidance on when to use this tool versus its many Medicare-themed siblings. Usage context is implied but not directly compared.

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

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

Annotations already indicate read-only, idempotent, and open-world behavior. The description adds that the sample is 'bounded API-order' and includes an 'authoritative matching-row count', providing useful behavioral context beyond the annotations. No contradictions.

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

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

Two sentences with essential information placed upfront. No unnecessary words or redundancy. The description is efficient and easy to parse.

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

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

The description covers the core functionality, constraints, and what the tool is not. Given the output schema exists (though not shown), the description need not detail return format. For a read-only sample tool, it is largely complete, though parameter details could be enriched.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions hcpcs_code, year, and state, but omits limit and offset. The term 'bounded' implies pagination, but no explicit parameter guidance is given. This is insufficient for a tool with 5 parameters.

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

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

The description clearly states the tool returns a bounded sample of DME supplier rows for an exact HCPCS code and year, optionally filtered by state, with an authoritative row count. It explicitly distinguishes itself from similar tools by stating it is not a supplier ranking or total market size.

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

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

The description explains what the tool does and what it does not do (not a ranking or total market size), which helps differentiate it from siblings. However, it does not explicitly state when to use this tool over alternatives or provide conditions for use, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that counts are program participation, not utilization or revenue, which is useful context. However, it does not disclose other behavioral traits such as data update frequency or any limitations.

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

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

The description is two sentences with no wasted words. It front-loads the core function and immediately adds a clarifying caveat.

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

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

Given the simple parameter set, presence of output schema, and annotations, the description adequately covers the main purpose, geographic scope, and data semantics. Missing details like default year behavior are minor.

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

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

Schema description coverage is only 33% (state described). The description mentions 'nationally or for one state' to clarify the state parameter, but does not explain the from_year and to_year parameters (e.g., valid ranges, default behavior, required formats).

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

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

The description clearly states it shows annual Medicare enrollment data broken down by plan types (Medicare Advantage, Original Medicare, Part D PDP, etc.) nationally or for one state. It distinguishes from utilization or revenue tools, which is a key differentiator among sibling 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 description implies usage for enrollment counts by noting it is not utilization or revenue, but does not explicitly guide the agent on when to choose this tool over alternatives like medicare_hcpcs_utilization_trend or medicare_hospital_service_trend.

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

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

Annotations already mark the tool as read-only and safe. The description adds valuable behavioral context by warning that 'State beneficiary counts across places of service must not be summed as unique people,' preventing misuse. This goes beyond standard annotation 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?

The description is two sentences, front-loaded with the primary function, and includes a critical behavioral note. No unnecessary words; every sentence earns its place.

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

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

Given the presence of an output schema and clear annotations, the description covers the core purpose and a key nuance. However, it lacks mention of typical use cases or output structure expectations, leaving some gaps for a tool in a complex domain.

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 33% (document only the limit parameter). The description does not compensate: it mentions 'one HCPCS code and program year' but omits details on the limit parameter or year format, leaving significant gaps in parameter understanding.

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

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

The description clearly states the tool compares state-level Medicare metrics for one HCPCS code and program year, using specific resource types (provider, beneficiary, service, average-payment). However, it does not differentiate from sibling tools like medicare_hcpcs_utilization_trend or medicare_coverage_states, which limits clarity for selection.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not specify prerequisites or exclude any scenarios, leaving the agent without context for appropriate invocation.

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

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

The description goes beyond the annotations (which indicate read-only, open-world, idempotent, non-destructive) by clarifying that data is fee-for-service aggregates with suppression and methodology limits, and that it does not measure total US use, coverage, demand, or revenue. No contradiction with annotations.

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

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

Two sentences, no wasted words. The first sentence states the core purpose, the second adds critical limitations. It is front-loaded and every sentence earns its place.

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

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

Given the presence of an output schema and comprehensive annotations, the description adequately covers data limitations and scope. It could mention that the tool returns metrics for the requested code, but the output schema presumably handles that. Minor improvement would be to note that at least one year must be present (since from_year and to_year are optional).

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 0% schema description coverage, the description must compensate. It adds minimal parameter meaning: implies hcpcs_code identifies a single code, and mentions 'annual' suggesting from_year/to_year define a range. But it does not specify defaults, valid ranges, or formatting requirements for the parameters.

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

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

The description uses a specific verb ('Show') and identifies the resource ('annual Medicare Physician & Other Practitioners national utilization and payment metrics') and scope ('for one HCPCS code'). It clearly distinguishes from sibling tools that cover geography, coverage, or multiple codes.

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 does not provide any guidance on when to use this tool versus alternative tools. No explicit context for when to choose it over siblings like medicare_hcpcs_geography or compare_entities.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by clarifying that trends are limited to fee-for-service and exclude Medicare Advantage, which provides important behavioral context beyond annotations.

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

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

The description is two sentences: the first clearly states the function, the second adds important exclusions. It is concise, front-loaded, and contains no unnecessary words.

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

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

Given the tool has an output schema and annotations, the description covers the main purpose and constraints. However, the lack of parameter descriptions (due to 0% schema coverage) leaves gaps for an agent, making it only minimally 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 0%, so the description must compensate. It mentions 'one inpatient MS-DRG or outpatient APC' relating to service_type and code, and implies a date range via annual trends, but does not explicitly describe the 'code', 'from_year', or 'to_year' parameters or their formats.

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

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

The description clearly specifies the tool shows annual national Medicare fee-for-service utilization and average-payment trends for one inpatient MS-DRG or outpatient APC. It differentiates from sibling tools like medicare_dme_service_trend by focusing on specific service types.

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 states trends exclude Medicare Advantage and do not measure total market demand, revenue, or profitability. This provides context for when not to use the tool, but does not explicitly name alternative tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: the result is a 'bounded sample' (not full dataset), includes 'authoritative matching-row count', and warns that 'Average payments are not hospital revenue or margin.' This goes beyond annotations.

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

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

The description consists of two concise sentences. The first sentence clearly defines the tool's function with no wasted words. The second sentence provides a critical caveat. Every sentence earns its place.

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

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

Given the existence of an output schema, the description adequately covers the input and behavior. It explains the type of data (hospital-level, fee-for-service), the key filters, and the nature of the output (bounded sample with row count). It could mention data availability limitations (e.g., years) but is largely 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 0%, so the description must compensate. It mentions 'exact MS-DRG and year, optionally filtered by state', which covers drg_code, year, and state. However, limit and offset are only implied by 'bounded sample' and the example in the schema. The description adds meaningful context (exact match, optional filters, bounded sample) but could more explicitly describe all five parameters.

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

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

The description clearly states the verb 'return', the resource 'hospital-level Medicare fee-for-service inpatient rows', and the constraints ('exact MS-DRG and year', 'bounded sample', 'optionally filtered by state', 'authoritative matching-row count'). This is highly specific and distinguishes it from sibling tools like medicare_hospital_service_trend or medicare_outpatient_apc_market, even without explicit contrasts.

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

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

The description provides clear contextual guidance: use this tool for exact MS-DRG and year, optionally by state, and notes it returns a bounded sample. It does not include explicit when-not-to-use or alternative tool names, but the context is sufficiently clear for an agent to determine applicability.

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

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

The description adds behavioral context beyond annotations by disclosing the license token requirement and its rationale. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness, and the description aligns with these while adding specific constraints.

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

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

The description is two sentences with no extraneous information. The first sentence states the purpose, and the second provides essential context about the license token. Every word is substantive.

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

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

Given the output schema exists, the description adequately covers purpose, key parameter, and a critical licensing restriction. It is missing explicit mention of the optional version parameter and error handling, but the overall completeness is high for a retrieval 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 only 33% schema description coverage, the description adds meaning by explaining the _licenseToken purpose and validity duration, and clarifying that the tool retrieves by document_id and version. However, it does not detail the optional version parameter's behavior or constraints.

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

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

The description clearly states the tool retrieves one Medicare LCD by document ID and version, using specific verbs and resources. It distinguishes from sibling tools like medicare_lcd_search, which searches for multiple LCDs.

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

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

The description explains when the tool is used (to retrieve a specific LCD) and provides crucial guidance on the required _licenseToken, including why it's needed (licensed AMA/ADA/AHA material) and how to obtain it. However, it doesn't explicitly contrast with alternative tools for when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds that LCDs are 'current final' and jurisdiction-specific, which is useful context but does not reveal additional behavioral traits beyond what annotations imply.

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. The purpose is front-loaded. Every word adds value.

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

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

With annotations fully covering safety and output schema present, the description is sufficient. It explains the key state-restriction feature. However, it could briefly mention that results are limited and sorted, but not required.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The tool description does not add extra meaning or syntax beyond the schema's attribute descriptions.

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

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

The description clearly states the verb 'Search' and the resource 'current final Medicare Local Coverage Determinations (LCDs)'. It adds context that they are contractor- and jurisdiction-specific, which helps distinguish from other Medicare tools like medicare_lcd_detail or medicare_ncd_search.

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

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

The description implies usage for searching LCDs, optionally by state, but does not explicitly guide when to choose this tool over siblings like medicare_ncd_search or when not to use it. No exclusions or alternatives are mentioned.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, so safety profile is clear. The description adds valuable interpretation that differences are 'policy signals, not proof of unequal beneficiary access or payment,' providing behavioral context beyond annotations.

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

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

The description is two sentences, the first immediately stating the purpose, and the second adding important nuance. No wasted words, fully front-loaded.

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

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

Given the tool's purpose and the existence of an output schema, the description is sufficiently complete. It explains the core behavior (comparing matches across states) and interprets the results. Minor gap: does not describe the output structure, but the output schema likely covers that.

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

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

Schema description coverage is only 25% (only limit_per_state has a description). The description does not explicitly explain the 'query', 'states', or 'status' parameters. It hints at 'states' by mentioning '1-15 states', but fails to add meaning for required or optional parameters beyond what the schema provides.

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

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

The description clearly states the verb 'compare', the resource 'final LCD search matches', and the scope across 1-15 states and Medicare Administrative Contractors. This effectively distinguishes it from sibling tools like medicare_lcd_detail or medicare_lcd_search.

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

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

The description implies use for variation analysis across states, but it does not explicitly state when to use versus alternatives or provide exclusion criteria. The context is clear, but lacks explicit guidance on when not to use.

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, etc. The description adds value by listing specific included fields (request, issue, benefit category, dates, decision memo, public-comment status), providing behavioral context beyond annotations.

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

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

Single sentence, front-loaded with the action, no wasted words. Efficient and clear.

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

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

With only one parameter, an output schema (implied), and annotations covering idempotency and read-only nature, the description is complete for a retrieval tool. Lists key data components.

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

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

Schema coverage is 100% with a description for document_id. The description repeats 'document ID' but adds no additional meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'Retrieve one CMS National Coverage Analysis by document ID', specifying a verb and resource, and distinguishes from siblings like medicare_nca_search and medicare_ncd_detail.

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 when you have a document ID, but does not explicitly state when to use this tool versus alternatives or exclude cases. No guidance on prerequisites or 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 cover safety (readOnly, idempotent, not destructive). Description adds that an open analysis is a policy process, not a coverage decision, which is useful context. However, it does not disclose other behaviors like rate limits or auth requirements.

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 purpose, second sentence adds important clarification. No unnecessary words.

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

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

Output schema exists, so return values are not needed. Description covers what is searched and the nuance about open vs completed. For a search tool with optional parameters, it is fairly complete, though could mention pagination or result format.

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 67% (query and status described). Description adds 'open and completed' which relates to status, but does not elaborate on limit or provide full enumeration. Adds some value but does not significantly exceed schema.

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

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

Description clearly states it searches National Coverage Analyses (NCAs) and Coverage Analyses for Labs (CALs), including open and completed CMS evidence reviews. The verb 'search' and specific resources are provided, and it distinguishes from sibling tools like medicare_ncd_search.

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

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

Implies usage for searching NCAs and CALs, but lacks explicit when-to-use or when-not-to-use guidance. No mention of alternatives or specific contexts beyond the task description.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and open-world. The description adds value by specifying exactly what data is returned (covered indications, limitations, effective dates, benefit category, revision text), providing behavioral context beyond the annotations. It is consistent with annotations and does not contradict 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 a single, concise sentence that front-loads the action and resource, then lists the return content. Every word adds value; there is no redundancy or fluff. It is well-structured for quick reading.

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

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

Given the tool's simplicity (2 parameters, one required), the annotations, the presence of an output schema, and the description's clear enumeration of returned fields, the description provides complete context. An agent can understand the tool's purpose, inputs, and outputs without additional information.

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

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

The input schema covers 100% of parameters (document_id and version) with descriptions. The description restates that retrieval is by document ID and optional version, but adds no new information beyond what the schema already provides. Per guidelines, when schema coverage is high, a score 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 clearly states the verb 'Retrieve' and the specific resource 'Medicare National Coverage Determination'. It specifies the retrieval by document ID and optional version, and lists the included content areas. This clearly distinguishes it from sibling tools like medicare_ncd_search (which searches) and medicare_lcd_detail (which retrieves a different type of determination).

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 that the tool is used after obtaining a document ID from medicare_ncd_search, and mentions optional versioning. However, it does not explicitly state when to use this tool versus alternatives (e.g., for LCD determinations, use medicare_lcd_detail), nor does it provide any when-not-to-use guidance. Given the many sibling tools, more explicit usage context would be helpful.

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

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

Annotations already indicate read-only and idempotent behavior. Description adds useful context: the search covers current NCDs and clarifies that results are not guarantees or medical advice, which is beyond annotations.

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

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

Two concise sentences with no wasted words. The key action and resource are front-loaded, and the limitation is stated efficiently.

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

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

With an output schema present, return values need not be explained. However, the description lacks context about when this tool is preferable over other Medicare search tools, leaving the agent without full decision support.

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%, but the description adds practical search tips (e.g., use spelled-out terms like 'positron tomography' not 'PET'), improving usability beyond schema definitions.

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

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

The description clearly states the tool searches Medicare NCDs by title, benefit category, or NCD number. Its purpose is specific and actionable, but it does not differentiate from sibling tools like medicare_lcd_search or medicare_nca_search.

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

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

No guidance on when to use this tool versus alternatives. Given many sibling Medicare search/detail tools, explicit comparison or conditions would help, but are absent.

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

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

The description adds behavioral context beyond annotations: 'bounded sample' indicates a limit on results, 'authoritative matching-row count' implies a count is returned, and the clarification that APC payments are aggregates not revenue/margin. Annotations already declare readOnlyHint=true, destructiveHint=false, and the description aligns without 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?

The description is two sentences with no redundancy. The first sentence delivers the core purpose, and the second adds essential context. Every word adds value; the structure is front-loaded and 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?

The description covers the overall purpose and key filters but lacks details on parameter usage (e.g., default values, ranges, offset behavior) despite having an output schema. It is sufficient for tool selection but not for full invocation understanding. Given the complexity and available annotations, it is moderately 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?

With 0% schema description coverage, the description must compensate. It explains 'apc_code' and 'year' (exact), 'state' (optional filter), and 'limit' indirectly via 'bounded sample', but does not describe 'offset' or provide detailed parameter formats. The example in the schema helps, but the description alone lacks full parameter semantics.

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

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

The description uses a specific verb ('Return'), a precise resource ('bounded sample of hospital-level Medicare fee-for-service outpatient rows'), and explicit filters ('exact APC and year', 'optionally filtered by state'). It also adds a clarifying sentence distinguishing APC payments from revenue/margin, helping differentiate from sibling tools like medicare_inpatient_drg_market.

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

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

The description implies usage for outpatient APC data queries but does not provide explicit guidance on when to use this tool over alternatives (e.g., medicare_hospital_service_trend). No exclusions or when-not conditions are stated, only implicit context based on the tool's focus.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds critical context about what the gross spending numbers do NOT represent (manufacturer revenue, net price, profit, etc.), which is valuable beyond structured metadata.

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

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

Two sentences with no redundancy. First sentence front-loads the core function and outputs; second sentence provides an essential clarification. Every word serves a purpose.

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

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

With an output schema present, the description sufficiently covers the query scope (time range, metrics). Minor omission on pagination behavior, but not critical given the schema and annotations.

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

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

Schema coverage is low (33%) but the description adds meaning for the 'drug' parameter (brand or generic name). 'limit' is already described in schema. 'offset' receives no additional explanation, so overall partial compensation.

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

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

The description uses a specific verb 'Search' and resource 'CMS Medicare Part D spending', and clearly lists the returned fields (spending, claims, beneficiaries, dosage units, unit-cost trends) and time range (2020–2024). It distinguishes from sibling tools like medicare_part_d_generic_competition by focusing on spending and claims.

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

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

The description implies usage for Part D spending queries but lacks explicit guidance on when to use this tool over alternatives. The clarification 'Gross Part D spending is not manufacturer revenue...' provides some boundary but does not replace explicit usage context.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds value by clarifying that manufacturer count is a CMS aggregate (not a list of companies) and specifying the 2020-2024 time range, going beyond what annotations provide.

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

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

The description is two sentences: first sentence states purpose, second provides a crucial caveat about manufacturer count. Every word earns its place; no redundancy.

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

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

Given the tool has an output schema (so return values need not be explained), the description covers purpose, key parameter, data source, time range, and a critical caveat. This is complete for a profiling tool with good annotations.

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

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

Schema coverage is 50%; the 'limit' parameter is documented, but 'generic_name' lacks description. The description compensates by stating the tool uses an 'exact generic name' and focuses on brand rows, adding meaning beyond the schema.

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

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

The description clearly states the tool profiles brand rows sharing an exact generic name, with manufacturer count and spending/use trends. It uses specific verbs and resources, distinguishing it from sibling tools like medicare_part_d_drug_spending.

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

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

The description implies usage for analyzing generic competition but does not explicitly state when to prefer this tool over alternatives such as medicare_part_d_drug_spending or medicare_part_d_prescriber_exposure. It provides context but lacks exclusion 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful behavioral context: 'bounded sample', 'authoritative matching-row count', and the negative note about suppressed/non-Part-D activity. No contradictions.

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

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

Two sentences with essential information front-loaded. Every word adds value. No redundant or vague phrasing.

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 5 parameters, 0% schema coverage, and an output schema, the description provides most key context: constraints on brand_name, year, state, limit, and count. However, offset is missing, and the description could be more precise about the relationship between limit and count.

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

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

Schema coverage is 0%, so description must explain all 5 parameters. It covers brand_name, year, state, and limit (implicitly via 'bounded sample'), but offset is not mentioned. The description omits syntax or format details, leaving ambiguity for offset and precise meaning of 'bounded'.

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?

Clearly states the tool returns a bounded sample of Medicare Part D prescriber-by-drug rows for an exact brand name in one year, with optional state filtering and an authoritative count. This specific verb-resource combination distinguishes it from siblings like medicare_part_d_drug_spending.

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

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

Explicitly states what the tool is not ('not a prescriber ranking') and notes excluded activity (suppressed/non-Part-D). However, it does not name specific sibling alternatives for when to use a different tool.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe, read-only operation. The description adds value beyond annotations by noting the 'bounded API-order sample' nature and clarifying that 'Payments are not provider revenue or margin,' which is critical for correct interpretation of the data. No contradictions.

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

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

Two sentences with no waste. The first sentence states the primary purpose and scope. The second is a critical disclaimer. Content is front-loaded and 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?

Given the tool has 5 parameters and an output schema, the description covers purpose, sample behavior, count, and a key payment caveat. It does not explain pagination (limit/offset) or output structure, but an output schema exists. For a simple list tool with robust annotations, this is adequately 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 0%, so the description must compensate. It mentions service_type, year, and state indirectly, but does not describe limit or offset (bounded sample implied). The description adds only partial parameter meaning; parameters like limit and offset are not explained. The example in schema helps, but the description alone is insufficient for an agent to understand all parameters.

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

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

The description clearly states it returns a bounded sample of Medicare post-acute provider rows for home health, hospice, or skilled nursing by year and optional state, with an authoritative count. It also clarifies that payments are not revenue/margin. This verb-resource combination is specific and distinguishes it from sibling tools like medicare_post_acute_trend (trend data) and other market 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 description implies usage context (getting provider rows for specific service types, year, state) but does not explicitly state when to use this tool vs alternatives, nor does it provide exclusions. Sibling tool names like medicare_post_acute_trend suggest aggregate trend data, but no explicit guidance is 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 indicate safe read operations. The description adds valuable behavioral context: program definitions differ by service and figures are not provider revenue. This goes beyond annotations and sets proper expectations.

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 that are front-loaded with the core purpose, followed by a necessary caveat. No fluff or redundancy.

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

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

The description provides the core purpose and a caveat, but it omits mention of the year range parameters (from_year, to_year) available in the schema. With an output schema present, this is acceptable but not 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 0% as the description does not explain the parameters. While the schema is simple with enums and optional year fields, the description fails to clarify the meaning of from_year and to_year. The implied annual nature is not enough.

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

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

The description clearly states the tool shows annual national Medicare fee-for-service data for specific post-acute services (home health, hospice, skilled nursing) and lists the metrics. It distinguishes from sibling tools by specifying the service type and context.

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 does not provide explicit guidance on when to use this tool versus alternatives like medicare_hospital_service_trend. It lacks any 'when to use' or 'when not to use' advice, which is needed given many similar Medicare trend tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds a key behavioral trait: CMS does not validate product-to-code associations, requiring independent verification. This goes beyond the annotations and is valuable for safe usage.

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: first defines core functionality concisely, second adds an important caveat. No fluff, front-loaded, every word 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?

The description explains the core operation but omits usage context and detailed parameter semantics. With 5 parameters and an output schema, more context would help an agent invoke it correctly, especially given the many sibling tools.

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

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

With only 20% schema coverage (only 'query' has a description), the description compensates by clarifying that 'query' is a product/topic and 'hcpcs_codes' are caller-supplied. It also hints at time range via 'annual utilization'. However, it does not explain 'policy_limit' or provide details on parameter formats.

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

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

The description clearly states that the tool combines national coverage policy matches with Medicare fee-for-service utilization for a given product/topic and HCPCS codes. This distinguishes it from sibling tools like medicare_ncd_search (coverage only) or medicare_hcpcs_utilization_trend (utilization only).

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 on when to use this tool over alternatives. The description does not specify prerequisites, exclusions, or compare with sibling tools. An agent would lack context to choose this over other Medicare tools.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds that the tool excludes suppressed/non-FFS activity and that it provides a bounded sample rather than a full ranking. This provides useful behavioral context without contradicting the annotations.

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

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

The description consists of two well-structured sentences. The first sentence conveys the core purpose and key details, and the second adds clarifying exclusions. There is no unnecessary 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?

The description is fairly complete given the presence of an output schema and clear annotations. It explains the sample nature, exclusion criteria, and key filters. However, it does not mention the year or offset parameters, though the output schema likely covers return format.

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 description adds meaning to parameters by explaining that the tool returns data for one HCPCS code, optionally filtered by state, and that it provides a match count. However, with only 20% schema description coverage, the description does not fully compensate for the lack of details on parameters like year and offset.

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

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

The description explicitly states the tool returns a bounded sample of provider-level Medicare FFS rows for a single HCPCS code, with optional state filtering and an authoritative match count. This specifies a clear verb, resource, and scope, and it distinguishes itself from siblings by stating it is not a provider ranking and excludes suppressed/non-FFS activity.

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 context through phrases like 'bounded sample' and 'not a provider ranking,' but it does not explicitly state when to use this tool versus specific sibling alternatives. There are no explicit when-to-use or when-not-to-use guidelines beyond one brief exclusion.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. Description adds context about document types included (NCDs, NCAs, etc.) and that documents are 'published or updated', which aligns with behavioral expectations.

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

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

Single sentence, front-loaded with key intent, no redundant information. Every word 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?

Output schema exists (not shown but stated), so return values are covered. Description lists document types and scope (national Medicare documents). Could mention ordering or pagination but is adequate for a simple list tool with clear annotations.

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

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

Schema coverage is 67% (2 of 3 parameters described). Description does not add any parameter-specific meaning beyond the schema; it does not mention the 'days', 'limit', or 'document_type' parameters. It does not compensate for the missing description of the 'limit' parameter.

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

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

Description clearly states it returns 'recently published or updated national Medicare coverage documents from CMS' and lists specific document types like NCDs, NCAs, CALs, etc. This distinguishes it from sibling tools that focus on individual document types or search.

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

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

Description implies use for recent changes across multiple document types but does not explicitly contrast with sibling tools like medicare_ncd_search or medicare_lcd_search. No guidance on when not to use this tool.

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

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

The description complements annotations by disclosing behavioral traits: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. It also explains how feedback is processed (team reads digests daily, signal affects roadmap). No contradiction with annotations (readOnlyHint=false, etc.).

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds essential information: purpose, usage scenarios, formatting advice, and constraints. No redundant or off-topic content.

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

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

Given the tool's simplicity (3 parameters, 2 required, no output schema), the description covers all necessary context: purpose, when to use, how to format input, behavioral constraints (rate limit, free), and expected outcome (digest to team). No gaps remain.

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. The description adds value by clarifying the `type` enum (e.g., 'bug = something broke or returned wrong data') and advising on `message` content (be specific, 1-2 sentences, 2000 chars). This enhances understanding beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs (tell, broken, missing) and identifies the resource (Pipeworx team/feedback). The description distinguishes from sibling tools by specifying its unique role as a feedback mechanism, while siblings are for queries, research, or visibility checks.

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

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

The description provides explicit guidelines on when to use the tool: for bugs (wrong/stale data), feature requests (tool wish existed), data gaps, or praise. It also specifies what not to do ('don't paste the end-user's prompt') and describes the feedback format. It mentions rate limits (5 per identifier per day) and that it's free, offering clear context for usage.

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. Description adds caching latency (5min-1h) and source derivation (CF analytics-engine, no PII), which provides useful behavioral context beyond annotations.

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

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

The description is a single, well-organized paragraph. It front-loads the primary function, then provides bullet-like use cases. Every sentence adds value with no redundancy.

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

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

For a read-only trending tool with one optional parameter, the description fully covers purpose, return content (top tools, packs, volume), source, caching, and privacy. No output schema is needed as return format is clearly described.

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 single parameter 'window' has 100% schema coverage with descriptive enum values. The description adds functional meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', aiding correct selection.

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

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

The description uses specific verbs ('Returns') and clearly states the resources (top tools, top packs, total call volume) and time window options. It distinguishes itself from siblings like discover_tools and entity_profile by focusing on aggregate trending data.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tools, checking alignment). Implicitly excludes individual lookups handled by siblings. Also mentions caching behavior, aiding appropriate usage.

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

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

The description adds extensive behavioral context beyond annotations: it details monotonicity checks, partition sums, semantic similarity filter, partition placeholder filter, and fill check against order book depth. Annotations already declare readOnlyHint and idempotentHint, and the description aligns with them, adding actionable constraints like 'do not trade it' when realizable edge ≤ 0.

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 detailed and well-structured with paragraphs for each mode, but it is somewhat lengthy. However, every sentence adds value given the tool's complexity, so only minor redundancy detracts from conciseness.

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?

Despite lacking an output schema, the description explains the response structure (opportunities[] with fields, partition_check object) and mentions fill check. All parameters are covered, and references to sibling tools (polymarket_fill_risk) for advanced use complete the context.

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

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

Schema coverage is 100% with brief descriptions, but the tool description enriches each parameter significantly: it provides examples of event slugs (e.g., 'fed-decision-may-2026'), explains that full URLs are accepted, describes topic as a seed question, and clarifies the behavior of each mode. This exceeds the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between three invocation modes (no args, event, topic) and explains what each does, making it distinct from sibling tools like polymarket_edges.

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?

Explicit guidance is provided: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market)', 'topic for a themed cross-event scan'. The description explains when to use each mode and what they achieve, including cross-event catching patterns single-event misses.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description goes beyond by explaining the three model families, caching behavior (1h KV level), response structure (by_segment, fed_candidates, _diagnostics), and the move warning. This adds significant behavioral 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?

The description is long but well-structured with front-loaded purpose and logical grouping. Some details (e.g., specific alpha values for sports) could be condensed, but overall it is appropriately sized for the tool's complexity.

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 100% parameter coverage and no output schema, the description explains the response structure (by_segment, fed_candidates, _diagnostics) and each opportunity's fields (edge_pp_net, kelly_fraction, etc.). It covers knobs' effects and caching, providing complete context.

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 description adds extra context beyond the schema for parameters like slippage_pp (Polymarket fee structure) and min_partition_leg_kelly (why min_kelly doesn't filter partitions). This provides meaningful guidance for parameter usage.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes from siblings like polymarket_arbitrage by focusing on discovery without paging hundreds of markets.

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

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

The description provides explicit context on when to use the tool (opportunity discovery) and includes detailed guidance on tradeable-edge knobs (min_liquidity, max_spread_pp) and how to interpret empty segments via _diagnostics. However, it does not explicitly state when not to use it or contrast with alternatives.

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, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: it uses daily snapshots, has a 60-day TTL, returns time-series, and notes that decay is from daily closes not intraday, fully disclosing behavior beyond annotations.

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

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

The description is lengthy but every sentence adds value, including the response structure and limitations. It is front-loaded with purpose and efficiently provides necessary details without redundancy.

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

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

Given the lack of an output schema, the description thoroughly covers the response structure (tracked, expired, snapshot_dates) and key details like trend interpretation and limits. It is nearly complete, though it could elaborate more on how to act on the decay metrics.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by clarifying the 'window' parameter as a snapshot family (e.g., 1wk) and explaining 'days' as a lookback with defaults and clamps, providing value beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry. It distinguishes from sibling tools like polymarket_edges by focusing on historical time-series trends, answering 'how long has this edge existed and is it shrinking?'.

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

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

The description explains the tool's application (comparing a fresh wide edge to an old wide edge) and provides context on when to use it. However, it does not explicitly list alternatives or exclusions, though it is clear from sibling tools that this is for historical analysis.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description does not contradict them. The description adds valuable behavioral context such as walking the order book ladder, returning verdicts, and explaining risks like thin books and forced directional risk, which goes beyond annotations.

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

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

The description is lengthy but each part earns its place. It is front-loaded with the core purpose and then details modes and usage. Could be slightly more concise, but the structure is logical and comprehensive.

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?

Despite no output schema, the description lists all expected return fields for both modes, including metrics like slippage, capture ratio, thin legs, and forced directional risk. It covers edge cases and risks, making it highly complete for a complex 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% and the description adds further meaning: it explains that market and event are mutually required, clarifies side parameter defaults and auto-detection for baskets, and describes size_usd interpretation for both modes. This adds significant value beyond the schema.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth, and distinguishes between single-market and basket modes. It provides specific actions and metrics, which differentiates it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly instructs to use this tool before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. It also warns that partial basket fills convert an arb into an unhedged directional position, providing clear when-to-use and when-not-to-use 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral context: two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explicit warnings that matches may not be tradeable. No contradiction with annotations.

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

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

The description is fairly long but well-structured with clear sections (overview, modes, response, safety fields). Every sentence adds useful information. Could be slightly more concise, but not verbose.

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 3 optional parameters and no output schema, the description is remarkably complete. It explains the response structure (leg-by-leg prices, top spreads, safety fields) and covers edge cases (temporal misalignment, shape mismatch, skipped cross types). No gaps.

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 has 100% parameter description coverage, but the description adds value by listing the 10 pre-mapped topics, explaining that explicit tickers override the topic-mapped side, and warning that topic shortcuts may not yield tradeable spreads. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic and explicit) and describes the output (leg-by-leg prices, top spreads). This distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly tells when to use each mode (topic shortcuts vs explicit tickers) and provides critical guidance: real spreads are rarer than shortcuts suggest, most pre-mapped topics return compatibility warnings, and the safety fields indicate when no arb exists. This gives clear when-to-use and when-not-to-use information.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds useful context: scoping to identifier, behavior when key omitted, and pairing with remember/forget. No contradictions.

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

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

Three sentences, each earning its place: first defines main function, second provides examples of use cases, third adds scoping and pairing info. Front-loaded and efficient with zero 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?

No output schema, but the tool is simple (retrieve one value or list keys). The description covers purpose, usage, scoping, and pairing. It is complete enough for an agent to understand how 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?

Only one parameter 'key' with schema description already covering its behavior (omit to list all). The tool description repeats this but adds no new parameter-specific semantics. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verb 'Retrieve' and resource 'value previously saved via remember'. It also distinguishes from sibling tools 'remember' and 'forget' mentioned explicitly.

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

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

It explains when to use (look up context stored earlier) and how to use (omit key to list all). It pairs with remember and forget. However, it does not explicitly state when not to use or provide alternatives, though siblings are listed in 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?

Goes beyond annotations by explaining the side effect of mark_read, the read-only nature, and that polling is safe. No contradiction with readOnlyHint, idempotentHint, or other annotations.

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

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

Three sentences, front-loaded with core purpose, each sentence provides distinct value without redundancy. Highly 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?

No output schema, but description details return fields (source, citation_uri, payload). Covers all 5 parameters, alternate access method, and polling behavior. Complete for intended use.

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%, but description adds practical examples (e.g., 'sec_8k', ISO timestamp) and explains mark_read effect. Adds value beyond schema.

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

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

Description uses specific verb 'Pull fired events from your subscription feed' and clearly names the resource. It distinguishes from sibling tools like list_subscriptions and subscribe by focusing on event retrieval.

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

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

Explicit guidance on polling suitability and alternative HTTP endpoint. Mentions filter options but does not specify when not to use (e.g., for non-subscription data).

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. The description adds valuable context: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO), explains fallback logic and soft-fail for patents, and mentions the return format with citations.

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 appropriately sized and front-loaded with query examples. Every sentence earns its place, providing clear, structured information without redundancy.

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

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

Although there is no output schema, the description comprehensively explains the return structure (grouped changes by source, total_changes count, citation URIs). It covers all parameters, behavior, and provides a good mental model.

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?

Although schema coverage is 100%, the description adds meaning beyond parameter names: clarifies 'since' accepts ISO dates or relative shorthand (with examples), restricts 'type' to 'company', and explains 'value' can be ticker or CIK. It also recommends '30d' or '1m' for monitoring.

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

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

The description clearly states the tool provides a change feed for a company by aggregating SEC filings, news, and patents within a time window. It distinguishes itself from the sibling tool 'entity_profile' which provides static profiles.

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

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

The description includes explicit usage examples ('What's new with X', 'latest on Y') and provides a direct alternative ('Use entity_profile instead when you want the static profile'). It also explains when not to use this tool.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false, readOnlyHint=false. Description adds context about persistence (24h for anonymous, persistent for authenticated), scoping by identifier, and key-value pair nature, without contradicting annotations.

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

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

Two concise sentences with no fluff. Front-loaded with purpose, then usage, then storage details. Every sentence adds value.

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, but description adequately covers return behavior (implicit storage) and pairs with retrieval/deletion tools. Complete for a straightforward storage 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 coverage is 100%, and description adds meaningful examples (e.g., 'subject_property', 'target_ticker') and clarifies value can be any text, going beyond the schema's basic description.

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

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

The description clearly states the tool saves data for later reuse, with specific verb 'Save' and resource 'data'. It distinguishes from siblings like 'recall' and 'forget' by mentioning them 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?

Explicitly tells when to use: 'when you discover something worth carrying forward'. Also states to pair with 'recall' and 'forget', providing clear alternatives and 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 indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds that each call cascades through several lookup endpoints internally, replacing 2-3 manual lookups. This provides useful context beyond annotations, though more detail on rate limits or data freshness would improve.

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 is purposeful, providing examples, usage context, and detailed output descriptions. The structure is clear and front-loaded with the primary use case.

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?

Despite lacking an output schema, the description thoroughly explains both input and output for each entity type, including specific identifiers returned and citation URIs. It covers the internal cascade behavior, making the tool's behavior fully clear.

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?

Both parameters are fully described in the schema (100% coverage). The description adds significant meaning: for 'type' it lists supported entities, for 'value' it details multiple accepted input formats (ticker, CIK, name for company; brand/generic for drug). It also explains the return values for each type, exceeding schema information.

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

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

The description clearly states that the tool resolves a user-spoken name to a canonical identifier, lists example queries, and distinguishes supported types (company, drug). It explicitly says to use this tool when you have a name but need an ID, differentiating it from other 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 description provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains input formats for each type. However, it does not explicitly state when not to use the tool or name alternatives among the sibling tools.

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

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

Annotations indicate safe, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, returns ranked list with score, confidence, signal density. No contradictions; provides behavioral context beyond annotations.

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