Medicaid Intelligence

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses cost implications ('free' default, 'BYO key — you pay Anthropic directly'), model selection behavior, and the return structure ('per-model {score, confidence, signals, raw_response} + a combined view'). This adds significant value and contradicts nothing in 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?

Three sentences efficiently deliver action, specifics, and use cases. The description is front-loaded and contains no filler, superfluous phrases, or repetition of schema 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?

For a moderate-complexity tool with no output schema, the description is remarkably complete: it explains the core function, model options and costs, return shape, and typical use cases. The annotations cover safety, so no behavioral gap remains.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances this by clarifying the default model when `models` is omitted, the relationship between `_apiKey` and the 'anthropic' model, and that keys are passed through directly. These details add practical meaning beyond the schema's field 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 opens with a specific verb ('Probe') and resource ('LLMs'), states the exact output ('score visibility (0-100) per model'), and lists concrete use cases. This clearly distinguishes it from sibling tools like scan_competitor_ai_presence or ask_pipeworx by focusing on multi-model visibility scoring.

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 provides clear usage context by naming 'AI-marketing audits, pre-launch brand checks, competitive monitoring' as appropriate scenarios. It also explains when to pass `_apiKey` (to add Anthropic) and the default model, but does not explicitly mention alternatives or when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not restate safety. It adds meaningful behavioral context about routing, argument filling, structured answers with citation URIs, and 'one fast call'. It does not cover fallback or error behavior, but the safety profile is already well-covered by 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 the most important instruction and every major section earns its place, including domains, examples, and alternatives. It is somewhat long and includes minor redundancy (e.g., 'START HERE' and 'default entry point' in the same sentence, plus an extensive trigger-phrase list), but overall it is well-structured and not bloated.

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?

Since there is no output schema, the description appropriately explains the return shape: a structured answer with stable pipeworx:// citation URIs. It also covers broad use cases, examples, and step-up alternatives. It could mention handling unanswerable queries or explicit fallback behavior, but for a broad default tool it is reasonably 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?

The input schema fully documents the single 'question' parameter and its aliases (100% coverage). The description adds value with concrete example questions and trigger phrases, guiding the agent on how to formulate queries in natural language beyond the schema's generic 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 states a specific verb+resource: routes questions to 5,344 tools across 1,393 verified sources and returns structured answers with citation URIs. It clearly distinguishes this from ask_pipeworx_grounded and deep_research, positioning itself as the default entry point for factual queries.

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' in a wide variety of domains, lists trigger phrases and examples, and names alternatives with clear when-not conditions: ask_pipeworx_grounded for verbatim evidence, deep_research for broad/multi-part questions. This is thorough usage guidance.

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

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

Annotations already cover readOnlyHint, idempotentHint, and destructiveHint. The description adds dynamic behavioral context: candidate routing improvements are enabled live when under test, the last was retired 2026-07-26, and it is a full working router. This goes beyond the annotations to explain the beta experimental nature.

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 and largely efficient. There is some redundancy between 'No candidate is active right now' and 'currently matches ask_pipeworx exactly', but the clarification that it falls back to nothing—a full working router—is valuable. Overall it earns its length.

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 universal router with no output schema, the description covers identity, usage, current state, and relationship to the stable router. It doesn't explain internals of routing or response format, but given the tool's resemblance to a known sibling, this is sufficiently 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 100%, with all parameters including aliases documented. The description adds 'same arguments' as ask_pipeworx but no additional parameter meaning. Since the schema already handles semantics, 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 identifies this as a beta version of ask_pipeworx, a universal router to 5,344 tools, with identical arguments and response shape. It distinguishes from siblings by highlighting the experimental routing improvements, but doesn't explicitly state the core function of routing user questions to 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?

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. It also clarifies that no candidate is active, so it currently matches ask_pipeworx exactly. However, it doesn't compare against other routing variants like ask_pipeworx_grounded.

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 well beyond the annotations by detailing the internal routing process, the exact return schema for success and refusal, including refusal reasons, and the behavioral guarantee to use only the tool result. It also discloses the extra LLM call cost, which is not captured by 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 dense but well-organized, with the core value proposition front-loaded. Every sentence provides unique information: mechanism, return format, use cases, and alternatives. Despite its length, there is 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?

The description is highly complete for a complex tool: it explains what it does, how it routes, what it returns in both success and refusal cases, when to use it, and the tradeoff vs the sibling. This compensates for the lack of an output schema.

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

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

The input schema fully documents the question parameter and its aliases (100% coverage), so the description doesn't need to compensate. The description's mention of 'fills arguments' is process-related rather than parameter-specific. 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's purpose as a 'hallucination-resistant answer mode for high-stakes reads.' It distinguishes itself from the sibling ask_pipeworx by explaining the same routing but with grounded extraction, and it explicitly names the alternative for casual use.

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 this tool: 'whenever an answer will be quoted, cited, or acted on' and when not to: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff, providing clear guidance for tool selection.

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

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

Annotations declare readOnlyHint/idempotentHint, but the description goes far beyond that. It discloses fan-out behavior, classifier categories, response shapes, resolver confidence handling, parent-event extraction, fallback behavior for news sources, low-confidence short-circuiting, closed-market handling, and resolution-rule risk. These are critical behavioral traits a caller must know and are not visible in annotations alone.

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

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

The description is long but extremely well-organized with bolded logical sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Each sentence carries substantive operational detail. A slight deduction for length—some less critical details (like specific FRED series codes) could be trimmed, but structure compensates.

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

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

For a tool with no output schema, the description compensates thoroughly by documenting all major response fields (result.market, result.analysis, result.evidence, result.parent_event, news fields) and critical edge cases (illiquid spreads, low-confidence matches, closed markets, cancellation rules). This is more than sufficient for an agent to invoke the tool and interpret results safely.

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 schema already documents each parameter's format and defaults. The description adds value by explaining that the 'market' parameter accepts slug/URL/text and is resolved via token-overlap matching, and it clarifies what 'include_raw' means in context of response size. This exceeds the baseline for schema-covered 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 opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains inputs, process, and outputs, and the focus on betting edge distinguishes it from sibling tools like polymarket_arbitrage or ask_pipeworx.

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 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', giving clear when-to-use context. It also describes blocking routes and safety handling, but does not name alternative tools to use instead. This is clear context without explicit exclusions, meriting a 4.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses rich behavioral context: it performs a "parallel call", handles off-calendar fiscal years (e.g., AAPL Sep, NVDA Jan), sorts results by primary metric, and returns "paired data + pipeworx:// citation URIs per entity." 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 a single dense paragraph, but every sentence adds unique information: triggers, usage preference, type-specific data sources, sorting behavior, and return format. It could be slightly more scannable with bullet points, but it is not bloated or redundant for the complexity it covers.

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 two parameters, strong annotations, and lack of output schema, the description is thoroughly complete. It explains what data is retrieved per entity type, how results are sorted, and what the response includes (paired data + citation URIs). It also mentions fiscal-year handling and the efficiency gain (replaces 8–15 lookups), leaving no major ambiguity.

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 substantial meaning: it explains that type="company" pulls specific 10-K metrics and type="drug" pulls FAERS/FDA counts. It also gives concrete value examples ("AAPL", "MSFT"; "ozempic", "mounjaro") and details the output ordering, going far beyond the raw enum and array 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 opens with explicit trigger phrases and a precise definition: "side-by-side comparison of 2–5 companies or drugs in ONE parallel call." It specifies the resources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs) and distinguishes itself from sibling tools by stating "ALWAYS PREFER over sequential single-pack lookups when comparing entities."

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 explicit and actionable usage guidance: "ALWAYS PREFER over sequential single-pack lookups when comparing entities" and lists concrete trigger phrases ("X vs Y", "which is bigger"). It also clarifies the supported entity types (company/drug) and data sources, making clear when to invoke this tool versus slower 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?

Beyond annotations, the description discloses many behavioral traits: it returns a findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], uses semantic excerpting, and never invents answers. It also reveals latency expectations and depth-specific behavior. There is no contradiction with the readOnly/openWorld/idempotent/destructive annotations.

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

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

The description is long but information-dense and logically structured: account prerequisite first, then core purpose, then usage comparisons, then depth semantics, then latency. Every sentence carries useful information, though it could be tightened without losing critical details. It earns its length given 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?

Even without an output schema, the description fully specifies response contents (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps, contradictions), prerequisites, exclusions, and expected durations. An agent can correctly select and invoke this tool without needing additional documentation.

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 schema already covers 100% of parameters, but the description adds meaningful practical context: the question parameter benefits from broad/multi-part phrasing because decomposition is the point, and the depth parameter is clarified with plan requirements and hop behaviors beyond the enum labels. This enriches what the schema alone 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 states a precise verb+resource: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources...' and explains the mechanism (decomposes question, routes to tools in parallel). It clearly distinguishes from siblings: ask_pipeworx is for single lookups, news, or open-web-style questions. This leaves no ambiguity about what the tool does.

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 is explicit about when to use the tool ('Best for broad/multi-part questions over structured data') and when not to ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also states the account requirement and the fallback if not signed in, making selection guidance complete.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds behavioral context by explaining what the tool returns ('top-N most relevant tools with names, descriptions, and full input schemas') and the fact that results are 'ready to call directly, no second schema lookup needed.' It also mentions calling it 'FIRST' as a workflow hint, adding value 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 front-loaded with the core purpose ('Find tools by describing the data or task.') and then efficiently covers usage, return behavior, and when to invoke. The list of domains is a bit long but each item adds clarity for potential use cases. No unnecessary fluff.

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 (no output schema, no nested params), the description is complete: it explains the input type, the output format (top-N tools with schemas), and the recommended usage context. The schema handles parameter details, so the description covers all necessary context for an agent to decide 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 description coverage is 100%, so the schema already documents all parameters including aliases and the 'limit' default. The description's phrase 'describing the data or task' aligns with the 'query' parameter but does not add new semantics beyond what the schema provides. 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's function: 'Find tools by describing the data or task.' It specifies the verb (find/discover), the resource (tools), and the broad scope (SEC filings, FDA drugs, financials, etc.), distinguishing itself from the sibling tools, which are domain-specific data 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?

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use this meta-tool versus directly invoking a specific sibling 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 goes well beyond the read-only/idempotent annotations by disclosing the fan-out across multiple sources, the specific data returned, the patent API sunset with soft-fail behavior, the GDELT→GNews fallback, and the input constraint that names are not supported. 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 dense and information-packed, with examples leading to purpose, return details, and caveats. It is slightly long but every sentence contributes value; no fluff detected. Could be marginally tightened, but not enough to warrant a lower score.

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 full burden of explaining return values. It enumerates the fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news mentions, LEI) and covers failure modes and fallbacks, making it complete for an agent to set expectations.

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

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

Schema description coverage is 100%, and the input schema already fully describes both parameters with examples and the note about names not supported. The description adds minimal new meaning beyond reiterating accepted formats, 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's function with a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It provides many example queries and explicitly differentiates itself from sibling tools by mentioning 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-only inputs.

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 given on when to use this tool ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to (names not supported, use resolve_entity first). Alternative tools and fallback behavior are clearly stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds meaningful context by explaining the tool deletes a previously stored memory and can be used to clear sensitive data, which aligns with the destructive nature. 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 three short sentences: the first states the core action, the second gives usage scenarios, and the third names related tools. Every sentence earns its place with no filler or redundancy.

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

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

For a simple one-parameter deletion tool with no output schema, the description covers the effect, when to use it, and related tools. The annotations cover idempotency and destructiveness, so the description is complete for an agent to select and invoke the tool correctly.

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

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

The input schema fully describes the single 'key' parameter as 'Memory key to delete,' providing 100% coverage. The description merely restates 'by key' without adding new semantic details beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with 'Delete a previously stored memory by key,' which is a specific verb and resource that clearly states what the tool does. It also distinguishes itself from siblings like 'remember' and 'recall' by focusing on deletion.

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 the tool: 'when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with 'remember' and 'recall,' providing relational guidance, though it doesn't explicitly call out when not to use it.

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

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

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds value by detailing the internal process: it fetches the page, extracts title/description/key links, and emits the standard llms.txt format. This goes beyond the annotations and gives the agent a clear mental model of the tool's behavior 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 three sentences long and front-loaded with the primary purpose. It covers the key mechanism, the output format, and relevant use cases without any filler or repetition. Every sentence contributes to understanding, making it highly concise and 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?

Despite having no output schema, the description fully compensates by stating the output is a 'single text blob ready to drop at site-root/llms.txt' and that it follows the standard llms.txt markdown format. For a tool with only two parameters and a straightforward function, the description provides sufficient context for an agent to select and invoke it correctly.

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

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

The input schema already covers 100% of parameters (url, max_links) with descriptions, so the baseline is 3. The description does not add significant semantic detail beyond what the schema provides; it only reinforces that 'url' is for any site and the output is a text blob. It does not elaborate on max_links behavior or defaults, but the schema adequately explains those.

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 ('Generate') with a clear resource ('a production-ready llms.txt file for any URL'), and explains exactly what it does: fetches the page, extracts key info, and emits standard markdown. This distinguishes it from sibling tools like scan_competitor_ai_presence or ai_visibility_check, which focus on different aspects of AI visibility.

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 lists three concrete use cases ('getting a client's site indexed by AI', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), giving clear context for when to use the tool. However, it does not mention exclusions or explicitly name alternative tools, so it stops short of a full 'use X instead of Y' guideline.

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

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

Annotations already declare read-only and idempotent behavior. The description adds useful context about the default active-only filter and the exact fields returned, enhancing transparency beyond annotations 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 concise sentences. The first states purpose and return fields, the second gives usage guidance. Every word earns its place 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?

With no output schema, the description's enumeration of return fields is essential and provided. The single optional parameter is fully covered by the schema, and the simple nature of the tool is adequately addressed.

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

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

Schema description coverage is 100%, with include_inactive fully described in the schema. The tool description does not add any parameter-level details beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and it enumerates the returned fields. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on read-only listing.

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: 'review what you're monitoring before adding more' and 'find an id to cancel.' It does not explicitly name alternatives or state when not to use, but the context is clear given 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 already declare readOnlyHint, idempotentHint, and openWorldHint, and the description adds significant behavioral caveats: suppressed rows are unavailable and totals are gross reimbursement before rebates. These are non-obvious and material for interpretation.

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 exactly two sentences: the first states the core function, the second discloses two critical caveats. It is front-loaded, concise, and every clause earns its place.

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

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

With read-only annotations, an existing output schema, and a simple required parameter, the description covers the essential behavior: aggregation scope, measure separation, suppression handling, and gross reimbursement. No critical information appears missing.

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

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

Both parameters have thorough schema descriptions (format, example, default, and resolution advice), so schema coverage is 100%. The tool description itself adds no extra parameter semantics beyond what the schema already 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 uses the specific verb 'aggregate' with a clear resource ('one exact NDC across states') and explicitly notes that fee-for-service and managed-care measures are kept separate, which distinguishes it from trend or utilization tools in the sibling list.

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 context for when to use this tool (for a single NDC across states with measure separation) and the input schema indicates resolving NDC names first. However, it does not explicitly name sibling alternatives or state 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 destructiveHint, covering safety. The description adds valuable behavioral context beyond annotations, notably that suppressed values are never converted to zero, which is a key data-handling nuance. No contradiction exists.

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 states the core purpose with all key scoping details, the second clarifies a behavioral guarantee. No filler, front-loaded, and 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 captures the essential query scope and a unique data-handling rule. With a full schema and output schema present, the description need not enumerate all parameters or return fields; the existing level of detail is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100% and each parameter is well-documented in the schema. The description reinforces 'exact 11-digit NDC' and the year range but adds no new semantic meaning beyond the existing parameter descriptions. Baseline of 3 is appropriate.

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

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

The description uses a specific verb ('Show') and defines a precise resource: annual Medicaid prescription, unit, and gross reimbursement trends for an exact 11-digit NDC. It clearly distinguishes from siblings like medicaid_drug_utilization by emphasizing the annual trend aggregate, NDC-level focus, and fee-for-service/managed care split.

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 its use case: querying annual trends for a specific NDC from 2020 onward. It provides clear context for when this tool is appropriate, but does not explicitly state exclusions or name alternative tools, leaving some judgment to 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 read-only, idempotent, and open-world traits, so the bar is lower. The description adds valuable context beyond annotations by clarifying that 'Reimbursement is gross before Medicaid rebates and is not manufacturer revenue or net price,' which prevents misinterpretation of the returned data. It also discloses the separation into fee-for-service and managed-care records, enhancing transparency.

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 long with no filler. The first sentence states the core functionality and output; the second provides a critical data interpretation caveat. 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 is largely complete for a read-only query tool: it defines the resource, the required parameter (NDC), the record breakdown, and the economic meaning of the reimbursement field. An output schema exists, so return values are likely documented elsewhere. Minor omissions include default behavior for limit/offset, but these are not critical given the schema and overall clarity.

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 schema covers 67% of parameters with descriptions, including ndc, year, state, and utilization_type. The main description adds context relevant to NDC (exact 11-digit) and utilization_type (separated records). However, limit and offset parameters lack description both in schema and main description, so some gaps remain.

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 action ('Return quarterly state Medicaid utilization rows') and its specific scope ('for an exact 11-digit NDC'), which uniquely separates it from siblings like medicaid_drug_state_market or medicaid_drug_trend. The mention of fee-for-service and managed-care records adds further precision.

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 an exact 11-digit NDC and need quarterly utilization rows. However, it does not explicitly state when to prefer this tool over alternatives, nor does it provide exclusions or alternative tool names. The schema hints at resolving NDC names first, but that guidance is not in the main 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 readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds valuable context beyond annotations by noting that 'Values are preliminary or updated state reports and may include footnotes or missing periods.' This discloses data quality and completeness issues not captured in structured fields.

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

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

The description is two sentences with zero waste. The first sentence states the core purpose; the second adds an essential caveat about data quality. It is front-loaded and 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?

Given the presence of an output schema and comprehensive annotations, the description covers the essential purpose and caveats. It does not explain the month-range relationship, but the schema examples imply it. For a moderately complex tool, this is sufficient 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%, with each parameter (state, to_month, from_month) fully described in the schema. The description adds no meaningful parameter semantics beyond 'for one state,' which is already implied by the schema. Per rubric, baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Show monthly Medicaid and CHIP enrollment and application-processing indicators for one state.' This specific verb+resource+scope distinguishes it from sibling tools like medicaid_drug_trend (drug data) and medicaid_managed_care_summary (managed care data).

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

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

The description provides clear context: it is for 'one state' and covers monthly enrollment and application-processing indicators. However, it does not explicitly name alternative tools for other use cases (e.g., national data or different indicator types), so it lacks explicit exclusions but is still unambiguous about its scope.

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

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

The description adds a crucial behavioral warning: 'Program counts overlap and must not be summed.' This is not conveyed by the annotations (readOnlyHint, idempotentHint, etc.) and is essential for correct interpretation of the data. This goes beyond what annotations provide.

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

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

The description is a single well-structured sentence that leads with the action and resource, lists the relevant categories, and ends with a critical caveat. Every part earns its place 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 presence of an output schema, complete parameter documentation, and strong annotations, the description only needed to add the overlapping-count warning, which it does. This makes the tool fully usable without further 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?

The input schema already provides full descriptions for both parameters (state and year), with 100% coverage. The description does not add additional parameter-level semantics beyond the schema; it focuses on the output categories. Thus the 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 uses a specific verb ('Show') and resource ('state Medicaid enrollment by managed-care program type'), and enumerates the program types (comprehensive MCO, PCCM, MLTSS, behavioral health, dental, transportation, PACE), which clearly distinguishes this tool from siblings like medicaid_managed_care_summary or medicaid_monthly_managed_care.

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 clearly implies when to use this tool: when the user wants enrollment broken down by managed-care program type. It does not explicitly name alternatives or exclusions, but the scope is clear enough for an agent to select it appropriately.

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 safety. Description adds behavioral context about data semantics—state-reported program enrollment vs covered lives—which is a meaningful caveat beyond annotation. No contradiction.

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

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

Two sentences, front-loaded with purpose, second adds caveat. 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?

Given output schema and rich annotations, description covers core purpose and important data caveat. A minor gap on date range behavior is understandable with output schema present.

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 only 33% (only state described). The description implies year parameters via 'annual' but does not explain to_year/from_year semantics such as range inclusivity or behavior when omitted. It does not compensate for the schema gap.

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 'Show', identifies resource as annual state Medicaid enrollment and managed care enrollment, and clarifies scope (any/comprehensive). It distinguishes from siblings like monthly and program mix tools. Not tautological.

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?

Second sentence provides an explicit exclusion: counts are program enrollment, not insurer-covered lives. This tells users when not to use the tool. However, it does not name alternative tools or explicitly state 'use this for X'. So it is clear but not fully explicit.

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

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

The annotations already declare readOnlyHint true, openWorldHint true, idempotentHint true, and destructiveHint false. The description adds a meaningful behavioral detail: 'Data-quality flags and confidentiality suppression are preserved,' which informs the agent that the output may include flags or suppressed data, going beyond the safety profile indicated by annotations.

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

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

The description is two sentences, front-loaded with the primary purpose, followed by a brief note on data-quality preservation. Every sentence earns its place with no extraneous content.

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

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

Given the presence of an output schema and comprehensive annotations, the description provides sufficient context. It covers the tool's scope (single state, participation category), its read-only nature via annotations, and the data-quality/suppression behavior. It does not mention optional time-range parameters, but the schema already documents those.

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 four parameters described (state, to_month, from_month, participation). The description adds no further parameter-level detail beyond restating the state and participation scope, so it remains at the baseline expected for fully covered schemas.

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 monthly Medicaid/CHIP enrollment for a single state and a managed-care participation category, using a specific verb ('Show') and resource ('monthly enrollment'). It distinguishes from sibling tools by explicitly scoping to 'one state' and a specific 'participation category', which differentiates it from summary-level or trend-focused siblings.

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

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

The description provides no explicit guidance on when to use this tool versus the sibling Medicaid managed care tools, no mention of alternatives, and no exclusion criteria. It only states what it does, leaving usage decisions entirely to the agent without actionable 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: it clarifies the response is a bounded sample in API order, warns that zero may represent confidentiality suppression, and emphasizes that the matching-row count is authoritative despite the sample limitation. These details go well beyond the annotations and help the agent interpret results correctly.

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 action verb 'Return', and every phrase adds meaning—sample scope, filtering, count behavior, and a data-quality caveat. There is no wordiness or repetition of schema data, making it highly efficient for its informational 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?

The output schema exists, so return-value details are not needed. The description covers the essential behavioral quirks (bounded sample, authoritative count, zero suppression). However, it does not clarify pagination or the meaning of limit/offset, and given the large set of medicaid sibling tools, a hint about when this sample tool is preferable could improve completeness. Still, the core is well covered.

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 20% (only 'state' has a description). The description explains that the tool filters by state and optional year, but it does not explain the meaning of 'limit', 'offset', or 'parent_organization'. It adds slightly more clarity about year being optional, but fails to compensate for the undocumented parameters, leaving significant ambiguity for the agent.

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 Medicaid managed-care plan/program rows by state and optional year, with an authoritative matching-row count. It uses a specific verb ('Return'), names the exact resource type, and differentiates from siblings like medicaid_managed_care_summary or medicaid_drug_state_market by focusing on managed-care plan rows and sample behavior.

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 one needs a sample of Medicaid managed-care plans by state/year with an authoritative count, but it does not explicitly state when to use this tool over alternatives or provide exclusions. No sibling alternatives are mentioned, and no explicit 'use this when...' or 'instead of...' guidance is provided.

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

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

Annotations provide no read-only or destructive hints, and the description adds valuable behavioral context: rate-limited to 5 per identifier per day, free, and doesn't count against quota. It also notes the team reads digests daily, giving the agent insight into the effect of using the tool.

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

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

The description is three sentences, front-loaded with the core purpose, and every sentence adds essential information (usage categories, constraints, rate limits). No fluff or repetition of schema details.

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

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

For a feedback tool with three parameters and a nested context object, the description covers purpose, usage, rate limits, and content guidance. No output schema is needed for a submission tool, and the description is sufficiently complete for an agent to invoke it correctly.

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

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

Schema coverage is 100% with per-property descriptions for all parameters. The description adds complementary guidance for the 'message' field (describe in terms of tools/packs, don't paste user prompt), which is not fully captured in the schema.

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

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

The description states the tool's purpose with a specific verb ('Tell the Pipeworx team') and resource, clearly distinguishing it as the feedback channel. It enumerates categories (broken, missing, praise) which aligns with the type parameter, making it unambiguous.

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 when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug)... when a tool you wish existed isn't in the catalog (feature/data_gap)... or when something worked surprisingly well (praise).' It also gives an exclusion ('don't paste the end-user's prompt'), leaving no doubt about 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?

With annotations already indicating read-only, idempotent, open-world, and non-destructive behavior, the description adds valuable context: it explains the data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached for 5min-1h depending on window. This goes beyond the annotations and gives the agent a fuller picture of what to expect.

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 with a leading summary sentence, a numbered list of use cases, and a final technical note. It is slightly longer than strictly necessary but every sentence contributes useful information. The front-loaded main clause helps the agent quickly grasp the core 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?

For a simple read-only tool with one optional parameter and no output schema, the description is exceptionally complete. It covers the purpose, use cases, data source, privacy implications, caching behavior, and window semantics. There are no significant gaps for an agent to select and invoke this tool correctly.

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

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

The schema provides 100% description coverage for the single 'window' parameter, including its enum values and the semantic difference between shorter and longer windows. The tool description does not add additional parameter semantics beyond what the schema already documents, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window.' The verb 'Returns' is specific, and the resource (Pipeworx usage) is well-defined. It distinguishes itself from siblings like discover_tools by focusing on what other AI agents are calling, not just discovery.

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 three explicit use cases: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. This gives clear context for when to use the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it stops short of the highest rating.

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 readOnly/openWorld/idempotent/non-destructive, and the description does not contradict them. It adds substantial behavioral detail beyond annotations: trending_scan scope, event-mode child market walking, >3pp partition signal threshold, ≥0.30 Jaccard semantic anchor, placeholder fraction >20% returning null, fill_check against CLOB depth, and the precise condition for avoiding a trade. This is far beyond what annotations alone 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 lengthy but carefully structured with clear mode sections and uppercase labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence carries specific, non-redundant information. It is front-loaded with the core purpose and then methodically covers filters, response shape, and fill-check conditions.

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

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

Given a complex tool with no output schema, the description is remarkably complete: it defines the response fields (`opportunities[]`, `partition_check`), explains threshold values, edge-case filtering, semantic constraints, and real-world tradability via fill_check. An agent could select and interpret this tool correctly with no additional 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?

Input schema already describes both params with 100% coverage, so the baseline is 3. The description adds further value with concrete examples, mode-specific recommendations, and clarifies that zero arguments is a valid mode. It also explains behavioral differences between event and topic in detail, though much of that is tool behavior rather than 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 leads with a specific verb and resource ('Find arbitrage opportunities on Polymarket') and explains the methodology ('monotonicity violations + partition-sum checks'). It clearly distinguishes three operating modes (trending_scan, event, topic) and positions itself against sibling tools via the fill-check and custom-sizing references.

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 call with no args, when to use `event`, and when to use `topic`, including recommendations and what each mode catches. It also names an alternative tool (`polymarket_fill_risk`) for custom sizing, and warns not to trade when realizable edge is non-positive. This is excellent, actionable usage 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?

The description discloses a wealth of behavioral details well beyond the read-only/idempotent annotations: it details output structure (by_segment, _diagnostics), caching behavior (1h KV cache keyed on knobs), internal model logic (lognormal barrier, GDELT ratio, partition overround with sport-specific α), and the 24h-move warning about edge erosion. It also explains why Fed bets are excluded and why segments might be empty, offering transparency into failure modes. 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 long and dense, but every sentence packs meaningful information—output fields, model families, diagnostic counters, and filters—necessary because no output schema is provided. The use of all-caps mini-headers (TRADEABLE-EDGE KNOBS, RESPONSE TOP-LEVEL) helps navigation, though it could be broken into bullet points for better skimmability. 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 no output schema, the description compensates by thoroughly specifying the top-level response structure (by_segment, fed_candidates, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and the meaning of diagnostic counters. It covers model families, filtering knobs, caching, and limitations (Fed signal unreliability). This is a near-complete mental model for agent invocation.

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

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

Schema coverage is 100%, so parameters are already well documented. The description adds value by grouping min_liquidity and max_spread_pp as 'tradeable-edge filters' and noting that the cache is keyed on all knobs, which affects how parameter changes interact with freshness. It also clarifies the min_partition_leg_kelly nuance about parent-level kelly being zero, which is already in the schema, but the description frames it in the broader response context. This is more than the baseline 3, though not dramatically so.

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

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

The first sentence clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, establishing a specific verb, resource, and scope. It goes further by describing the three response segments and model families, which differentiates it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker. The 'Built for' phrase frames a distinct use case.

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 opens with 'Built for "what should I bet on today"' which explicitly states the intended use case. It also discusses knobs like min_liquidity, max_spread_pp, and category_filter, giving guidance on when to apply them, and explains the tradeability filters. It doesn't explicitly name when not to use it or contrast with sibling tools, but the level of contextual detail is strong.

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 far exceeds the basic read-only annotation by disclosing critical behavioral nuances: snapshots are written on cache-miss so gaps indicate no scan, history is bounded by a 60-day TTL, and decay is computed from daily closes rather than intraday data. This adds significant context beyond the annotations about data availability and computational methodology.

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?

Though longer than average, the description is well-structured with clear ARGS, RESPONSE, and LIMITS sections. Every sentence adds essential value, explaining the tool's unique output format and operational constraints without filler or redundancy.

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

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

Given there is no output schema, the description compensates fully by detailing the response structure (tracked[], expired[], snapshot_dates[]) and explaining key metrics like decay_pp_per_day, lifespan_days, and the meaning of gaps. It provides a complete mental model for how the tool behaves and what data it returns.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the defaults for 'days' and 'window' but does not add deeper semantic meaning beyond what the schema already provides. The only minor addition is reinforcing that 'window' refers to a snapshot family, but that is already in the schema.

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

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

The description clearly defines the tool as edge persistence and decay telemetry built from daily snapshots, answering the specific question of whether an edge is new or old. It distinguishes this from sibling tools like polymarket_edges by focusing on time-series trend analysis rather than just current edge values.

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 strong contextual guidance, explaining that a fresh wide edge and a 3-week-old wide edge are different trades, implying when to use this tool to assess edge persistence. It also notes limitations about TTL and snapshot gaps, but does not explicitly name alternative tools for current edge data, leaving the 'when-not-to-use' 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 declare readOnlyHint=true and destructiveHint=false, and the description adds no contradiction. It further discloses critical behavioral traits: the tool 'walks the ladder' to compute fill prices, returns a verdict of clean|degraded|cannot_fill, and warns that 'partial basket fills convert an arb into an unhedged directional position' — a subtle risk beyond what annotations convey.

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

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

The description is long but well-structured with SINGLE-MARKET, BASKET, and USE THIS sections. Each sentence carries necessary operational or risk information, and the primary purpose is front-loaded. It loses one point for being dense enough that an agent might need to parse carefully, but no filler exists.

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?

This is a complex, two-mode tool with no output schema, so the description must explain outputs — and it does extensively, listing single-market returns (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict) and basket returns (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], forced_directional_risk). It also provides the contextual warning about loss modes, making it complete for invocation.

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

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

Input schema has 100% parameter description coverage, so baseline is 3. The description adds meaningful semantic context beyond the schema by clarifying that size_usd means 'max spend on buys, target proceeds on sells' and that basket size_usd is settlement notional with shares paying $1, and it adds the mutual-exclusion constraint ('REQUIRES one of market or event'). This enriches how the parameters relate to each other, justifying a 4.

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

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

The opening line 'Realizable-vs-theoretical edge check against live CLOB order-book depth' uses a specific verb ('check') and resource ('live CLOB order-book depth'), clearly distinguishing this from sibling tools like polymarket_arbitrage and polymarket_edges. The description also explicitly separates SINGLE-MARKET and BASKET modes, establishing its unique role as a fill-risk validator.

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 final sentence gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the rationale (theoretical overround on thin books is not capturable) and provides mode-selection rules ('REQUIRES one of market or event'), making alternatives and exclusions unambiguous.

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 goes far beyond, detailing two usage modes, response structure, compatibility_warning cases, temporal alignment, and skipped counters. It provides rich behavioral context 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?

The description is long but every sentence earns its place, covering purpose, modes, response format, and pitfalls. It is well-structured with clear labels like 'TWO MODES', 'RESPONSE', and 'SAFETY FIELDS', making dense information scannable.

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 complexity and absence of an output schema, the description thoroughly explains what is returned (leg-by-leg prices, spread, compatibility_warning, temporal_alignment, skipped counters) and how to interpret edge cases. It is comprehensive enough for correct invocation and result interpretation.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances this by listing the exact topic values, explaining how explicit tickers/slugs override topics, and clarifying the auto-fetch behavior. It adds meaningful context 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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' with a specific verb (spread comparison) and resource (two prediction markets). It distinguishes itself from sibling tools by emphasizing cross-venue analysis, which is unique among the listed 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 explains two modes (topic shortcuts and explicit ticker/slug) and provides strong guidance on when results are meaningful vs. when compatibility warnings fire. It lacks explicit 'use this instead of X' statements for sibling tools, but the context is clear enough for an agent to decide.

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?

With annotations declaring readOnlyHint=true and destructiveHint=false, the description adds value by explaining the scoping behavior (anonymous IP, BYO key hash, account ID) and the listing behavior when key is omitted. This goes beyond the annotations, though it does not describe return format or errors.

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

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

The description is three sentences, front-loaded with the primary action, and every sentence adds useful information: the action, the use case, and the relationship to sibling tools. No redundant or irrelevant 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?

For a simple tool with one optional parameter and no output schema, the description fully covers the purpose, usage, scoping, and relationships. It is sufficiently complete for an agent to decide when and how to invoke the 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% with the key parameter already described, so baseline is 3. The tool description enriches this by giving examples of key values (target ticker, address) and clarifying the omit-to-list behavior, adding meaning beyond the schema's minimal 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 retrieves a saved value or lists saved keys, with the verb 'Retrieve' and resource 'a value previously saved via remember'. It also explicitly references sibling tools 'remember' and 'forget', distinguishing its role as the lookup counterpart.

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 context for when to use (look up previously saved context) with concrete examples (user's target ticker, address, research notes). It mentions pairing with remember and forget, indicating alternatives, but does not explicitly state when not to use it, stopping short of a full 5.

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

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

The description states 'Set mark_read:true to flag returned events read so the next call only shows newer ones', which describes a persistent side effect and non-idempotent behavior. However, annotations declare readOnlyHint=true and idempotentHint=true, directly contradicting this side effect. The annotation contradiction forces a score of 1.

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

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

The description is three sentences with no filler. It front-loads the core purpose, then provides filtering details, mark_read semantics, and an alternative endpoint in a compact, scannable format. 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?

Despite having no output schema, the description covers returned payload fields (source, citation_uri, raw event payload), filtering options, mark_read behavior, polling suitability, and even provides an external URL for programmatic access. Given the low complexity and rich annotations, this is complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by giving a concrete type example ('sec_8k'), explaining the consequence of mark_read (next call shows only newer events), and summarizing the return payload fields. This additional context justifies a 4.

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

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

The description opens with 'Pull fired events from your subscription feed', a specific verb+resource pairing that clearly distinguishes this from sibling tools like subscribe/unsubscribe/list_subscriptions. It also details what is returned (recent alerts with source, citation_uri, raw payload), leaving no ambiguity about the tool's function.

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

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

It gives practical usage context: filtering by type and since, polling behavior ('Polls work fine'), and an explicit alternative for scripts/dashboards ('the same feed is also at GET registry.pipeworx.io/alerts.json'). It does not explicitly state when not to use this tool vs alternatives, but the context is sufficiently clear for an agent to choose appropriately.

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, openWorldHint, idempotentHint), the description discloses crucial runtime behavior: parallel fan-out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO PatentsView sunset causing soft-fail, and the exact return shape (changes[] grouped by source + total_changes count + citation URIs). This is exactly the kind of behavioral context agents need. 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 dense but every clause earns its place: user-intent examples, data source pipeline, fallback logic, parameter formats, output shape, and an explicit alternative tool. It fronts with user-facing phrasing ('What's new') to maximize quick comprehension, then delivers technical specifics in a tight, structured flow.

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?

This is a high-complexity tool (multi-source fan-out) with no output schema, so the description must carry the full burden of explaining behavior and return values. It does: sources queried, fallback order, failure modes, parameter grammar, and the result structure. The inclusion of pipeworx:// citation URIs also prepares the agent for linking. Nothing critical is missing.

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

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

Schema coverage is 100%, and the description enriches the parameters: 'since' accepts ISO or relative shorthand with concrete examples ('7d', '30d', '3m', '1y') and recommends '30d' or '1m' for monitoring; 'value' can be ticker or zero-padded CIK; 'type' is limited to 'company'. This adds practical guidance beyond the schema field 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 opens with concrete natural-language examples ('What's new with X', 'latest on Y') and then states a specific verb+resource+scope: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It also distinguishes itself from entity_profile by naming the alternative, making it clear which tool suits a given intent.

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 usage context through exemplar queries and clarifies when NOT to use it: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This gives the agent concrete decision rules for tool selection 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?

Beyond the annotations (idempotentHint, destructiveHint), the description adds critical behavioral context: storage as a key-value pair, scoping by identifier, and differing retention policies for authenticated vs anonymous users (persistent vs 24 hours). 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 concise and front-loaded, starting with the primary action ('Save data the agent will need to reuse later'). Each sentence provides distinct value: use case, storage mechanics, retention policy, and relationship to sibling tools. 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?

For a simple memory-write tool, the description covers all essential operational aspects: when to use, how storage works, persistence details, and how to retrieve/delete. Given the idempotent annotation and lack of output schema, no critical context is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some context by explaining the storage model ('stored as a key-value pair'), but does not add significant parameter-specific details beyond the schema's examples. The examples given in the description mirror those in the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later'. It differentiates from siblings by explicitly mentioning 'Pair with recall to retrieve later, forget to delete', distinguishing from recall and forget. The verb 'save' plus the resource (data/key-value) is specific.

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 use context: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also names alternative tools and their complementary roles, saying 'Pair with recall to retrieve later, forget to delete.'

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?

While annotations already declare readOnly/idempotent/non-destructive, the description enriches this by specifying exactly what is returned (ticker, CIK, company_name, citation URIs for companies; RxCUI, ingredient, brand for drugs) and disclosing internal cascading behavior. It also notes auto-disambiguation and that it replaces multiple manual lookups, giving the agent a clear model of the tool's behavior and side effects.

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 compact yet information-dense, starting with concrete example queries to set context, then providing explicit use-first guidance and a structured breakdown of supported types. Every sentence adds value, with no filler or repetition of the schema.

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

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

Given the absence of an output schema and the tool's moderate complexity, the description provides a complete picture: purpose, when to use, supported types, input formats, output details, and efficiency benefit. It also fits well within the sibling-tool context where other tools likely require identifiers, making this the necessary prerequisite step.

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, but the description adds significant semantic value beyond the schema: it clarifies accepted input formats (ticker, CIK, or name for company; brand or generic for drug), explains the output context for each type, and highlights auto-disambiguation. This fully compensates for any ambiguity in the raw 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 resolves user-spoken names to canonical official identifiers, with a specific verb ('resolve') and resource ('NAME to identifier'). It explicitly distinguishes itself from sibling tools by focusing on identifier lookup rather than entity profiles or comparisons.

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 explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also names the two supported entity types (company and drug) and gives concrete example phrases, making the intended use case unmistakable. This effectively tells the agent when to choose this tool over 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 the tool as read-only, idempotent, and non-destructive. The description adds behavioral context by explaining it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific metrics. This goes beyond the annotations and clarifies the tool's internal behavior, though it doesn't disclose rate limits or API key handling details.

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 and well-structured: three sentences covering the action, the method, a use case with example, and the output format. Every sentence adds value, and the key functionality is front-loaded ('Compare AI visibility across multiple entities side-by-side').

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 moderate complexity (composite operation across multiple entities), the description adequately covers the purpose, method, use case, and output. The schema fills in parameter details, and annotations cover safety. It lacks only minor behavioral specifics (e.g., how the ranking is computed, handling of model failures), but is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaningful semantic nuance for the 'entities' parameter by explaining the first entry is the subject and the rest are competitors, and contextualizes the usage ('your brand + N competitors'). This enriches the schema's basic description of 'array of 2-8 entities to compare'.

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 ('Compare'), identifies the resource ('AI visibility across multiple entities'), and explicitly distinguishes itself from the sibling ai_visibility_check by focusing on side-by-side multi-entity comparison and ranking. It clearly states the tool's core function and output (ranked list with score, confidence, signal density).

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 a concrete use case ('competitive AI-marketing audits') with an example question, and implies when to use it over ai_visibility_check by emphasizing multiple entities. It also notes the first entity is treated as the 'subject' for narrative, which is a practical usage guideline. However, it does not explicitly state 'use this instead of X' or mention alternative tools like 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 readOnly, idempotent, and non-destructive, but the description adds substantial behavioral context: it fans out across multiple sources, returns a specific summary block, degrades gracefully on partial failures, and warns that bundlephobia's first measurement can take 5-30s. It also reveals the output structure, which is not in an output schema.

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

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

The description is dense but organized with clauses and parentheses, front-loading the purpose. While longer than two sentences, the complexity of a composite tool justifies the detail; each clause provides operational value. Could be tightened but is appropriately sized.

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

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

For a tool with no output schema, the description fully enumerates the returned fields (summary block, per-advisory detail, links, alternatives) and explains failure behavior and latency. Ecosystem scope is explicitly stated. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no new parameter semantics beyond the schema—'package' accepts scoped packages and version defaults to latest, both already in the schema. It doesn't need to compensate.

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

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

States explicitly that this is a composite check for adding npm packages, combining deps.dev and bundlephobia data. The verb 'scan' plus resource 'dependency' is specific, and the description distinguishes it from siblings by focusing on npm ecosystem evaluation. No sibling confusion.

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 explicit trigger phrasing: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also gives an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This clearly delineates when to use vs 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?

Beyond the annotations' read-only and idempotent hints, the description reveals truncation at 200K chars (with flagging), the embedding model (BGE-base-en), cosine similarity over 500-char overlapping windows, and that outputs include offsets and scores. This is actionable behavioral detail.

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

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

The description is a single dense paragraph: purpose first, then use case, then technical details. No fluff; the pairing note with ask_pipeworx_grounded and the truncation flag are both valuable.

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

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

With no output schema, the description compensates by naming return fields (passages, offsets, similarity scores). It also covers the input cap, truncation behavior, and relationship to a sibling tool, making it self-sufficient for agent decision-making.

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

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

Schema covers all three parameters (text, query, limit) with 100% coverage, so the baseline is 3. The description's examples ('SEC 10-K body', 'supply-chain risk') add marginal color but don't change parameter semantics substantially.

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 opens with 'Semantic search INSIDE a fetched record' — a specific verb and resource that clearly differentiates from sibling tools like ask_pipeworx_grounded. It explains the input (pre-fetched text) and output (passages), making the tool's role unambiguous.

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 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded, giving a concrete workflow. This tells the agent exactly when to choose this tool over the grounded Q&A 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 discloses the OAuth account requirement, feed always-on behavior, and SMS constraints (phone verification, 10/day cap). However, it omits the webhook delivery channel and its behavioral details (signing secret, auto-disable after 10 failures), which are only in the input schema, so the description is not fully transparent.

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 and uses structured, scannable sentences. It is somewhat long and repeats examples already present in the schema's params and delivery descriptions, but it is not excessively verbose. The omission of webhook is a content issue, not a structure issue.

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 account prerequisites, supported subscription types, feed delivery, and email/SMS options, and states the return value (subscription id). However, it fails to mention the webhook delivery channel, which is a significant option in the schema, making the description incomplete for a tool of this 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?

The input schema already provides 100% coverage with detailed descriptions and examples for each parameter type. The tool description adds the feed pull mechanism and OAuth context but largely repeats schema-provided examples (e.g., sec_8k items, fred_series). Thus it adds marginal 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 'Create a proactive monitoring subscription to a live-data event stream' and 'Returns the new subscription id,' making the verb, resource, and purpose explicit. It distinguishes from sibling tools like list_subscriptions and unsubscribe by indicating it's a creation action.

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 provides clear context on when to use: to set up monitoring for live-data events, with supported types and delivery channels. However, it does not explicitly name alternatives or exclusions, and it omits the webhook delivery option, which limits full 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?

Beyond the readOnly and idempotent hints, the description discloses the return structure (category-bucketed questions), the inclusion of tool + argument shape, the live catalog source, and the behavior of the topic parameter. This adds substantial context not available from annotations alone.

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

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

The description is a bit long but each sentence contributes meaning. It is front-loaded with common user intents, then explains the purpose, return content, and usage. The structure flows well, though the opening list of intents is not strictly necessary 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?

The description covers what the tool does, what it returns, how to call it, and when to use it. It even names closely related meta-tools. Given the simple parameter structure and lack of output schema, this description is fully sufficient for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete example values ('finance', 'pharma', 'betting') and explaining that omitting the topic returns a full spread, which is more actionable than the schema's generic list.

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

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

The description clearly identifies the tool as the onboarding entry point for discovering what Pipeworx can do, and specifically states it returns category-bucketed example questions with the exact tool and argument shape. This distinguishes it from siblings like discover_tools and ask_pipeworx.

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 FIRST when unsure what Pipeworx can do, and even names the meta-tools (ask_pipeworx, entity_profile, compare_entities) that the agent should learn to call. It also explains the topic parameter usage, making when-to-use clear.

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

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

Annotations mark the tool as non-read-only and non-destructive; the description adds crucial behavior: ownership is enforced, and the row is deactivated rather than deleted, preserving history via recent_alerts. This meaningfully supplements the annotation 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?

Two sentences, front-loaded with the core action; the second sentence packages key caveats without redundancy. 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?

For a one-parameter cancellation tool, the description covers action, ownership, and data-retention semantics, and references recent_alerts for historical events. No output schema exists, but return details are not critical for this simple operation.

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

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

The input schema fully documents id as a UUID returned by subscribe, providing a solid baseline. The description adds that the id must belong to the caller, an ownership eligibility condition not present in the schema.

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

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

Description opens with 'Cancel a subscription by id' — a specific verb and resource that clearly distinguishes it from sibling tools like subscribe and list_subscriptions. The additional deactivation detail reinforces the tool's exact purpose.

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 conveys when the tool applies (canceling an existing subscription) but does not explicitly compare it against alternatives like subscribe or list_subscriptions, nor does it state when not to use it. Ownership enforcement is a constraint rather than an alternative recommendation.

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 readOnly/openWorld/idempotent annotations, the description discloses the internal processing (SEC EDGAR + XBRL fast path vs grounded pipeline), the evaluation method (exact percent-delta math), and the return structure (verdict, actual value with citation, reasoning). This gives the agent a solid mental model of what the tool does and how results are produced, exceeding the 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 compact despite its length; every sentence contributes the purpose, scope, processing paths, output, and efficiency benefit. It is front-loaded with trigger phrases and purpose. However, a few phrases could be tightened without losing clarity, so a 4.

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

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

For a complex tool with no output schema, the description covers purpose, usage, behavioral details, return values, and even explains why it replaces multiple calls. It fully equips the agent to invoke and interpret the tool. No major 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 description coverage is 100%, so the description adds little beyond what the schema already documents. While the description mentions percent-delta math and tolerance, the schema's parameter descriptions are already detailed. 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's function: natural-language claim verification against authoritative sources, with trigger phrases and specific output verdicts. It distinguishes itself from siblings by emphasizing the claim verification focus and the two-path approach (SEC EDGAR for financial, grounded pipeline for other facts), which differentiates it from general Q&A tools like ask_pipeworx.

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 explicit usage instruction ('Use whenever the agent needs to check whether something a user said is factually correct'). Explains the two categories of claims (company-financial vs other) and how they are routed. Does not explicitly mention when NOT to use it, but the scope is clearly defined, making it a 4 rather than 5.

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