Uk Food Hygiene

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds beyond that: mentions per-model return fields (score, confidence, signals, raw_response), combined view, default model, and that Anthropic probing costs via user's own key. This is useful 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?

Two sentences; first sentence states core action and output, second sentence adds customization details. No unnecessary words. Front-loaded with essential info.

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 4 parameters and no output schema, the description covers input, output format, use cases, and model selection. It could mention that results are read-only (already in annotations) or error behavior, but overall it's sufficient for an agent to decide and invoke.

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 good descriptions. The description adds value by summarizing the score range (0-100), naming the default model (Workers AI Llama-3.3-70b), and clarifying the purpose of the context parameter. It doesn't add new syntax but reinforces meaning.

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 main verb 'Probe' and 'score', identifies the resource (LLMs for a business/brand/product/topic), and states the output (visibility 0-100 per model). It clearly distinguishes from siblings like compare_entities or deep_research by focusing on 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?

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It mentions default model and optional Anthropic with BYO key, giving context. However, it doesn't explicitly say when NOT to use it or compare to alternatives like ask_pipeworx.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by explaining the routing mechanism (5,521 tools, 1,452 sources), the citation output, and operational characteristics ('works on every tier, one fast call'). No contradictions with annotations.

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

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

The description is longer than average but front-loaded with the key directive 'PREFER OVER WEB SEARCH' and organized logically from core function to usage examples to escalation paths. It contains some redundancy (the examples repeat what's in the schema), but every sentence contributes useful guidance without excessive 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?

For a tool with no output schema, the description adequately explains the return format ('structured answer with stable pipeworx:// citation URIs'). It covers target domains, usage triggers, examples, alternatives, and news handling, making the description self-sufficient 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 description coverage is 100% because all six parameters are documented as aliases for 'question' with descriptions. The tool description itself adds examples and clarifies the aliases, but no new semantics beyond what the schema already provides. Baseline 3 is appropriate given the high schema coverage.

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

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

The description clearly states the tool's function: it routes questions about current or historical data to one of 5,521 tools across 1,452 sources and returns structured answers with citations. It explicitly lists covered domains (SEC filings, FDA drug data, economic statistics, etc.) and differentiates from siblings by naming ask_pipeworx_grounded and deep_research as alternatives for specific needs.

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 when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and provides concrete trigger phrases ('what is', 'look up', 'get the latest') plus examples. It also states when NOT to use it, directing to ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad/multi-part questions, making the usage context unmistakable.

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

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

The description adds behavioral context beyond annotations: it is a beta with candidate routing improvements that may be enabled live, currently matches the stable version, and 'falls back to nothing' meaning it is fully functional. It does not contradict the readOnly, openWorld, idempotent, non-destructive annotations, and while it doesn't detail side effects of the routed tools, that is acceptable given this tool itself is read-only.

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

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

The description is three sentences, front-loaded with the beta identity and key information. Every sentence adds value: what it is, current status, usage guidance, and reassurance of functionality. No waste or redundancy.

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

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

Given the tool's complexity (a router for 5,521 tools), the description adequately covers its purpose, relationship to ask_pipeworx, and usage. It mentions identical response shape, and since there is no output schema, it doesn't need to detail returns. It could slightly expand on what a 'universal router' does, but it is sufficient for an agent selecting this tool.

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

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

Schema coverage is 100% and all six parameters are aliases for one required 'question' field, each with clear descriptions. The description states 'same arguments' as ask_pipeworx but adds no new parameter-level detail beyond what the schema already 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 identifies this as a beta version of ask_pipeworx, a universal router handling 5,521 tools with the same arguments and response shape. It distinguishes itself from the stable version by being the experimental edge, and it explicitly states it is a full working router. The purpose is specific and 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?

The description gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no candidate active, matches ask_pipeworx exactly) and explains that results are compared against the stable router. This provides clear when-to-use context and contrasts with the stable alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral detail beyond this: refusal reason enum, return shape, and the 'one extra LLM call' cost. No contradiction exists, and the additional context about refusal behavior is valuable for high-stakes use.

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?

Although the description is a single long paragraph, every sentence earns its place: purpose, mechanism, return value, refusal conditions, use cases, and cost trade-off. It is front-loaded with the primary benefit and uses precise language without filler.

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

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

Without an output schema, the description fully documents the return shape including the refusal reason enum. It also covers routing behavior, cost, and usage guidance, making it complete for a complex tool with no output schema. The differentiation from siblings like ask_pipeworx_beta adds necessary context.

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

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

Schema description coverage is 100%, and the description does not add parameter-level detail. The parameter aliases are fully documented in the schema, so the description need not repeat them. Baseline 3 is appropriate because the schema handles the heavy lifting; the description adds no extra value for 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 'Hallucination-resistant answer mode for high-stakes reads,' which clearly states the tool's specific function and differentiates it from the sibling ask_pipeworx. The verb 'answer mode' and the focus on extraction from tool results make the purpose concrete and distinct.

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

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

The description explicitly states when to use this tool: whenever answers will be quoted, cited, or acted on, and the agent must not invent facts. It also provides a clear exclusion by saying 'prefer ask_pipeworx for casual lookups,' and names the alternative ask_pipeworx directly.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral detail: resolver contract with market_match_confidence, parent_event extractor, news fallback mechanisms, safety short-circuits, tradeability warnings, and cancellation rule parsing. No contradictions with annotations.

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

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

The description is very lengthy (multiple paragraphs). While it is well-structured with clear sections, it could be more concise. The level of detail is valuable but at the cost of brevity. It earns its place but not tightly written.

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 lack of output schema, the description thoroughly covers inputs, outputs, edge cases (low confidence, closed markets, wide spreads), error handling, and resolution rules. It leaves no critical gaps for an AI agent.

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%. The description adds value by explaining the flexibility of the market parameter (slug, URL, question text) and clarifying the effects of depth and include_raw. It provides examples and scenarios for parameter usage.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, question text) and outputs (evidence packet + comparison). This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edges, which focus on different aspects.

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 recommends usage for questions like 'should I bet on X' and provides examples of classifiers and fan-outs. However, it does not explicitly contrast with sibling tools, leaving some ambiguity about when to prefer alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context: results sorted by primary metric, includes pipeworx:// citation URIs, handles off-calendar fiscal years with examples. No mention of rate limits, but overall good 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?

Single paragraph packs a lot of useful information without wasted words. Could be slightly more structured (e.g., separate sections for company vs drug), but still efficient and readable.

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

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

Covers input format requirements, data sources, output structure (sorted, paired data, citations), and use cases. With annotations providing safety hints, no significant gaps for an agent to make informed decisions.

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% (parameters have descriptions). Description significantly enriches each parameter: explains what data each enum value fetches (company: revenue/net income/etc.; drug: adverse events/FDA/trials) and proper formats for values (tickers/CIKs vs drug names). Adds meaning beyond schema.

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

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

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs. It provides specific trigger phrases and details what data each entity type retrieves (company: financials from SEC; drug: FAERS/FDA/trials). Strong verb+resource differentiation from sibling tools like entity_profile.

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

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

Explicitly instructs to prefer this tool over sequential single-pack lookups for comparisons. Provides concrete use cases and trigger phrases. This is a model for when-to-use guidance.

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

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

Despite annotations already marking readOnlyHint=true and dangerous=false, the description adds substantial behavioral context: account requirements, latency estimates (15-60s, up to ~90s), how gaps are handled (explicit gaps[], never invented), contradiction scanning, semantic excerpting not head-truncation, citation_uri resolvability, and the limitation that current-news topics yield mostly empty gaps. This goes well beyond annotations and honestly discloses edge-case behavior.

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

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

The description is long but packed with useful, structured information. It is front-loaded with the account requirement and then proceeds logically: what it is, what it returns, when to use, what to avoid, depth nuances, and performance expectations. There is a slight redundancy (paid plan noted twice) and a heavy wall of text, but every major point earns its place. It could be tightened, but it is far from wasteful.

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 lack of an output schema, the description thoroughly covers return values (findings packet with evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop field, and citation_uri semantics. It also explains limitations (current-news gaps), latency, and iteration behavior. The description is complete enough for an agent to understand what to expect and when to choose it.

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

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

Schema coverage is 100%, so the schema already documents the parameters. The description adds meaningful semantic context: depth values are mapped to facet counts (quick=3, standard=5, thorough=8), the default for standard is stated, and thorough is flagged as paid. It also clarifies that the question can be broad/multi-part because decomposition is the point. This adds value beyond the schema's raw enum, though not quite a full extra layer of 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 clearly states a specific verb+resource: 'grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources in ONE call,' with a detailed scope (decomposes questions, routes to tools, returns a findings packet). It explicitly distinguishes from sibling tools (ask_pipeworx, open-web search) and names its target use case, making its purpose unambiguous and non-overlapping.

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 when-to-use guidance: 'Best for broad/multi-part questions over structured data' and contrasts with alternatives ('For a single lookup use ask_pipeworx'; for breaking/current news 'prefer ask_pipeworx'). Also includes account/prerequisite instructions (sign in via GitHub, paid plan for thorough) and when to fall back to ask_pipeworx if unsigned-in. This clearly qualifies as explicit when/when-not/alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that results include full input schemas with curated examples and are ready to call directly, which aligns with and supplements the 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 well-structured with a clear purpose statement first, followed by usage guidance and output details. Every sentence serves a purpose, but it is slightly lengthy; however, it remains efficient and front-loaded.

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

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

Given the tool's role as a discovery mechanism, the description is comprehensive: it explains what it does, when to use it, what it returns, and includes examples in the schema. The absence of an output schema is compensated by describing the output format clearly.

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 explaining that the limit parameter controls the number of tools returned (top-N) and that query accepts aliases. This enhances understanding beyond the schema's property descriptions.

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

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

The description clearly states the tool's verb ('Find') and resource ('tools by describing the data or task'). It lists multiple domains (SEC filings, FDA drugs, etc.) and distinguishes itself from siblings like search_within or entity_profile by being a discovery tool for finding other tools.

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

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

The description explicitly guides the agent to call this tool first when many tools are available and the option set is needed. It provides specific contexts (browse, search, look up, discover) but does not list alternative tools or cases where it should not be used.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds valuable behavioral context: parallel fan-out across multiple sources, specific data returned (CIK, filings with URIs, fundamentals sorted), patent soft-fail date, and fallback mechanisms. No contradictions.

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

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

The description is dense and informative but lacks clear structure. It mixes example queries, usage guidance, data sources, return fields, and limitations in one run-on paragraph. While front-loaded with examples, the length could be trimmed and organized for better scanability.

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 thoroughly explains the return value: lists CIK, company name, recent filings (with URI format), fundamentals (sorted by period_end), patents (with sunset note), news via GDELT/GNews, and LEI. Limitations and fallbacks are also covered. Fully sufficient for an agent to understand the output.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds practical context: value can be ticker or zero-padded CIK, and explicitly states that names are not accepted. This adds meaningful nuance beyond the schema alone, justifying a score above baseline 3.

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

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

The description clearly states the tool creates a holistic cross-source profile of a US public company, with specific example queries. It explicitly distinguishes from sibling tools like resolve_entity and compare_entities, and advises preferring this tool over chaining individual lookups.

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

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

The description provides explicit when-to-use guidance with natural language triggers ('tell me about X', 'brief me on...'). It also gives a clear when-not-to-use condition: names are not supported, so use resolve_entity first. Additionally, it mentions the patents soft-fail behavior, setting expectations.

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 mentions deleting and clearing sensitive data, which aligns with the destructiveHint: true annotation. It adds context about the tool's effect beyond annotations, such as clearing stale or sensitive data, but the annotations already convey destructiveness.

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 core action, minimal waste. Every sentence adds value: action, when to use, pairing hints.

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 (1 param, no output schema, clear annotations), the description fully covers purpose, usage, and parameter. It is complete for effective selection and 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% with one parameter 'key' described as 'Memory key to delete'. The description adds no additional meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states 'Delete a previously stored memory by key', which specifies the verb and resource. It distinguishes itself from sibling tools like 'remember' and 'recall' by implying its opposite 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?

The description provides explicit when-to-use scenarios: stale context, task completion, or clearing sensitive data. It does not explicitly state when not to use it, but the positive guidance is strong and contrasts with sibling 'remember' and 'recall'.

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 read-only, idempotent, and non-destructive behavior. The description adds that it fetches the page, extracts content, and emits markdown, which goes beyond annotations. No contradictions.

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

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

The description is concise (two sentences plus use cases), front-loaded with the main action, and free of fluff. Every sentence adds value.

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

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

Given no output schema, the description explains the output format ('single text blob') and use cases. It could mention error handling or prerequisites, but for a simple tool with good annotations, it's nearly complete.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The description adds little new meaning beyond the schema, 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 generates an llms.txt file for any URL, with specific verb and resource. It distinguishes itself from siblings like 'scan_competitor_ai_presence' and 'ai_visibility_check' by focusing on llms.txt generation.

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 lists three explicit use cases (client indexing, personal project, competitor audit), providing clear context. It doesn't explicitly exclude alternatives, but the guidance is sufficient for typical usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds value by specifying default behavior (only active subscriptions) and the optional include_inactive parameter, plus return fields. No contradiction with annotations.

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

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

Two sentences, no fluff. First sentence states purpose and return fields; second provides usage guidance. 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 tool's simplicity (one optional boolean, no output schema), the description fully covers functionality, return fields, and use case. No gaps.

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

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

Schema coverage is 100% with one optional boolean parameter. The description mentions 'active' which relates to the parameter context but does not add explicit semantics beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates return fields (id, type, params, created_at, last_fired_at, fire_count), providing a specific verb and resource. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for use cases and implies when to use vs subscribe/unsubscribe, though it doesn't explicitly list when not to use.

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

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

Annotations are all false and provide no safety hints, so the description must carry behavioral disclosure and does so richly. It explains the claim_token return flow, rate limiting ('5 per identifier per day'), cost behavior ('doesn't count against your tool-call quota'), review cadence ('reads digests daily'), and content restrictions ('don't paste the end-user's prompt'). This goes far beyond the 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 longer than typical but each sentence serves a distinct purpose: purpose, triggers, exclusions, formatting rules, claim_token mechanics, and rate limits. It is front-loaded with the core action, and the density is justified by the tool's multiple behavioral nuances. Not perfectly tight, but no wasted words.

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

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

Despite having no output schema, the description fully covers the tool's lifecycle: how to file, what a claim_token is for, how to check status later, rate limits, scope boundaries, and content guidelines. An agent can confidently invoke this tool and handle subsequent retrieval without missing information.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by instructing users to describe issues in terms of Pipeworx tools/packs and explicitly warns against pasting end-user prompts, which the schema does not mention. It also clarifies claim_token usage synergistically with the schema, giving a modest lift.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete scenarios (bug, feature/data_gap, praise) and clearly distinguishes this from sibling tools like ask_pipeworx or discover_tools, which are about answering questions or finding tools, not reporting issues.

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 when-to-use guidance ('Use when a tool returns wrong/stale data (bug)...') and when-not-to-use guidance ('if the tool came from a different MCP server... file it with that server instead'). It also resolves ambiguity with 'Pipeworx tool names are the ones this connection lists,' providing a clear decision rule.

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. The description adds valuable behavioral details: self-aggregating signal derived from CF analytics, no PII, and caching behavior (5min-1h). No contradictions.

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

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

Five sentences with no wasted words. Front-loaded with purpose, followed by use cases and implementation details. 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 no output schema, the description explains what is returned (top tools, top packs, call volume). Caching, data source, and parameter behavior are all addressed. No gaps given the tool's simplicity.

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 100% of the single parameter with a description. The description adds context about window semantics ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which goes beyond the schema's enum listing.

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

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

The description clearly states that the tool returns 'top tools, top packs, and total call volume' over a configurable time window. The verb 'returns' and specific resource make the purpose unambiguous, distinguishing it from sibling tools like 'discover_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 enumerates three specific use cases (discovering hot data sources, confirming canonical tools, aligning use case) but does not explicitly contrast with alternatives. While context is strong, a direct 'when not to use' or sibling comparison would elevate 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?

Annotations indicate read-only, non-destructive behavior, which is consistent with the description. The description adds rich behavioral context: monotonicity violations, partition checks, fill check using live depth, and conditions for rejecting trades (thin legs, realizable edge ≤ 0).

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

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

The description is fairly long but well-organized, with a clear front-loading of purpose, followed by mode explanations, then technical details. Every sentence adds distinct value, though a minor reduction in verbosity could improve conciseness.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities array, partition_check details) and provides crucial usage context (fill check, similarity filter, placeholder filtering). It also references a related tool for custom sizing.

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

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

Schema descriptions cover 100% of parameters, but the tool description adds significant contextual value: explains the difference between event and topic modes, provides examples of valid inputs (e.g., 'fed-decision-may-2026'), and describes how each mode works internally.

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 finds arbitrage opportunities via specified techniques and distinguishes between three modes (no args, event, topic). It lacks explicit differentiation from sibling tools but is sufficiently 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?

Explicitly guides when to use each mode (no args for trending scan, event for specific markets, topic for cross-event scanning). Provides recommendation for event mode and warns when not to trade via fill check, with a pointer to an alternative tool for custom sizing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: caching (1h at KV level), model family details (crypto_price, news_momentum, etc.), edge computation (edge_pp_net, kelly_fraction), tradeable-edge knobs, and diagnostics ('callers can see WHY a segment is empty'). 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 it is well-structured with clear segments (model families, tradeable-edge knobs, response structure). It front-loads the core purpose. While it could be trimmed to improve conciseness, the level of detail is justified 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?

Given 9 parameters with 100% schema coverage, no output schema, and annotations present, the description comprehensively covers tool behavior: caching, model families, edge calculation, knobs, response structure (by_segment, diagnostics), and even explains why segments might be empty. It leaves no major gaps for an agent to infer.

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 each parameter already has a description in the schema. The tool description reiterates some parameter purposes (e.g., 'Tradeable-edge filter' for min_liquidity) but does not add significant new meaning 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 purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses specific verbs ('scan', 'return'), identifies the resource ('Polymarket markets'), and distinguishes itself from sibling tools like 'polymarket_arbitrage' by focusing on edge opportunities from Pipeworx 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 explicitly positions the tool for 'what should I bet on today' and notes that 'agents discover opportunities without paging hundreds of markets.' It explains the role of knobs (min_liquidity, max_spread_pp) but does not provide explicit when-not-to-use guidance or alternatives among siblings. Thus, clear context but lacking exclusions.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant value by detailing output structures (tracked[], expired[], snapshot_dates[]), explaining computed fields like trend and decay_pp_per_day, and disclosing limitations (60-day TTL, snapshot start date, daily closes not intraday).

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 relatively long but every sentence serves a purpose, from stating the core question to detailing output fields and limits. It is front-loaded with the purpose and clearly separated into sections. Minor improvement possible with bullet points for readability.

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

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

No output schema is provided, so the description fully compensates by explaining every return field (tracked with time-series, first_seen, trend; expired with lifespan_days; snapshot_dates). It also interprets the sign of edge_pp_net and notes the median lifespan as a competition clock, making the output actionable.

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 descriptions in the schema (100% coverage). The description adds context beyond the schema by clarifying defaults (days: 14, window: '1wk'), explaining window as a snapshot family, and linking parameters to the output structure. This enriches the agent's understanding.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it is shrinking. It uses specific verbs and resource references, and distinctly differentiates from sibling polymarket_edges by focusing on temporal analysis rather than raw edge 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 explains when to use the tool (to assess edge age and trend) and provides context with the example of fresh vs old wide edges. It does not explicitly list alternatives or when not to use, but the purpose implicitly guides 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds rich behavioral context: it walks the order book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, etc. For basket mode, it explains per-leg fill details, thin_legs detection, and forced directional risk. It also explains the dominant loss mode. No contradictions with annotations.

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

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

The description is long but well-structured: first sentence gives overall purpose, then REQUIRES line, followed by clear sections for SINGLE-MARKET and BASKET. The closing paragraph ties to usage guidelines. Every sentence is informative. However, it could be slightly more concise; some details about return fields could be abbreviated while still being clear. Still, very good for a complex tool.

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 thoroughly explains return values for both modes, including verdict values (clean|degraded|cannot_fill), per-leg fill detail, thin_legs, forced_directional_risk, and max_clean_notional_usd. It covers edge cases like partial basket fills and thin books. For a 4-parameter tool with no output schema, this is exceptionally 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%, but the description adds significant semantic value beyond the schema. It explains that `side` defaults based on partition sum in basket mode, `size_usd` has different interpretations for single-market vs basket (max spend vs target proceeds vs settlement notional), and specifies clamp range 10–1,000,000. This level of detail goes well beyond what the schema provides.

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

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

The description starts with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes between single-market and basket modes, and the closing sentence explicitly differentiates it from siblings like `polymarket_arbitrage` and `polymarket_edges` by stating when to use this tool. This makes the purpose very clear.

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 says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It warns about theoretical overround not being capturable on thin books and partial basket fills converting an arb into a directional position. While it does not explicitly list when not to use, the ~$500 threshold and the clear use case provide strong guidelines. A 5 would require explicit exclusions for all alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds extensive behavioral detail: modes, response structure, compatibility_warning conditions, temporal_alignment, and skipped cross types. 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 verbose but well-structured with clear sections. Every sentence adds value, though it could be slightly more concise without losing critical information.

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

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

Given the tool's complexity (two modes, multiple safety fields, no output schema), the description covers all necessary context: return values, compatibility warnings, temporal alignment, and practical caveats about tradeability.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds meaning by explaining parameter interaction (topic vs explicit, overriding) and provides examples, compensating well beyond the schema.

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

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

The description states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' specifying a unique verb-resource pair. It clearly distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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 and explicit) and warns that most macro shortcuts trigger compatibility_warnings. However, it does not explicitly compare with sibling tools 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=true, no contradiction. Description adds: lists all keys when omitted, scoped to identifier, pairs with remember/forget. No missing key behaviors.

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 core functionality, zero waste. Every sentence adds value.

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

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

Fully describes both retrieval modes, scoping, and sibling relationships. No output schema needed; rich annotations cover safety. Complete for a simple 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 100% with description for 'key'. Description says 'omit the key argument' which reinforces but does not add new meaning beyond schema.

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

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

States specific verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys'. Distinguishes from siblings 'remember' and 'forget'.

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

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

Explicitly tells when to use: 'look up context... without re-deriving it from scratch'. Mentions scoping and pairing with remember/forget as alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true. Description adds behavior of mark_read parameter (flags events read, affecting subsequent calls) and response structure, which goes beyond annotations. No contradictions.

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

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

Concise three sentences: first states core purpose, second details returned fields and parameter use, third adds polling suitability and alternative endpoint. No wasted words.

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

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

Despite lacking output schema, description explains return structure (source, citation_uri, raw payload), covers all five parameters with usage context, and provides alternative access method, making it complete 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 has 100% parameter descriptions. Description adds value by explaining mark_read's effect on read-state management and clarifying that returned events include source, citation_uri, and raw payload, which informs parameter usage.

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

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

Clearly states it pulls fired events from subscription feed, specifies returned fields (source, citation_uri, raw payload), and distinguishes itself from sibling tools like 'list_subscriptions' by focusing on recent alerts with read-state management.

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 context for polling ('Polls work fine') and mentions an alternative GET endpoint for scripts/dashboards. Implicitly suggests use for programmatic access with read-tracking, though lacks explicit when-not-to-use guidance.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive context: fans out to SEC, GDELT/GNews, USPTO; explains fallback logic; soft-fail for USPTO; rate-limiting handling. 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 well-organized: starts with example queries, then explains behavior, parameter details, and ends with sibling comparison. Every sentence adds value. Could be slightly more structured with bullet points, but still concise.

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 explains the return structure (changes[] grouped by source, total_changes count, citation URIs). It covers all relevant aspects: sources, fallbacks, error handling, parameter options, and when to use sibling tool.

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

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

Schema description coverage is 100% with clear descriptions for 'type', 'since', 'value'. The description adds further value by providing examples of 'since' values (ISO date, relative shorthand) and typical usage ('30d' or '1m'). It also clarifies that 'value' accepts ticker or CIK.

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

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

The description clearly states it is a change feed for a company, listing example queries like 'What's new with X' and 'latest on Y'. It distinguishes itself from the sibling tool 'entity_profile' by specifying when to use each.

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

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

The description explicitly tells when to use this tool (for recent changes) and when not to use it (use entity_profile for static profile). It also explains fallback behavior (GDELT to GNews) and window options.

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 idempotentHint=true and destructiveHint=false. The description adds valuable context: key-value store, scoped by identifier, persistence differences (authenticated vs anonymous, 24-hour TTL for anonymous). This goes beyond annotations without contradicting them.

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

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

Four sentences, each earning its place. Front-loaded with purpose, then usage, then storage semantics, then related tools. No wasted words; highly effective.

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 key-value storage tool with two parameters and no output schema, the description fully covers all aspects: purpose, when to use, storage behavior, lifetime, and relationship to siblings. No gaps remain.

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

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

Schema provides 100% coverage for both key and value descriptions. The description adds semantic guidance on key naming conventions (e.g., 'subject_property') and value types ('findings, addresses, preferences, notes'), enhancing the agent's understanding of parameter usage.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and provides concrete examples (resolved ticker, target address, user preference). It distinguishes from sibling tools recall and forget by naming them.

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

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

Explicitly states when to use ('Use when you discover something worth carrying forward') and mentions complementary tools (recall, forget). Provides context for both authenticated and anonymous sessions, leaving no ambiguity about 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses specific return fields (ticker, CIK, company_name, RxCUI, ingredient, brand), data sources (SEC EDGAR, RxNorm), citation URIs, auto-disambiguation behavior, and the internal cascading of multiple endpoints. This is rich behavioral detail that the annotations alone do not 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 appropriately front-loaded with example phrases and structured by SUPPORTED TYPES. While it is a bit long, every sentence carries useful guidance, and the internal cascade note justifies the extra length. Minor redundancy (e.g., 'replaces 2-3 manual lookups' could be implied) keeps it from a perfect 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?

With no output schema, the description compensates by detailing exactly what is returned for each entity type, including citation URIs. It also covers both the company and drug cases, the input variations, and the internal logic, making the tool fully self-explanatory for an agent.

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?

Even though the input schema covers both parameters with descriptions, the tool description adds significant meaning: it gives concrete examples (AAPL, 0000320193, 'ozempic'), explains that company accepts ticker, CIK, or name with auto-disambiguation, and clarifies drug input as brand or generic name. This goes well beyond the schema's baseline.

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

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

The description uses a specific verb ('resolve') and resource (names to canonical identifiers), provides concrete example queries ('What's the ticker for…', 'find the CIK for…'), and clearly distinguishes itself as the prerequisite lookup for other tools. It covers both supported types, making it unambiguous 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?

It explicitly states 'Use FIRST whenever you have a name but need an ID,' which is a clear when-to-use directive. The description also explains that the tool replaces 2-3 manual lookups, and the reference to 'other tools' implies the alternative is using raw lookups instead. This gives strong contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint as false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. This goes beyond annotations, but could be more explicit about intermediate calls or potential side effects (none expected). 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 two main sentences plus a parenthetical example. It is front-loaded with the primary action, then provides a concrete use-case example. No redundant or extraneous text; every sentence serves a clear 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?

Given the tool complexity (multi-entity comparison, no output schema), the description adequately explains the process (probes each entity, ranks, returns metrics). It covers what the tool does, how it works, and what is returned. However, it could specify entity count limits (already in schema) or potential rate limits. Overall sufficient for an AI agent to understand and invoke 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% (all four parameters have descriptions). The description adds value by explicitly stating that the first entity is treated as the 'subject' for narrative, which is not in the schema. This enhances understanding of parameter semantics beyond the schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. It uses specific verbs like 'compare', 'probes', 'ranks', and 'surfaces', and distinguishes from the sibling ai_visibility_check by being a multi-entity comparison. The example question solidifies its 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 explicitly mentions 'useful for competitive AI-marketing audits' and gives a concrete example question. It implies usage for comparing multiple entities, which distinguishes it from single-entity tools like ai_visibility_check. However, it does not explicitly state when not to use it or list alternative tools, but the context is clear enough for an AI 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?

The description adds significant behavioral context beyond annotations, including composite fan-out, partial failure handling, and bundlephobia latency (5-30s on first measurement). It also mentions that sources_failed will list timeouts, which is critical for agent behavior understanding.

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 usage, then provides output details and limitations. While slightly verbose, every sentence adds value. A minor conciseness improvement could tighten the output summary, but overall it's 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?

Given the tool's complexity (composite check, multiple data sources, partial failures) and absence of an output schema, the description is remarkably complete. It covers what the tool returns (summary fields, advisories, alternatives) and how it handles errors, enabling correct agent behavior.

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

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

Schema coverage is 100% with both parameters described. The description adds minimal additional value: it confirms scoped package acceptance and default version behavior, but these are already implied by the schema descriptions. 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 composite check for npm packages using deps.dev and bundlephobia, with a specific verb ('scan') and resource ('dependency'). It distinguishes from sibling tools by focusing on npm package analysis, which is unique among the listed 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 explicitly advises when to use the tool: when an agent asks about npm package safety, popularity, or size. It also specifies the scope (NPM only) and directs users to deps.dev:version for other ecosystems, providing clear when-not-to-use guidance.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral context: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars), truncation with flag, and output includes offsets and similarity scores. 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?

The description is concise, single paragraph, front-loaded with the main action, then use case, then technical details. Every sentence adds value with no redundancy.

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

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

Given the tool's complexity (semantic search, chunking, embedding model), the description covers all essential aspects: when to use, how it works, technical limits, and output format. No output schema exists, but the description explains what is returned (passages, offsets, similarity scores). Context is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: for 'text' it specifies the max length ('max ~200K chars'), for 'query' it provides example queries, and for 'limit' it gives default (5) and range (1-20). This adds helpful context.

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

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

The description clearly states it performs 'Semantic search INSIDE a fetched record.' It gives concrete examples (SEC 10-K, article) and distinguishes from sibling tools like ask_pipeworx_grounded, indicating it is for searching within a single record, not for broader tasks.

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 says when to use this tool: 'Use when the record is too big to cram into the prompt.' It also mentions a companion tool (ask_pipeworx_grounded) for grounding over passages. However, it does not explicitly state when not to use it, though the guidance is clear enough.

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 provide readOnly=false, destructive=false, openWorld, idempotent. Description adds value by detailing authorization requirement, type-specific behaviors, delivery channel constraints, and return value. Does not directly address idempotency behavior.

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

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

Well-structured with purpose, prerequisites, types, delivery channels. Every sentence adds value, but could be slightly more concise without losing information.

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

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

Covers prerequisites, parameters, delivery options, limitations. No output schema, but description mentions returns subscription id and webhook secret. Minor omission: response format details.

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?

Parameter schema coverage is 100%, and description adds substantial context: detailed examples for each subscription type, constraints on delivery fields (SMS verification, 10/day cap, webhook signing and auto-disable). Adds meaning far beyond the schema descriptions.

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

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

Clearly states it creates a proactive monitoring subscription and returns the subscription id. Distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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 extensive usage guidance: requires Pipeworx OAuth account, lists supported types with examples, explains delivery channels and limitations. Lacks explicit 'when not to use' or direct comparison to alternative tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about being an onboarding entry point, returning example questions with exact tool shapes, and being drawn from a live catalog. It provides extra behavioral context 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 relatively long but every part adds value, front-loading common queries and structuring information with parentheses. It could be slightly more concise, but it is well-organized and informative.

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

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

No output schema exists, but the description compensates by detailing the output format (category-bucketed example questions with tool+argument shape). It covers optional parameter, use cases, and mentions alternatives, making it fully complete for the tool's purpose.

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

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

Schema has 1 parameter with description; the description elaborates with concrete possible values (finance, pharma, etc.) and explains the effect of omitting or providing the topic. Adds value 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's purpose: returns category-bucketed example questions to help an agent understand Pipeworx's capabilities. It distinguishes itself from siblings like ask_pipeworx by being the onboarding entry point, using specific verbs and a clear resource description.

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: 'Use this FIRST when you do not yet know what Pipeworx can do.' It also explains when to pass a topic vs. no arguments, and mentions alternatives like ask_pipeworx and entity_profile.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds value by explaining the sub-scores scale (0=best, higher=worse) and listing returned fields, but no additional behavioral traits beyond annotations.

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

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

The description is a single sentence with an example, front-loading key information. 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 no output schema, the description compensates by detailing what is returned (rating, inspection date, sub-scores, address, local authority, geocode). This is sufficient for a retrieval tool with a single parameter and clear annotations.

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

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

Only one parameter (fhrsid) with schema coverage 100%. Schema already provides a description; description adds an example and context (from search), which is helpful but not essential. 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 it gets the full FHRS inspection record for one establishment by FHRSID, with specific details (rating, inspection date, sub-scores). It distinguishes from the sibling search tool by explicitly referencing uk_food_hygiene_search.

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

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

Description indicates the tool is for retrieving details after a search (by FHRSID from uk_food_hygiene_search) and provides an example. It doesn't explicitly state when not to use, but the context is clear enough for a single-purpose 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 adds significant context beyond annotations: explains Scotland uses FHIS with different ratings ('Pass'/'Improvement Required'), that min_rating drops Scottish results, and what is returned (rating, date, address, sub-scores). No contradiction with annotations (readOnly, openWorld, idempotent).

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 efficient and front-loaded with purpose. It is slightly lengthy due to examples and details, but every sentence adds value. Could be more concise, but structure is clear.

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

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

Given 8 parameters, no output schema, and no enums, the description is very complete. It explains return contents, geographic differences, filter implications, and provides examples. It adequately compensates for missing 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?

Schema covers all 8 parameters (100% coverage), baseline 3. Description adds value with context: explains address can be town/street/postcode, min_rating range and effect on Scottish results, radius defaults and limits, and provides usage examples. This goes beyond schema.

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

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

The description clearly states it searches UK restaurant food hygiene ratings from FHRS, provides specific examples, and distinguishes from sibling tools (e.g., uk_food_hygiene_details). It includes verb 'Search' and specifies resources and what it answers.

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 clear context on when to use: for finding hygiene ratings by name/address or geo. It includes examples and filter options. However, it does not explicitly state when not to use it or mention alternatives beyond implied sibling.

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?

Discloses that the row is deactivated (not deleted) and historical events remain accessible via recent_alerts. Annotations already indicate non-destructive and idempotent behavior; description adds valuable context beyond annotations.

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

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

Two sentences with zero waste. Front-loaded with primary action, second sentence adds critical behavioral detail. Highly efficient.

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

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

Given the tool's simplicity (1 parameter, no output schema), the description fully covers purpose, ownership, side effects, and linkage to recent_alerts. No gaps remain.

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

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

Schema coverage is 100% and describes id as 'uuid returned by subscribe.' Description does not add new parameter details beyond what schema provides; 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource. Differentiates from siblings subscribe and list_subscriptions by emphasizing ownership enforcement.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context. Does not explicitly list when not to use or alternatives, but the constraint is well-defined.

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 behavior. The description adds significant value by detailing the two verification paths, the output verdict options (confirmed, approximately_correct, refuted, etc.), the inclusion of grounded or structured actual value with citation, and reasoning. 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?

Description is a single paragraph, but every sentence is meaningful. The first sentence effectively front-loads the purpose with trigger phrases like 'Is it true that…', 'fact check', etc. It could be slightly more structured (e.g., bullets), but is appropriately sized for the information it conveys.

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 (multiple verification paths, output structure), the description is comprehensive. It explains the two pathways, the verdict options, and the citation format. No output schema, so the description must cover return values, and it does so adequately, making the tool self-contained.

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

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

Schema coverage is 100% with both parameters already described. The description adds examples for 'claim' and explains the override behavior for 'tolerance_pct' (implied by wording, capped at 5). This adds moderate context beyond the schema, but the baseline is 3 due to high schema coverage.

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

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

Description uses specific verbs like 'validate', 'verify', 'confirm or refute' and clearly identifies the resource as natural-language claim verification against authoritative sources. It distinguishes the tool from siblings by mentioning it replaces 4-6 sequential calls and has a fast path for company financial claims.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It describes two pathways (SEC EDGAR + XBRL for company claims, grounded pipeline for others), giving clear context for when to use. No negative guidance or alternatives, but adequate for agent decision.

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