Denue

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds value by specifying the default model is free and the cost implications of using Anthropic (BYO key, direct payment). It also reveals the return structure: per-model {score, confidence, signals, raw_response} + combined view. 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 concise, consisting of three sentences that front-load the purpose. Every sentence adds unique value: first sentence explains what it does and default behavior, second sentence covers optional Anthropic integration and cost, third sentence lists use cases and return format. 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 listing return fields (score, confidence, signals, raw_response, combined view). The input schema is fully described with 100% coverage. The tool's complexity is moderate with 4 parameters (1 required), and the description addresses all key aspects: default model, optional models, API key usage, disambiguation context, and practical applications.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant meaning: explains that '_apiKey' is only needed if 'anthropic' is in models and that it is passed straight through to api.anthropic.com. It also clarifies that 'context' helps disambiguate common names. These details go beyond the schema descriptions.

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

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

The description clearly states the tool 'probes LLMs for what they know about a business/brand/product/topic and scores visibility (0-100) per model'. It uses specific verbs (probe, score) and resources (LLMs, entity). It distinguishes from siblings by focusing on multi-model visibility scoring, unlike sibling tools like 'ask_pipeworx' which are single-query 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 lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It explains default model (Workers AI Llama-3.3-70b free) and when to provide an API key for Anthropic. However, it does not explicitly state when not to use or compare to similar siblings like 'compare_entities' or 'scan_competitor_ai_presence'.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior context: it routes to other tools, returns stable pipeworx:// citation URIs, works on every tier, and is one fast call. It also clarifies that it handles breaking news via live news sources. This goes beyond annotations and gives insight into what the agent should expect.

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

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

The description is longer than average but front-loaded with the critical 'PREFER OVER WEB SEARCH' directive. It is structured logically: core purpose, examples, usage guidance, and alternatives. Each sentence adds value, but some repetition exists (e.g., the list of domains is long and could be trimmed). Overall, it earns its place without being bloated.

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

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

The description is comprehensive for a general-purpose question router. It covers the tool's scope, return format (structured answer with citations), performance characteristics ('one fast call'), tier availability, and clear escalation paths to more specialized siblings. It also provides a wide range of examples to set expectations. Despite having no output schema, the description sufficiently explains what the tool returns and when to use it.

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

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

Schema description coverage is 100% — the 'question' parameter is well-documented, and all other parameters are aliases for it. The description reiterates that the input is a natural language question and provides examples, but does not add any additional syntax or formatting details beyond the schema. Since the schema already does the heavy lifting, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's core function: routing factual questions to the appropriate one of 5,529 tools across 1,455 sources and returning a structured answer with citations. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and explicitly lists diverse domains. It also distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research, making its purpose 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 is explicit about when to use this tool: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It provides clear alternatives with conditions: use ask_pipeworx_grounded for hallucination-resistant single answers with evidence, and deep_research for broad/multi-part questions. It also gives example queries and notes it works on every tier. This is exemplary usage guidance.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description discloses that candidate routing improvements are 'enabled live whenever one is under test', that no candidate is currently active, and that results are compared against the stable router. This adds critical behavioral context about the tool's variable routing behavior and current equivalence to ask_pipeworx.

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 beta identity and purpose, each sentence carries meaningful information (identity, current state, usage, reassurances). The inclusion of a specific retirement date (2026-07-26) is slightly over-specific but not redundant.

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

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

For a tool with no output schema and complex routing behavior, the description fully covers what it does, when to use it, current behavior, and its relationship to the stable version. It is complete enough for an agent to invoke it correctly and understand the experimental context.

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

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

Schema description coverage is 100% with all parameters as aliases for 'question', already well-documented. The tool description adds no extra parameter detail beyond 'same arguments' as ask_pipeworx, so it does not elevate beyond the 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 explicitly states 'Beta version of ask_pipeworx: identical universal router (same 5,529 tools, same arguments, same response shape)' and clarifies 'this IS a full working router'. This gives a specific verb+resource (universal router) and clearly distinguishes it from the sibling ask_pipeworx by highlighting the beta/experimental nature.

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

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

It provides direct guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies 'Falls back to nothing — this IS a full working router'. While it doesn't explicitly say 'use the stable ask_pipeworx for production', the 'experimental edge' and comparison-to-stable implications are 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the internal mechanism (extracts answer only from tool result), the exact return shape with refusal reasons, and the additional LLM cost. This is rich behavioral context that fully informs the agent of the tool's constraints and failure modes.

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

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

The description is approximately 130 words but every sentence contributes: behavior, return format, refusal types, use cases, and cost trade-off. It is front-loaded with the most important distinction ('hallucination-resistant') and avoids irrelevant details. Structure is logical and compact.

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

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

Despite having no output schema, the description fully compensates by detailing the return structure and all refusal reasons. It also provides context on the routing scope (5,529 tools, 1455 sources) and cautions about the extra LLM call. For a complex tool with a single question parameter, this 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 description coverage is 100%, with all six parameters documented as aliases for the natural language question. The description doesn't add parameter syntax details, but the schema already handles this fully. Baseline 3 is appropriate because the description's context about routing and tool selection does not specifically enhance the parameter understanding.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' which clearly identifies the tool's unique value proposition. It explicitly contrasts with the sibling ask_pipeworx by describing the same routing but with additional grounded extraction behavior, effectively distinguishing between the two.

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 ('whenever an answer will be quoted, cited, or acted on') and when to prefer an alternative ('prefer ask_pipeworx for casual lookups'). It also mentions the cost trade-off of an extra LLM call, giving the agent clear decision criteria.

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 extensively discloses behavioral traits beyond annotations: resolution confidence handling, parent event extraction, news fallback behavior, safety short-circuits for low-confidence matches, closed market handling, wide spread warnings, and cancellation rule parsing. No contradictions with annotations (readOnlyHint, openWorldHint, etc.).

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

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

The description is effective but not concise. It spans multiple paragraphs with dense information, which is necessary for the tool's complexity, but could be better structured or front-loaded with the most critical usage instructions.

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 (classifiers, fan-outs, response shapes, error cases) and lack of output schema, the description is comprehensive. It covers market match confidence, parent events, news fallback, safety, closed markets, wide spreads, and cancellation rules, ensuring the agent can appropriately handle all scenarios.

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

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

The input schema has 100% coverage with parameter descriptions. The description adds value by explaining the depth parameter's effect on evidence count, the include_raw parameter's impact on response size, and clarifying that market accepts slug, URL, or question text. It enriches understanding without being redundant.

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). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by being a one-call comprehensive research tool.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides detailed examples of fan-outs for different bet types, offering clear guidance on appropriate usage contexts.

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 readOnlyHint, openWorldHint, idempotentHint. Description adds specifics: data sources (SEC EDGAR/XBRL, FAERS), fiscal year handling, sorting by primary metric, citation URIs. 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?

Description is front-loaded with common phrases and usage patterns. Each sentence adds value, though it is somewhat long. Well-structured with clear sections for triggers, usage, and return details.

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

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

Despite no output schema, description adequately covers return format (paired data + citation URIs), sorting behavior, and data sources for both entity types. Meets the needs for a comparison tool with clear 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 has 100% coverage with basic descriptions. Description adds significant context: what data is pulled for each type (revenue, adverse events, etc.) and how sorting works. This goes 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?

Description clearly states the tool does side-by-side comparison of 2–5 companies or drugs in one parallel call, with explicit verbs and phrases like 'Compare X and Y', 'rank these companies', 'head to head'. It distinguishes from sequential lookups and sibling tools like entity_profile.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides natural language triggers and examples, giving clear 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description adds substantial behavioral context beyond these: the account/payment prerequisite, the parallel decomposition into facets, the return packet format (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), explicit gaps[] for unanswered facets, contradictions[] for standard/thorough, semantic excerpting, timing (15-90s), and the guarantee that findings are 'never invented'. 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 (~250 words) but every sentence earns its place, covering prerequisites, tool behavior, alternatives, return format, and performance. It is well-structured (starts with the account warning, then capability, then guidance, then returns). It is not a model of brevity, but the density of useful information justifies the length 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?

With only 2 params, no output schema, and basic annotations, the description fully compensates: it explains the findings packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), iteration semantics for depth values, the account/tier requirement, and expected latency. This is a complete operational picture for an AI agent deciding whether and how to invoke the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter-related insight beyond the schema: depth:'thorough' requires a paid plan, 'standard' is the default, and expected latency (15-60s, thorough up to ~90s) helps choose depth. It also reinforces that the question can be broad/multi-part, but the schema already covers this, so the incremental value is moderate.

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 with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that 'decomposes your question into focused facets, routes each to the right one of 5,529 tools IN PARALLEL, and returns a findings packet.' It also distinguishes itself from siblings by explicitly noting 'this is NOT open-web search' and positioning itself against ask_pipeworx.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: 'Best for broad/multi-part questions', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also explains depth tiers and iteration behavior, making selection straightforward.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds value by clarifying that only totals are returned and no detail records, which is a behavioral trait beyond the annotations. No contradictions exist.

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

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

The description is two sentences: one for function and one for usage example. No filler, front-loaded with the core purpose. 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?

For a counting tool with no output schema, the description adequately explains the result type (totals) and provides a concrete use case. It could be more complete by hinting at the return format, but given the tool's simplicity and the sibling context, it is largely sufficient.

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

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

The input schema already provides detailed descriptions for all three parameters (100% coverage). The description groups them into 'economic activity + geography + size stratum' but does not add new parameter-level details 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 the tool counts establishments by three dimensions (economic activity, geography, size stratum) and distinguishes from siblings by noting it returns totals, not detail records. The sibling tools include other denue tools that likely provide detail records or search by name, so this tool's purpose is well-differentiated.

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 an explicit use case ('how many pharmacies are in Jalisco') and implies market-sizing questions. However, it does not explicitly state when to avoid this tool or mention alternatives by name, missing some guidance on 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=true, idempotentHint=true, destructiveHint=false, which fully cover behavioral traits. The description adds no new behavioral context beyond clarifying the input source, so it meets the baseline for annotation-supported tools.

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

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

Single sentence that immediately states purpose and input, with no unnecessary words. Perfectly front-loaded for an AI agent.

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

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

Tool is simple with one parameter and no output schema. The description adequately explains the input source and action, providing complete context for a single-entity lookup tool.

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

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

Schema coverage is 100% with the 'id' parameter described in the schema. The description adds context that the ID comes from search results, providing helpful usage guidance beyond the raw schema.

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

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

Description clearly states verb ('Get'), resource ('full details for a single establishment'), and method ('by DENUE ID'). It distinguishes from sibling search tools by specifying the input as the 'Id' field from search results.

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 instructs to use the 'Id' field from search results, providing clear context for when this tool is appropriate (when you have a specific ID). While it doesn't explicitly state when not to use alternatives, the sibling names imply search tools for finding IDs and this tool for details.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about pagination behavior and geographic scope (Mexico or single state). It does not mention rate limits, error handling, or return format, but the annotations lighten the burden.

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

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

Two sentences with no fluff. The first sentence front-loads the core purpose. Every word earns its place. Perfectly 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?

The description covers the search scope and pagination but lacks details on output format, error cases, or limitations (e.g., max results). With no output schema, some additional context about return structure would improve completeness, but the annotations partially compensate.

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 baseline is 3. The description mentions page_size incorrectly (schema uses page_end) and adds no new meaning beyond what the schema already provides for each parameter. It does confirm pagination context but adds little value.

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

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

The description clearly states the verb 'search', resource 'businesses', and scope 'by name or brand across Mexico or a single state'. It differentiates from siblings like denue_search_in_state by focusing on name-based search, but could be more explicit about when not to use it.

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 pagination guidance ('set page_size and page_start to walk results') but lacks explicit when-to-use or when-not-to-use instructions relative to sibling tools. The pagination advice is helpful but not comprehensive.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world behaviors. The description adds that results are paginated, which is useful additional 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 well-structured sentences: first defines purpose and matching criteria, second provides usage guidance and pagination note. No unnecessary words.

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

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

Given the tool's simplicity, good annotations, and complete schema, the description sufficiently covers all necessary information: purpose, scope, matching, and pagination.

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 includes detailed parameter descriptions. The description essentially reiterates the matching scope and provides examples, but adds minimal new semantic meaning beyond the schema.

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

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

The description clearly states the tool searches businesses in a single Mexican state by keyword, matching against name, activity, or address. This distinguishes it from sibling tools like denue_search_by_name which likely does nationwide search.

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

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

The description advises using this tool for state-scoped queries that need more than just business name, with examples. It implicitly contrasts with nationwide searches, and the schema explicitly mentions denue_search_by_name for nationwide, providing clear context.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds the specific behavioral constraint 'max 5000m' radius, which is useful. 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 two sentences long, front-loaded with the main purpose, and contains no extraneous information. Every word contributes to clarity.

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 does not explain the return format (e.g., list of establishments with fields). For a simple spatial search, this is acceptable but could be improved by noting typical response structure.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reiterates the keyword and radius purpose but does not add new semantic information beyond what the parameter descriptions already provide.

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 'Find businesses near a coordinate' and specifies the action (returns matching establishments within a radius). This distinguishes it from siblings like denue_search_by_name and denue_search_in_state, which target different search criteria.

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

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

The description implies usage for spatial proximity searches with a keyword and radius. However, it does not explicitly state when not to use this tool or mention alternatives, which would enhance 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=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns top-N tools with full input schemas and curated examples, ready to call directly without a second lookup. This goes beyond the annotations by explaining the output structure and convenience.

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 primary purpose and usage guidance. It lists domains and explains the return format without unnecessary repetition. While slightly long, every sentence adds value, and it remains focused.

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

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

Despite no output schema, the description fully explains the return format: tools with names, descriptions, and full input schemas with examples. It also covers parameter aliases and usage context. Given the tool's simplicity (6 params, mostly aliases), the description is complete and leaves no ambiguity.

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

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

Schema description coverage is 100% (all 6 parameters documented). The description adds examples ('analyze housing market trends') and mentions that multiple aliases (task, q, description, search) are accepted, which is already in the schema. The added value is marginal, so a 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 explicitly states 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and lists numerous domain examples that distinguish it from generic search tools. It clearly differentiates itself from sibling tools like 'search_within' or 'deep_research' which search data, not 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 advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (when a specific answer is needed). It does not explicitly name sibling alternatives, but the guidance is strong enough to allow proper selection.

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

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

Annotations already indicate safe read-only tool. Description adds beyond: details sources (SEC, XBRL, USPTO, etc.), return fields, and limitations (patents soft-fail). 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?

Description is thorough but front-loaded with examples. Every sentence adds value; structure is logical (purpose, usage, sources, return fields). Slightly verbose but well-organized.

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 complexity and no output schema, description covers what tool returns (cik, filings, fundamentals, patents, news, LEI) and caveats. Could detail formats but is adequate for 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 good descriptions. Description reinforces constraints (type only company, value ticker/CIK) and clarifies that names not supported, adding useful context 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 specifies verb+resource ('full cross-source profile of a US public company') and distinguishes from siblings by stating 'ALWAYS PREFER over chaining single-pack...lookups'. Example queries clarify intent.

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

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

Explicitly states when to use (holistic view) and when not (names not supported), directing to resolve_entity first. Lacks explicit exclusions for single-data-point queries but covers key context.

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

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

Annotations already indicate destructive and idempotent behavior. The description adds context on why deletion occurs (stale, done, sensitive) and does not contradict 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?

Extremely concise: three short sentences covering purpose, usage, and pairing. Every sentence adds value, 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 simplicity of the tool (one parameter, no output schema), the description fully covers purpose, usage context, and relationships to sibling tools.

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

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

Parameter schema has 100% coverage with description 'Memory key to delete'. The description does not add additional semantic information beyond the schema.

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

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

The description clearly states the verb 'delete' and the resource 'memory by key'. It distinguishes from siblings 'remember' and 'recall' by specifying the action of deletion.

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

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

Provides explicit when-to-use scenarios (stale context, task done, clear sensitive data) and suggests pairing with siblings. However, does not list exclusions or alternatives beyond mentions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context: it fetches the page, extracts title/description/key links, emits standard markdown, and outputs a single text blob. 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?

Three sentences, each earning its place: first for purpose, second for process, third for use cases. No redundancy, front-loaded with core action.

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 low complexity (2 params, no output schema), the description fully covers purpose, process, output format, and usage context. Annotations provide safety guarantees. No gaps exist for a simple generation tool.

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

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

Schema coverage is 100%, with both 'url' and 'max_links' having descriptions. The description does not add new parameter details beyond what the schema provides (e.g., default/max for max_links). Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, using specific verbs ('generate', 'fetches', 'extracts', 'emits'). It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on a specific output format and use case.

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

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

The description provides explicit use cases (client site indexing, personal projects, competitor auditing) but does not include exclusions or when not to use the tool, leaving a slight gap for the agent to infer alternatives from sibling names.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by listing the specific return fields (id, type, params, created_at, last_fired_at, fire_count), providing additional behavioral context beyond what annotations offer.

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

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

The description is two sentences: the first states the action and return fields, the second gives usage guidance. No wasted words; every sentence serves a purpose. It is front-loaded with the core function.

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 parameter, no output schema, strong annotations), the description is complete. It covers what the tool does, what it returns, and when to use it. No further details are necessary.

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 (include_inactive) fully described in the schema. The description does not mention this parameter, so it adds no additional parameter meaning beyond the schema. Baseline score of 3 applies because the schema already documents the parameter adequately.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It lists the returned fields (id, type, params, etc.), making its purpose unambiguous. This distinguishes it from sibling tools like subscribe and unsubscribe, which perform mutations.

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: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implicitly suggests alternatives (subscribe, unsubscribe) for other actions.

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

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

While annotations are all false, the description adds substantial behavioral context: rate limit (5 per identifier per day), free/quota-free, claim_token mechanics, daily digest processing, and the instruction to not paste user prompts. This goes well beyond the annotations and gives the agent a clear picture of side effects and constraints. No contradiction with annotations.

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

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

The description is front-loaded with purpose and usage, and every sentence serves a distinct function: usage criteria, exclusion, identification, message guidance, claim_token, roadmap impact, rate limit, and cost. It is appropriately sized for a tool with nuanced routing and token behavior.

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

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

Given the lack of an output schema, the description adequately explains what to expect (a claim_token, future status updates), covers all required behavioral guidance, and provides sufficient context for correct invocation. The tool is simple in purpose, and nothing essential is missing.

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

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

Schema covers 100% of parameters with detailed descriptions, including the enum, nested context object, and claim_token usage. The description adds minimal extra parameter meaning—it restates claim_token behavior already in the schema, but does not provide new semantics. Baseline 3 is appropriate given 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 uses a specific verb ('tell') and resource ('Pipeworx team'), and clearly enumerates what the tool does: report bugs, features, data gaps, or praise. It distinguishes itself from siblings like ask_pipeworx by focusing on feedback about the tools themselves, not asking questions or doing research.

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 criteria (wrong/stale data, missing tool, praise) and an explicit when-not-to-use (tools from a different MCP server) with a named alternative ('file it with that server instead'). Also clarifies how to identify Pipeworx tools, making the usage guidance unambiguous.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, and caching durations per window. This goes beyond 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?

Two sentences plus a bulleted use-case list. Front-loaded with the core result. Every sentence adds value without redundancy or fluff.

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

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

Given only one parameter, rich annotations, and no output schema, the description sufficiently covers what, when, and why. It mentions caching and data source. Minor gap: no description of the output format, but acceptable for a simple trending 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?

The sole parameter 'window' has 100% schema coverage with enum values and descriptions. The description further clarifies that shorter windows surface hot trends while longer windows show steady-state demand, adding semantic 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 clearly states the tool returns 'top tools, top packs, and total call volume' over selectable windows. The verb 'returns' and resource 'trending data' are specific and distinct from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Three explicit use cases are provided (e.g., 'discovering what data sources are hot for current events'). The description also notes caching behavior and window selection guidance. However, no explicit mention of when not to use this tool or direct comparison with alternatives.

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

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

Annotations already declare non-destructive, idempotent, read-only behavior. The description adds rich behavioral context: monotonicity checks, partition_sum logic, placeholder filtering, semantic anchor for similarity, and fill check against live order book depth.

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 thorough but somewhat lengthy. However, it is well-organized into logical paragraphs, with clear labeling of modes and edge cases. Every sentence adds value, though a minor reduction in detail 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?

Given the tool's complexity (multiple modes, edge cases, fill check) and the absence of an output schema, the description covers all essential aspects: parameter behavior, response structure, failure conditions, and references to related tools. It is fully self-contained.

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

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

Both parameters are fully described in the schema. The description adds examples of valid values (event slugs, topic seed questions) and explains the default behavior with no arguments, providing meaningful context beyond the schema.

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

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

The description clearly identifies the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three operation modes (no args, event, topic) and explains their specific use cases.

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

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

Explicitly states when to use each parameter (or none), contrasts cross-event vs single-event modes, provides a condition to avoid trading (realizable_edge_pp ≤ 0), and directs to polymarket_fill_risk 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 mark the tool as read-only, idempotent, and non-destructive. The description adds extensive detail beyond annotations: caching (1h at KV level), edge calculation (net of slippage, Kelly caps), model families, diagnostics, and a 24h-move warning. 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 long (~500 words) but well-structured with sections and bold keys. It front-loads purpose effectively but includes very detailed technical descriptions of model families that could be externalized. Every sentence adds unique information, but verbosity reduces 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?

For a complex tool with 9 parameters, nested model segments, diagnostics, and no output schema, the description is exceptionally complete. It explains all three opportunity segments, edge computation, Kelly sizing, tradeable-edge filters, caching, and diagnostic output structure. 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%, so baseline is 3. The description enhances schema definitions with practical context (e.g., slippage_pp explains Polymarket's zero fees but thin depth; min_partition_leg_kelly clarifies why min_kelly doesn't apply to partition arbs). Adds meaningful value beyond raw schema.

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

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

The description clearly states the verb ('scan'), resource ('Polymarket markets'), and unique value ('where Pipeworx data disagrees with market price'). It distinguishes from siblings like polymarket_arbitrage by specifying it's for 'what should I bet on today' without paging through hundreds of markets.

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

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

Explicitly positions the tool for discovering opportunities and explains when to use tradeable-edge knobs (min_liquidity, max_spread_pp). Mentions Fed bets are excluded from ranking due to data reliability. However, it does not explicitly contrast with alternatives like polymarket_edge_tracker or polymarket_fill_risk.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description adds significant context: data comes from daily snapshots, gaps mean no scan that day, decay computed from daily closes, and detailed explanation of tracked vs. expired arrays.

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 quite long and includes detailed response structure inline, which reduces conciseness. While well-structured, it could be more succinct by separating response format.

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

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

Given the complexity and lack of output schema, the description provides a thorough explanation of response fields, limits, and caveats. Still, it could be more organized for easier parsing by 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 coverage is 100% with clear parameter descriptions. The tool description restates defaults and bounds but adds little new information beyond what is already in the schema, warranting a baseline score.

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

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

The description clearly states the tool provides edge persistence and decay telemetry from daily snapshots, answering specific timing-related questions. It distinguishes itself from sibling tools by focusing on historical analysis rather than current edges.

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

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

The description explains when to use the tool (to differentiate new vs. old edges) and provides default parameter values, but does not explicitly state when not to use it or compare to alternatives among siblings.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses detailed behavioral traits: 'walks the ladder', 'thin_legs', 'forced_directional_risk', and the critical warning that 'partial basket fills convert an arb into an unhedged directional position (the dominant loss mode)'. 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: starts with purpose, then REQUIRES, then mode explanations, then usage guidance. Every sentence adds value, though it could be slightly more concise. The density of information justifies the length.

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

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

Given the complexity (two modes, no output schema), the description covers inputs, modes, outputs (return fields), risks, and usage context. It helps an agent understand exactly what to expect and when to use the tool. No output schema exists, so the description compensates fully.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant value: default values (size_usd=1000, side defaults), mode-specific interpretations (size_usd interpreted as settlement notional in basket mode), auto side detection logic, and explanations of how parameters affect return fields. This goes 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 clearly states 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket) with specific verbs and resources. It explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains when to use (large trades) and the risks of partial fills converting arb to unhedged positions. Sibling context is leveraged for clear when-not-to-use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds crucial behavioral details: compatibility_warning scenarios, temporal_alignment flag, skipped_cross_type counters, and the fact that many pre-mapped topics return warnings. 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 lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though it could be slightly condensed. The structured format helps 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?

Given the absence of an output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields) and edge cases (compatibility warnings, temporal alignment). It covers all necessary context for correct invocation.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context on how topic maps to shortcuts and how explicit overrides work, but this does not significantly surpass the schema's inherent clarity. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: computing cross-venue spread between Kalshi and Polymarket. It specifies two distinct modes (topic shortcuts and explicit parameters), and differentiates from sibling tools like polymarket_arbitrage by focusing on cross-venue rather than intra-venue arbitrage.

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

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

The description provides explicit when-to-use guidance, explains both modes, and cautions about compatibility warnings and temporal alignment. It clearly states that real spreads are rarer than the shortcut list suggests, helping the agent avoid misuse.

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, non-destructive. The description adds value by explaining the scoping mechanism and the dual behavior (retrieve vs list), with no contradictions.

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

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

Three concise sentences with no fluff, well-structured and front-loaded with the core action.

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

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

The tool is simple with one optional parameter and no output schema; the description fully covers both usage modes, scoping, and relationship with sibling tools.

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

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

Schema coverage is 100% and already describes the 'key' parameter simply. The description adds meaningful context by explaining that omitting the key lists all saved keys.

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

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

The description clearly states the tool retrieves a saved value or lists all keys when no key is provided, distinguishing it from 'remember' and 'forget' sibling tools.

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

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

It provides explicit use cases (look up stored context) and mentions scoping and pairing with remember/forget, though it does not explicitly state 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 indicate read-only, idempotent, non-destructive behavior. The description adds context about the mark_read side effect (flagging events as read), which is a state change but is transparently disclosed. 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 four sentences covering purpose, return fields, filtering, and usage. It is concise but contains essential information without unnecessary fluff. Slightly longer than minimal but every sentence adds value.

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

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

No output schema exists, but the description explains return values (source, citation_uri, raw payload). All 5 parameters are described with usage hints. It also mentions polling and an alternative access method. Complete for a read-oriented tool with good annotations.

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

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

Schema coverage is 100% with parameter descriptions. The tool description adds meaningful context beyond the schema: explains filter by type with an example ('sec_8k'), specifies ISO timestamp for 'since', and clarifies the effect of 'mark_read' on subsequent calls. This enhances 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 pulls fired events from a subscription feed, returns recent alerts with specific fields (source, citation_uri, raw payload), and supports filtering. It is specific and distinguishable from sibling tools like list_subscriptions.

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

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

The description provides explicit usage context: filtering by type and since, using mark_read to control read state, and mentions that polling works fine. It also points to an alternative endpoint for scripts/dashboards, though it does not directly compare to other tools in the sibling list.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: it explains the fan-out to multiple APIs with fallback (GDELT preferred, GNews when rate-limited or 5xx), the soft-fail for USPTO due to API sunset, the return structure (changes grouped by source, total_changes count, citation URIs), and the `since` format acceptance. 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 but efficiently packed: it begins with relatable user queries, then concisely describes the mechanism, sources, parameter details, and alternatives in a logical flow. Every sentence adds necessary information, and no wasted words are present.

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 sources, no output schema, rate-limit behavior, API sunset), the description is remarkably complete. It covers return format, fallback logic, soft-fail scenarios, parameter formats, and provides a clear alternative. There are no gaps in contextual information needed for an agent to use the tool correctly.

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

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

Schema coverage is 100% (all three parameters described in schema), yet the description adds value beyond: for `since`, it provides examples ('2026-04-01', '7d', '30d', '3m', '1y') and a usage suggestion ('30d or 1m for typical monitoring'). For `value`, it clarifies that both ticker and CIK are accepted. For `type`, it notes only 'company' is supported. This enriches the schema information.

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

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

The description starts with explicit user query examples ('What's new with X', 'latest on Y'), clearly defining the tool as a change feed aggregator. It specifies the three data sources (SEC EDGAR, GDELT/GNews, USPTO) and distinguishes itself from the sibling tool `entity_profile` by contrasting dynamic vs. static profiles. This makes the purpose specific, actionable, and differentiated.

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

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

The description explicitly states when to use the tool ('change feed for a company in the last N days/weeks/months') and when not to, by directing the agent to `entity_profile` for static profiles. It also covers the `since` parameter with recommendations like 'Use 30d or 1m for typical monitoring.' This provides clear usage context and 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 indicate idempotentHint=true and destructiveHint=false. The description adds valuable context: memory is scoped by identifier, persistent for authenticated users, and 24-hour retention for anonymous sessions. This goes beyond what annotations provide, though it could potentially mention that idempotent means re-saving same key updates value.

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

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

The description is four sentences, each with clear purpose. The first sentence states the main action, the second explains when to use, the third details storage mechanics, and the fourth references sibling tools. No superfluous words.

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

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

Given the tool has only 2 required parameters and no output schema, the description fully addresses usage: what to store, when, how it's scoped, retention policy, and pairing with recall/forget. No gaps remain for typical use cases.

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 examples for key (e.g., 'subject_property') and clarifies value can be 'any text'. This adds meaning beyond the schema's dry descriptions, earning a 4.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It uses a specific verb (save) and resource (data), and distinguishes from sibling tools like recall and forget by explicitly pairing with them.

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

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

The description provides explicit guidance on when to use the tool: 'Use when you discover something worth carrying forward'. It also mentions pairing with recall and forget, giving context on lifecycle. However, it does not explicitly state when not to use it, so a small deduction applies.

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 valuable behavioral context: identifiers that cannot be resolved are explicitly listed under `unresolved`, and LEI/FIGI enrichment degrades gracefully (EDGAR data still returns if GLEIF/OpenFIGI are down). This goes beyond the annotations and helps set expectations for partial failures.

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 well-structured: it starts with concrete usage examples, states the core purpose, gives a clear usage directive, then details supported types. Every sentence provides useful information, though it could be tightened slightly without losing 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 there is no output schema, the description takes responsibility for explaining return values. It covers the main resolved identifiers for both types, mentions the `unresolved` field, and notes graceful degradation. It is reasonably complete for a 2-parameter tool, though it does not specify the exact output JSON structure.

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

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

The schema already covers both parameters with 100% coverage. The description enriches this by explaining what each type returns (e.g., company resolves to CIK, ticker, LEI, FIGI; drug returns RxCUI, ingredient, brand) and what value formats are accepted (ticker, CIK, name). This adds meaning beyond the basic schema descriptions.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to official identifiers required by other tools. It provides concrete examples and explicitly distinguishes itself from siblings by framing it as the first step when a name needs an ID. The supported types are enumerated with specific output identifiers.

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

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

The description includes 'Use FIRST whenever you have a name but need an ID', giving clear guidance on when to invoke this tool. It also explains that it replaces 2-3 manual lookups, implying it is a preferred, consolidated option. However, it does not explicitly name alternative tools or describe when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds behavioral context: it calls ai_visibility_check per entity, ranks results, and surfaces most/least recognized. 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, front-loaded with purpose, and includes a concrete example. Every sentence serves a purpose 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 4 parameters (1 required), no output schema, and no nested objects, the description fully explains the return format (ranked list with score, confidence, signal density) and the tool's behavior. Complete and sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' for narrative and that context disambiguates common names. This goes beyond the schema.

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

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

The description clearly states it compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It distinguishes itself from sibling tools like ai_visibility_check (single entity) and compare_entities (generic 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 explicitly says 'Useful for competitive AI-marketing audits' and gives an example question. It implies when not to use (e.g., single entity check via ai_visibility_check) but does not explicitly name alternatives. Clear context provided.

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

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

Annotations already indicate a safe, idempotent read operation. The description adds valuable behavioral context: composite fan-out, partial failure degradation (bundlephobia timeout handling), and the specific data sources and returned structures, exceeding what annotations convey.

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

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

The description is appropriately sized, with each sentence earning its place: purpose, usage, return fields, ecosystem limitation, and partial failure behavior. It is front-loaded and well-structured, though slightly verbose for a very concise 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?

With no output schema, the description thoroughly lists return fields (summary fields, advisory details, links, alternative versions) and covers edge cases (scoped packages, default version, partial failures). For a composite tool of this complexity, it is fully complete.

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

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

Schema description coverage is 100%. The description adds meaning beyond the schema by explaining that scoped packages (e.g., '@types/node') are accepted for 'package' and that 'version' defaults to latest when omitted. This clarifies default behavior and acceptable inputs.

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: a composite npm package evaluation combining deps.dev and bundlephobia data, answering 'should I add this package?' queries. It distinguishes from sibling tools by specifying the npm ecosystem and the composite nature, and explicitly lists return fields.

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 whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also notes the npm-only limitation and directs users to deps.dev:version for other ecosystems, providing clear when-to-use and when-not-to-use guidance.

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

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

Beyond annotations (readOnly, idempotent), reveals internal mechanics (BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flag), fully disclosing behavioral traits.

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

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

Every sentence is purposeful: purpose, usage, pairing, internal details, limits—no redundancy, front-loaded with core action.

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

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

Despite no output schema, description specifies return (passages with offsets and scores) and truncation behavior, fully covering what an agent needs to understand usage and expectations.

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

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

Schema covers 100% of parameters; description adds value by clarifying query as natural-language with examples and confirming text limit, but baseline 3 applies due to full 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?

Clearly states it performs semantic search inside a fetched record, differentiating from sibling tools by specifying use cases like handling oversized records and pairing with ask_pipeworx_grounded.

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 advises when to use (when record too large for prompt), how it saves context, and pairs with ask_pipeworx_grounded, providing clear context-aware guidance.

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

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

The description discloses important behavioral details beyond annotations: subscription persistence requires OAuth, SMS delivery is capped at 10/day and requires phone verification, webhook auto-disables after 10 consecutive failures, and HMAC signing is explained. 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 well-structured starting with the core purpose, then requirements, supported types, and delivery details. It is slightly verbose with examples but each sentence adds value. Could be trimmed slightly for 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?

Given the tool's complexity (multiple subscription types, nested delivery params, no output schema), the description covers all necessary aspects: types with parameter formats, delivery options with limitations, and hints about return values (subscription ID and webhook secret).

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?

While the schema covers all parameters, the description adds substantial meaning with concrete examples for each type and delivery channel, constraints (e.g., phone verification, webhook HTTPS requirement), and the fact that webhook secret is returned only once.

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 proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 specifies requirements (Pipeworx OAuth account) and provides examples for different subscription types and delivery channels. However, it does not explicitly contrast with alternatives like recent_alerts or list_subscriptions when the user might want to view existing subscriptions instead of creating new ones.

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 safety (readOnly, idempotent, non-destructive). Description adds value by disclosing the return format (category-bucketed examples with tool/argument shapes) and that calling with no arguments gives full spread. 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 front-loaded with the purpose and uses a clear structure: opening phrases, explanation of output, usage options. It is slightly verbose with example categories but remains well-organized and scannable.

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

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

For a tool with one optional parameter and no output schema, the description covers all necessary context: purpose, output format, optional focus, and when to use. 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 the optional 'topic' parameter with allowed values. Description reinforces by listing examples ('finance', 'pharma') and clarifies behavior when omitted, adding practical usage 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 uses specific verbs ('returns category-bucketed example questions') and clearly identifies the tool as the onboarding entry point. It distinguishes from siblings like 'ask_pipeworx' by focusing on generating ideas rather than answering specific queries.

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

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

Explicitly advises 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains optional topic filtering. While it doesn't list alternatives for when not to use, the context implies it's for exploration, not direct answers.

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 clarifies that the row is deactivated (not deleted), so historical events remain available via recent_alerts. It also reiterates ownership enforcement, aligning with annotations (destructiveHint: false, idempotentHint: true). 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 extremely concise: two sentences, no extraneous words. First sentence states the action and constraint, second explains the behavioral nuance. Every sentence is necessary.

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

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

For a simple tool with one parameter, high schema coverage, and annotations providing safety profile, the description covers all necessary behavioral aspects (ownership, deactivation). No output schema needed. Complete for agent invocation.

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

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

Schema coverage is 100% and the description does not add significant meaning beyond the schema. The parameter 'id' is already described in the schema as 'Subscription id (uuid) returned by subscribe.' Baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', which is a specific verb and resource. It distinguishes from sibling tools like subscribe and list_subscriptions by noting ownership enforcement and deactivation behavior.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions'), providing a clear condition for use. It implies this tool is for cancellation but does not explicitly mention when not to use it or suggest 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. Description adds behavioral details: two-path routing (SEC vs. grounded), exact percent-delta math for financial claims, and return structure (verdict, value, 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 relatively long but well-organized, starting with examples and use cases. Each sentence adds value. Could be slightly more concise, but 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?

Given 2 parameters with full schema coverage, no output schema, and complex behavior (two verification paths), the description is thorough. It explains return values (verdict types, citation, reasoning) and covers both routing paths without 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 covers both parameters fully (100%). Description adds meaning: 'claim' explained as natural-language factual claim with examples; 'tolerance_pct' explains default behavior and override use case (e.g., hallucination detection).

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 claim verification/fact-checking, provides specific examples of natural-language queries, and distinguishes from siblings by detailing two distinct verification paths (structured SEC EDGAR for financial claims, grounded pipeline for others).

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Differentiates between financial and other claims, and notes it replaces multiple sequential calls. Lacks explicit 'when not to use' but context is clear.

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