Denue

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, indicating safe, non-destructive behavior. Description adds value by explaining the scoring range (0-100), default model, requirement for API key to probe Anthropic, and return format (per-model score, confidence, signals, raw_response + combined view). No contradictions.

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

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

Description is two sentences, front-loading the core action and key details. Every sentence adds value without redundancy. Efficient and clear.

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

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

Given 4 parameters with 100% schema coverage, no output schema, and strong annotations, the description fully covers the tool's behavior and output. It explains the return structure, scoring, and optional API usage. No critical gaps.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds meaning beyond schema: it explains the default model (workers-ai), the role of _apiKey (BYO key for Anthropic), and context helps disambiguate entities. This provides useful contextual guidance not in the schema.

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

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

Description clearly states the tool probes LLMs about an entity and scores visibility 0-100. It specifies the verb 'probe' and resource 'LLMs', and provides concrete use cases (AI-marketing audits, pre-launch brand checks). This distinguishes it from sibling tools like deep_research or bet_research, which have different purposes.

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

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

Description explicitly indicates when to use the tool (AI visibility audits, brand checks) and provides guidance on default model and optional API key. However, it does not explicitly state when not to use it or contrast with alternatives among siblings, though the purpose is fairly unique.

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. Description adds that it routes to the right tool, returns structured answers with pipeworx:// citation URIs, works on every tier, and is one fast call. 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 paragraphs but well-structured with a clear front-loaded instruction, inline examples, and usage hierarchy. Every sentence serves a purpose, though slightly lengthy.

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

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

Despite no output schema, the description explains the return format (structured answer with citations). It covers use cases, examples, alternatives, and behavioral notes. Complete for a complex routing tool.

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

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

Schema description coverage is 100%, with all 6 parameters documented (5 are aliases for question). Description does not add significant meaning beyond the schema; it only states that the parameter is a natural language question.

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 'PREFER OVER WEB SEARCH' and explicitly lists many domains (SEC, FDA, FRED, etc.), clearly stating the tool routes questions to a vast set of sources. It distinguishes from siblings by specifying when to use ask_pipeworx_grounded and deep_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 guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists example queries. Also tells when to step up to alternatives: 'for a hallucination-resistant single answer use ask_pipeworx_grounded; for broad/multi-part use deep_research'. Covers breaking news as well.

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 it as read-only, idempotent, and non-destructive. The description adds detailed behavioral traits: return structure with evidence, confidence, source, explicit refusal reasons, and the fact that it costs an extra LLM call. 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 comprehensive but well-structured, starting with purpose, then process, usage, and return value. Every sentence adds value, though slightly long for a very concise ideal.

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 fully specifying the return format and refusal reasons. Parameter count is high but schema covers all. The description is complete for an agent to use correctly.

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

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

Schema coverage is 100% with all parameters described. The description mentions that question accepts aliases, which is already in the schema. No additional semantic value beyond the schema.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains it extracts answers using only tool results. It distinguishes from sibling ask_pipeworx by emphasizing groundedness and 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 tells when to use (when answers will be quoted/cited/acted on, high-stakes like financial or medical) and when not (prefer ask_pipeworx for casual lookups). Also notes the extra cost.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. Description adds extensive behavioral context: resolution flow, fan-out details, response shapes, error conditions (low-confidence, closed markets, wide spreads, cancellation rules). No contradiction with annotations.

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

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

Front-loaded with core purpose, but very long and dense. Contains multiple paragraphs of detailed behavioral info that could be restructured or condensed. Every sentence is informative but conciseness suffers.

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?

Extremely complete given complexity and no output schema. Covers input formats, classification, fan-out examples, response structure, resolver contract, parent event extraction, news fallback, safety mechanisms, cancellation rules. Leaves virtually no ambiguity 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?

100% schema coverage (baseline 3). Description adds meaning: explains market input formats (slug, URL, question text), depth options with defaults, and include_raw rationale. Provides examples and practical guidance 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?

Starts with a clear verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' Distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage that focus on specific sub-tasks.

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

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

Explicitly states use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides clear context but does not explicitly exclude scenarios or mention alternatives to prevent 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 declare readOnlyHint, idempotentHint, and openWorldHint. The description adds significant context: it pulls specific financial metrics for companies (revenue, net income, cash, debt) and drug metrics (adverse events, FDA approvals, trials), handles off-calendar fiscal years, sorts by primary metric, and returns citation URIs. This goes beyond annotations.

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

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

The description is comprehensive but slightly long. It is front-loaded with common query patterns and structured with clear sections. Every sentence adds value, but some redundancy could be trimmed.

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 of comparing two entity types with distinct data sources and multiple metrics, the description is thorough. It explains input constraints, data sources, sorting, and output format (paired data + URIs). No output schema exists, so the description adequately covers return values.

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

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

Schema coverage is 100%, but the description adds meaning: it explains what each 'type' value returns (financials vs. drug data) and gives examples for 'values' (tickers/CIKs for companies, drug names). It also clarifies constraints like 2–5 items.

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 performs side-by-side comparison of 2–5 companies or drugs, with specific data sources (SEC EDGAR for companies, FAERS for drugs). It distinguishes itself from sibling tools like 'entity_profile' by emphasizing parallel lookup over sequential single-entity lookups.

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

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

The description provides explicit when-to-use guidance (comparing, ranking, head-to-head) and advises to ALWAYS prefer this tool over sequential single-pack lookups. It also specifies valid entity types and output behavior.

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, openWorld), the description reveals key behaviors: account dependency, parallel facet decomposition, output structure (evidence, confidence, gaps), and that it never invents answers. 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?

Every sentence provides critical information: account requirement, alternative, tool capability, internals, output, timing, use cases, and exclusions. Front-loaded with most important details. No wasted words despite 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 tool's complexity (2 params, no output schema), the description fully covers what the tool does, how it works, output format, constraints, and alternatives. Complements the lack of output schema by describing the findings packet and 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% and both parameters have descriptions. The description enriches them significantly: explains depth enum values (quick=3, standard=5, thorough=8) and that standard is default, and clarifies that question can be broad/multi-part. Adds value beyond schema, so above baseline 3.

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

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

Clearly states the tool performs grounded multi-source research across Pipeworx's structured data sources, decomposing questions into facets and routing to thousands of tools in parallel. It distinguishes from siblings by explicitly contrasting with ask_pipeworx (single lookup) and noting it is not open-web 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?

Provides explicit when-to-use: broad/multi-part questions over structured data. Gives when-not-to-use: breaking/current news, with alternative ask_pipeworx. Also states account requirement and alternative for non-signed-in users. Mentions expected response time (15-60s).

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

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

Annotations already declare read-only and idempotent behavior. Description adds that the tool returns only totals (no detail records), which is essential behavioral knowledge beyond annotations.

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

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

Two efficient sentences with no wasted words. Every part is informative and 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?

Given the tool's simplicity, the description covers all key aspects: what it counts, returns, and an example. No output schema is needed as totals are straightforward.

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

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

Schema covers all parameters (100% coverage). The description provides an illustrative example ('how many pharmacies are in Jalisco') that clarifies parameter usage, adding value beyond the schema.

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

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

Clearly states the tool counts establishments by activity, geography, and size. Distinguishes from sibling tools like denue_establishment by specifying it returns totals only.

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

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

Provides an explicit use case ('market-sizing questions') and an example. Does not explicitly state when not to use or name alternative tools, but the context makes it clear.

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

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

Annotations already indicate read-only, idempotent, not destructive. Description adds that it returns full details and clarifies the ID source, complementing the annotations without contradiction.

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

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

Single, concise sentence that is front-loaded with the purpose and includes relevant context about the ID source. 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?

Adequate for a simple read operation with one parameter. Lacks output structure, but not critical given no output schema and the straightforward nature of 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 covers 100% of parameter with description and example. Description adds minor value by linking ID to search results, but does not significantly extend beyond schema.

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

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

The description clearly states the tool retrieves full details for a single establishment using a DENUE ID, distinguishing it from sibling search tools like denue_search_by_name and denue_search_in_state.

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 to use the ID from search results, providing contextual guidance with a prerequisite step. No explicit when-not-to-use, but sufficient for this simple tool.

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

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

The description adds useful behavioral context beyond annotations: it reveals pagination behavior ('Paginated — set page_size and page_start to walk results'). Annotations already confirm read-only, idempotent, and non-destructive traits, and the description aligns with these without contradiction.

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

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

The description is extremely concise: two sentences that front-load the core purpose and then add the key behavioral note about pagination. Every sentence adds value with no 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?

The description covers purpose and pagination but lacks details about the return format, error handling, or result structure (e.g., what fields are returned). For a search tool with no output schema, more context would help the agent understand the response. Still, the essential behavioral traits are present.

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

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

All four parameters have clear descriptions in the input schema (100% coverage), so the description adds no additional meaning. It simply mentions pagination, which is already covered by schema descriptions for 'page_start' and 'page_end'. 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 specifies a clear verb ('Search') and resource ('businesses by name or brand') with geographical scope ('across Mexico or a single state'), which effectively distinguishes it from sibling tools like 'denue_search_in_state' or 'denue_search_nearby'.

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

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

The description does not provide guidance on when to use this tool versus alternatives, nor does it mention when not to use it. There are no explicit usage rules or context that help the agent decide between this and sibling tools.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) already declare safe, read-only behavior. The description adds 'Returns paginated results', which is useful but minimal. No contradiction with annotations, but no further behavioral details (e.g., error handling, max page size) are provided.

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: purpose, usage guidance, result format. No unnecessary words, front-loaded with the core action. Every sentence serves a clear 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?

With good schema descriptions and annotations, the description covers purpose, usage, and pagination. It distinguishes from sibling search tools. Missing details like result structure or error cases are minor given the tool's simplicity and the presence of pagination mention.

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 param meaning by stating that keyword matches name/activity/address, and the state_code schema description directs nationwide queries to denue_search_by_name. This adds context beyond the raw schema definitions.

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

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

Description clearly states verb ('Search') and resource ('businesses in a single Mexican state by keyword'), and specifies matching fields (name, activity, address). It differentiates from sibling tools like denue_search_by_name (nationwide) and denue_search_nearby via the state-scoped constraint.

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 this for state-scoped queries that need more than just business name' and provides examples ('panaderia', 'ferreteria'). The schema description for state_code hints at the alternative tool, but the main description lacks explicit when-not-to-use or exclusions beyond the nationwide reference.

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 read-only and nondestructive hints. The description adds the radius limit (max 5000m) and result nature, but lacks details like pagination or rate limits. Adds some value beyond annotations.

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

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

Two concise sentences, no filler. Front-loaded with the core action and key constraints. Every sentence is informative.

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

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

With 4 parameters, good annotations, and no output schema, the description covers the essential behavior. It does not mention pagination or return format, but the openWorldHint and read-only nature mitigate the need.

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 description need not explain every parameter. It adds value by clarifying 'condition' as a keyword (e.g., 'oxxo', 'todos') and reinforcing the radius range. Enhances practical 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 finds businesses near a coordinate, returning establishments matching a keyword within a radius. It uses specific verbs and resources, and distinguishes from siblings like 'denue_search_by_name' and 'denue_search_in_state'.

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 location-based keyword search but does not explicitly discuss when to use alternatives or when not to use. Context is clear but no exclusions or comparisons are 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 readOnlyHint and idempotentHint, so the bar is lower. The description adds valuable context: it returns top-N relevant tools with full schemas and examples, and promises no second schema lookup. It does not contradict annotations and discloses the result format beyond what annotations provide.

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

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

The description is 4 sentences with no filler. The first sentence states the core action, the second lists use cases, the third explains the rich return format, and the fourth gives strategic guidance. Every sentence earns its place, and it is well front-loaded.

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

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

Given the tool's complexity (6 parameters, no output schema), the description adequately explains the return format (top-N tools with schemas and examples) and the query parameter's flexibility. It does not address pagination or sorting, but for a discovery tool, this is sufficient. A slightly more detailed description of the search behavior would push it to 5.

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 provides example domains and confirms aliases, but the schema already describes all parameters with natural language examples. The description adds moderate value by listing real-world use cases but does not significantly enhance understanding 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 'Find tools by describing the data or task' and lists specific domains (SEC filings, FDA drugs, etc.), distinguishing it from all sibling tools as the sole discovery tool. It specifies that it returns tool schemas ready to call, making the 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?

It provides explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set.' It also lists when to use (browse, search, look up, discover). However, it does not explicitly state when NOT to use or mention alternatives, missing a small element for a top score.

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 beyond: explains fans out across multiple sources, returns structured data with limits (e.g., up to 5 filings), and discloses USPTO API sunset soft-fail. 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 example queries and a key instruction, then provides detailed breakdown. While lengthy, it is well-organized and every sentence adds information, so it earns its length.

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

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

No output schema, but the description fairly fully outlines return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and constraints (e.g., sorted period_end DESC, soft-fail). Leaves some ambiguity about patent reactivation but sufficient for agent selection.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds value by clarifying acceptable values (ticker or zero-padded CIK) and the limitation that names not supported, reinforcing schema guidance.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' with specific verb 'profile'. It distinguishes from sibling tools like resolve_entity by noting it should be used only with a ticker or CIK, and recommends resolve_entity first if only a name.

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 chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises using resolve_entity first if only a name. Also mentions patents soft-fail, 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 provide destructiveHint=true and readOnlyHint=false. Description adds context that it deletes memory saved by the agent and is for clearing sensitive data, which is consistent and slightly extends the behavioral understanding beyond annotations.

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

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

Two sentences, front-loaded with action, then usage context. No wasted words; each sentence serves a distinct purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and sibling relationships. Complete for the tool's complexity.

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

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

Schema coverage is 100% with a single parameter 'key' described, but the description adds no further meaning beyond 'by key'. Baseline 3 is appropriate as 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 'Delete a previously stored memory by key', specifying the verb and resource, and distinguishes from sibling tools 'remember' and 'recall' by context.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and pairs with alternatives: 'Pair with remember and recall'.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint false, fully covering safety. The description adds behavioral context: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This explains the process without contradicting annotations, providing value beyond the structured fields.

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

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

The description is compact (two sentences plus a bullet-like list), front-loads the essential action ('Generate a production-ready llms.txt file'), and every sentence adds information. No 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 the tool has only 2 well-documented parameters, no output schema, and annotations cover safety, the description sufficiently explains the output format ('single text blob'), the process (fetch, extract, emit), and the intended use cases. An agent has all necessary context to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for both url and max_links. The description adds modest value: it reiterates the URL role ('site to summarize') and provides an example ('https://example.com'), but does not substantially enhance understanding 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 generates a production-ready llms.txt file for any URL, specifying the verb ('generate'/'fetch'/'extract') and resource ('llms.txt file'). It distinguishes from siblings by focusing on the specific output format (llms.txt) and enumerates concrete use cases (client site indexing, personal drafting, competitor auditing), making the 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 provides three explicit use cases (getting a client site indexed, drafting for own project, auditing competitor AI visibility). It strongly implies when to use, but does not explicitly state when not to use or name alternative tools among the siblings (e.g., scan_competitor_ai_presence). Still, the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds return field details. No mention of pagination or limits, but acceptable given annotations.

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

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

Two sentences, no wasted words. Purpose and return fields are front-loaded.

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

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

Complete for a simple list tool with one optional parameter and good annotations. Could mention pagination, but not essential.

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% for the single parameter include_inactive. The description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states the verb 'List' and resource 'subscriptions', specifies return fields, and distinguishes from siblings like subscribe and unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' No 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.

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

Discloses that the tool is free, does not count against tool-call quota, and is rate-limited to 5 per identifier per day. Annotations do not contradict the description. Some behavioral aspects like what happens after submission are omitted, but overall adds value beyond annotations.

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

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

Every sentence serves a purpose. The description is short, front-loaded with the primary action, and structured logically: what it does, when to use, what not to do, operational details. 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 the moderate complexity (3 parameters, one nested object) and no output schema, the description covers purpose, usage, behavior, parameter guidance, and provides operational context (roadmap impact). Lacks explicit description of the response, but for a feedback tool this is acceptable completeness.

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 detailed semantics for each parameter: explains the meaning of each enum value, provides concrete examples for context fields (e.g., pack slug 'fred'), and specifies the message length limit. 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 starts with a clear verb-resource pair ('Tell the Pipeworx team') and explicitly lists use cases (bug, feature, data_gap, praise), differentiating this tool from sibling research/info 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?

Provides explicit when-to-use guidance for each category and a negative instruction ('don't paste the end-user's prompt'). Also mentions rate limits and quota, helping the agent decide if this tool is appropriate.

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 details about data source (CF analytics-engine), no PII, caching behavior, which complements annotations without contradiction.

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

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

Concise, well-structured with bullet points for use cases. Front-loaded with main function; 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?

For a simple read-only tool with one optional parameter and comprehensive annotations, the description fully covers what the tool returns, data source, caching, and use cases. 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 description coverage is 100% for the single parameter 'window'. The description adds contextual meaning about shorter vs longer windows, improving understanding beyond the schema.

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

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

Clearly states the tool returns top tools, packs, and call volume over a window, using specific verbs and resources. Distinguishes from sibling tools like 'discover_tools' by focusing on trending data.

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

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

Explicitly lists three use cases (discovering hot sources, confirming canonical tool, aligning use case). While it doesn't explicitly state when not to use, the guidance is clear and actionable.

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 (readOnlyHint, idempotentHint, etc.), the description details edge cases: partition filter drops placeholder slugs, fill check tests live CLOB depth, semantic anchor uses Jaccard similarity. It explains internal logic (monotonicity, partition_sum, fill_check) and warns when realizable_edge_pp ≤ 0. No contradiction with annotations.

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

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

The description is dense but well-organized, front-loading the requirement and mode usage. Every sentence adds value, though it could be slightly more structured (e.g., bullet points for response fields). Still efficient for the complexity.

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

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

Given the tool's complexity (two modes, internal checks, fill check, edge cases), the description is thorough. It covers required parameter, algorithm, response fields, and fill check behavior. No output schema, but response elements are described. Complete for effective use.

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

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

Schema coverage is 100% with descriptions, but the tool description adds significant detail: for event, it explains walking child markets and checking; for topic, it describes cross-event scanning and flattening. This adds meaning beyond the schema, justifying a 4.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishing two modes (event and topic). It uses specific verbs (find, walks, checks) and resources (Polymarket markets). Compared to siblings like polymarket_edges and polymarket_fill_risk, it is distinct.

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

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

The first sentence explicitly requires one of event or topic and warns against calling with no args. It recommends event for specific markets and topic for cross-event scanning, and mentions polymarket_fill_risk as an alternative for custom sizing. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations (readOnlyHint, idempotentHint) already indicate safe, read-only behavior. The description adds extensive behavioral details: caching at KV level (1h), output structure with diagnostics, edge calculation including slippage, Kelly caps, 24h-move warnings, and fed markets handling. It far exceeds annotation coverage without contradiction.

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

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

The description is long but well-structured with clear sections: overall purpose, model families, tradeable-edge knobs, response format. It front-loads the main use case. While some depth might be trimmed, the information density justifies the length for a tool with 9 parameters and complex output.

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 thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and each field. It covers parameter behaviors, edge cases (empty segments, filter skips), and caching. The description is complete and anticipates agent needs.

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?

All 9 parameters have descriptions in the schema (100% coverage), so baseline is 3. The description adds value by explaining rationale (e.g., slippage_pp discusses Polymarket fees and depth) and interactions (min_kelly vs. min_partition_leg_kelly for partitions). This extra context justifies a 4.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses a specific verb ('scan') and resource ('Polymarket markets'), and distinguishes from siblings by focusing on these disagreement opportunities. The phrase 'what should I bet on today' frames the purpose precisely.

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: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the three model segments and when each applies, as well as tradeable-edge knobs. While it doesn't explicitly state when not to use, the context is comprehensive for a discovery tool.

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

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

Annotations provide readOnly, idempotent, and openWorld hints. The description adds substantial behavioral details: snapshot gap handling, decay derived from daily closes not intraday, and the meaning of negative edge_pp_net (SELL YES). 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: purpose first, then response fields in detail, then limits. Every sentence adds value, no fluff. It is front-loaded for quick understanding.

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 return values: tracked, expired, snapshot_dates. It covers edge cases (gaps, lifespan median, decay derivation). Given only two parameters and no output schema, this is exceptionally complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds context: default values (days=14, window='1wk'), and interprets parameters in the edge-tracking domain (lookback, snapshot family). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence, not just 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 implicitly guides usage by detailing what it returns and including a LIMITS section (60-day TTL, snapshot start). However, it does not explicitly state when to or not to use this tool versus siblings, though the uniqueness of the telemetry output makes the context clear.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it walks the ladder, returns verdict, and for basket mode includes thin_legs and forced_directional_risk. 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?

Well-structured with headings and semicolon lists, but somewhat verbose. Every sentence adds value, but could be tightened.

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 (two modes, many return fields, warnings) and lack of output schema, description thoroughly explains the return values and rationale for using the tool. Covers all necessary context.

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

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

Schema description coverage is 100%, but description adds extra meaning: explains single-market vs basket mode, default values, size_usd interpretation, and side auto-detection logic. Exceeds schema alone.

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

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

Clearly states the tool checks realizable-vs-theoretical edge against live CLOB order-book depth. Distinguishes single-market and basket modes, and lists return fields. Differentiates from siblings by explicitly saying 'USE THIS before acting on any polymarket_arbitrage...'

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

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

Explicitly states when to use (before acting on arb signals or trades above ~$500) and what happens if not used (partial fills convert arb to unhedged directional). Also explains that REQUIRES one of `market` or `event`.

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 behavior. The description adds valuable context on safety fields (compatibility_warning, temporal_alignment, skipped counters) and explains that most pre-mapped topics are not tradeable, which goes beyond basic 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 thorough but somewhat lengthy. It is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) but could be more concise while retaining key information.

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

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

Given the complexity of cross-venue spread with matching logic and safety checks, the description covers all necessary aspects: response fields (top_spreads_pp), temporal alignment, and compatibility warnings. No output schema exists, so the description must explain return values, which it does thoroughly.

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

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

Schema coverage is 100% with descriptions for each parameter. The description further clarifies the two modes and provides examples, adding value beyond the schema by explaining how topic vs explicit work.

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

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

The description clearly states the tool computes the cross-venue spread between Polymarket and Kalshi for the same resolving question. It specifies two modes (topic and explicit) and distinguishes it from other sibling tools like polymarket_arbitrage which only focus on single venues.

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 compare prices across venues) and provides warnings about non-tradeable cases via compatibility_warning. It could be more explicit about when not to use, but the safety fields guide the agent.

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

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

Annotations already indicate safe read operation. Description adds context about scoping to user identifier, which is beyond annotations. No contradiction.

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

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

Three sentences, front-loaded with core action, no unnecessary words. Each sentence adds value: action, usage context, and scope.

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 simple retrieval tool with single optional parameter, description fully covers behavior (with/without key), scope, and pairing with siblings. No output schema needed as return is straightforward.

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. Description adds clear explanation: omitting key lists all keys, providing key retrieves specific value. Adds meaning beyond schema's short description.

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

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

Clearly states the verb (retrieve/list) and resource (saved values/keys). Distinguishes from siblings 'remember' and 'forget' with specific pairing. Specifies both use cases: with key for value retrieval, without key for listing all keys.

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 to use for looking up stored context to avoid re-deriving. Provides scoping info and pairing with remember/forget. No explicit when-not to use, but the context is clear enough.

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

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

Annotations already convey readOnly, openWorld, idempotent, non-destructive traits. The description adds value by explaining the effect of mark_read (flags events as read for next call), the contained fields (source, citation_uri, payload), and the polling suitability. 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?

Four sentences efficiently convey purpose, returned fields, parameter usage, and an alternative access method. No redundant words; all information is relevant and front-loaded.

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

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

Despite lacking an output schema, the description clearly explains return fields (source, citation_uri, payload). It covers all parameters, side effects of mark_read, and even offers an alternative endpoint. For a read-only tool with 5 optional parameters, this 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 coverage is 100% but descriptions are brief (e.g., 'Optional ISO timestamp'). The tool description enhances understanding by connecting 'since' to 'fired_at' and providing an example 'sec_8k' for type, and explaining mark_read's impact on future calls. This adds behavioral context beyond schema text.

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 'Pull fired events' and the resource 'from your subscription feed.' It specifies returns of recent alerts with source, citation_uri, and payload, effectively distinguishing it from sibling tools like 'list_subscriptions' which likely lists metadata, not events.

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

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

The description provides clear context for usage: it mentions filtering by type and since, setting mark_read, and notes that polling works fine. It also suggests an alternative HTTP endpoint for scripts, implying use cases. However, it does not explicitly state when not to use this tool versus others.

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, non-destructive, idempotent behavior. The description adds valuable behavioral context: parallel fan-out to multiple sources, fallback logic (GDELT→GNews), soft-failure for USPTO, and output format with citation URIs. No contradiction with annotations.

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

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

The description is fairly long but well-structured: it opens with usage examples, then covers sources, parameter details, fallback, and output. Every sentence serves a purpose, though minor redundancy could be trimmed. Still, it remains efficient for its complexity.

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

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

Given the tool's complexity (multiple sources, fallback, parameter formats) and no output schema, the description is remarkably complete. It explains the parallel nature, fallback mechanism, soft-fail status, output structure (changes[] grouped by source, total_changes, citation URIs), and distinguishes from sibling tool. 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 description coverage is 100%, providing a baseline of 3. However, the description adds significant meaning: explains 'since' accepts both ISO dates and relative shorthand (with examples and recommendation '30d'/'1m'), confirms 'type' only supports 'company', and clarifies 'value' accepts ticker or CIK. This exceeds the schema's own 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: providing a change feed for a company in the last N days/weeks/months via one parallel call. It lists specific sources (SEC EDGAR, GDELT→GNews, USPTO) and output format (structured changes[] grouped by source), and explicitly distinguishes from sibling tool 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?

The description provides explicit usage examples ('what's new with X'), explains when to use this tool (recent changes) and when to use entity_profile (static profile), and details the fallback behavior (GDELT→GNews when rate-limited). It offers clear guidance on the 'since' parameter with shorthand examples.

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 (idempotentHint, etc.), the description adds critical behavioral details: scoping by identifier, persistence for authenticated users (persistent) vs anonymous (24 hours). No contradiction with annotations.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value: purpose, usage, behavioral details, and pairing with siblings. 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 simple 2-param tool with no output schema, the description covers all essential aspects: what, when, how (key-value, scoping, persistence). It is complete for agent decision-making.

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

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

Schema coverage is 100% with descriptive parameter definitions (e.g., key examples). The description mentions key-value pair but adds little beyond the schema. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose with a specific verb ('save') and resource ('data to reuse later'). It distinguishes from sibling tools like recall and forget by mentioning retrieval and deletion. The scope is well-defined (key-value pair, scoped by identifier).

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 provides when-to-use guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also pairs with recall and forget, giving clear alternatives for related operations.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds substantial context: internal cascading lookups, auto-disambiguation for company inputs, exact return fields per type (including citation URIs), and the fact that it replaces 2-3 manual lookups. No contradictions; it enriches the behavioral model.

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

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

Concise yet richly informative. Opens with natural language queries to signal use cases, follows with a clear imperative ('Use FIRST…'), then lists supported types in structured detail. Every sentence is purposeful; no redundancy. Front-loaded with the core purpose.

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

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

For a lookup tool with only two parameters and no output schema, the description is highly complete. It specifies return values per type (including citation URIs), explains internal cascading, and notes auto-disambiguation. It covers all essential aspects an agent needs to invoke and interpret results.

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

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

Schema coverage is 100% so baseline is 3. The description adds meaning by explaining accepted input formats (ticker, CIK, or name for company; brand or generic for drug) and highlighting auto-disambiguation. Examples like 'AAPL', '0000320193', 'ozempic' further clarify acceptable values.

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

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

The description clearly defines the tool's purpose: resolving user-spoken names to canonical identifiers needed by other tools. It provides specific example queries ('ticker for…', 'CIK for…', 'RxCUI for…') and explicitly states the verb+resource. It also distinguishes from siblings by positioning itself as a prerequisite lookup tool for ID-dependent operations.

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 FIRST whenever you have a name but need an ID.' Lists supported entity types and what each returns. Does not explicitly state when not to use or compare to alternatives like entity_profile, but the use case is sufficiently scoped. Minor gap in excluding pre-owned-ID scenarios.

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, and non-destructive behavior. The description adds that it probes each entity with ai_visibility_check, ranks results, and returns score, confidence, and signal density. No contradictions, and adds useful behavioral context beyond annotations.

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

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

Three concise sentences with no wasted words. The core action is stated first, followed by how it works and a usage example. Well-structured and front-loaded.

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

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

For a tool with no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also provides usage context (competitive audit) and constraints (2-8 entities). Slightly more detail about the ranking logic could improve completeness.

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 briefly mentions 'context' and 'entities' but does not add significant new meaning beyond what is in 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 compares AI visibility across multiple entities side-by-side, using a specific verb and resource. It distinguishes from siblings by focusing on multi-entity comparison and ranking.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example question, implying when to use it. However, it does not explicitly state when not to use it or mention alternative sibling tools.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), the description adds critical behavioral traits: fan-out across services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 efficiently structured: front-loaded with the core purpose, then usage, then detailed behavior and return values. 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 no output schema, the description thoroughly explains return fields (summary block, per-advisory detail, links, alternative versions) and edge cases (partial failures, timeouts). It is complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor extra context: 'Scoped packages (e.g. "@types/node") are accepted' and restates the default version behavior. This is helpful but not significantly 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 performs a composite check for adding an npm package, specifying the resources (deps.dev and bundlephobia) and the exact action. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on dependency analysis.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small"'. It also specifies when not to use (non-NPM ecosystems) and directs to deps.dev:version directly for others, giving clear boundaries.

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 safe and idempotent. The description adds crucial behavioral details: 200K char limit, truncation with flag, embedding model, windowing strategy, and return fields (offsets, similarity). 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 concise sentences. First sentence establishes core function, second adds usage context, third provides technical detail. No fluff; each sentence earns its place. Front-loaded with the key 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, the description explains what is returned (top-N passages with offsets and scores). Combined with annotations covering safety, the description is complete for the tool's complexity. It addresses input limits, pairing, and verification of verbatim quotes.

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 'text' as the fetched record and giving concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue'). The limit parameter is implied with range.

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 performs semantic search inside a fetched record. It uses specific language ('INSIDE', 'passages', 'character offsets') and distinguishes from sibling 'ask_pipeworx_grounded' by explaining the pairing and different 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?

Explicitly tells when to use: 'when the record is too big to cram into the prompt'. It also suggests a complementary tool (ask_pipeworx_grounded). Does not explicitly state when not to use, but the context is clear.

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

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

Description details behavioral traits beyond annotations: creation persists subscriptions, returns ID, specifies delivery channels with constraints (email validation, phone verification, SMS daily cap, webhook auto-disable after failures). Annotations indicate non-read-only and non-destructive, which aligns.

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

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

Single paragraph is dense but well-organized, front-loading the core action. Could benefit from bullet points for the supported types, but it remains readable and structured.

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

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

Despite no output schema, the description mentions the return value (new subscription id). All three parameters are thoroughly explained. The tool's complexity is well addressed with detailed type-specific parameter examples and delivery channel constraints.

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

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

Schema coverage is 100% but the description adds significant value: explains the 'type' enum with concrete examples, elaborates each 'params' variant, and details 'delivery' options including webhook HMAC signing. The description goes well beyond the schema's brief 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 uses the specific verb 'Create' and identifies the resource as a 'proactive monitoring subscription to a live-data event stream', clearly stating it returns the new subscription id. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' 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?

Provides clear context for when to use (proactive monitoring) and lists supported subscription types with examples. Requires a Pipeworx OAuth account and notes that anonymous/BYO cannot persist subscriptions. Lacks explicit ‘when not to use’ but the account requirement serves as a constraint.

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?

Description adds context beyond annotations: it returns category-bucketed examples drawn from a live catalog, and explains behavior with no args vs topic. 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 slightly verbose but well-structured with front-loaded examples and clear sections. Each sentence adds value.

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

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

Given the simple schema and rich annotations, the description fully covers purpose, usage, and return type. 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%, but description adds meaning by listing possible topic values and the effect of omitting it, enhancing the schema's minimal description.

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

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

The description clearly states it is an onboarding entry point that returns categorized example questions with tool calls. It distinguishes itself from siblings by being the first tool to use when unsure.

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 to use this FIRST when unsure, and mentions alternative meta-tools like ask_pipeworx, entity_profile, compare_entities. It also explains calling with or without the topic parameter.

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 non-destructive and idempotent behavior. The description adds valuable context: ownership enforcement, soft deactivation (not deletion), and that historical events remain available via 'recent_alerts'. 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?

Two sentences, each providing essential information: action and ownership in the first, effect and relationship in the second. No unnecessary words; 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?

For a simple tool with one parameter and no output schema, the description covers the action, constraints, side effects, and ties to related tool 'recent_alerts'. It is complete enough for an AI agent to understand and invoke correctly.

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

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

The only parameter 'id' is fully described in the schema with 'Subscription id (uuid) returned by subscribe.' The description does not add further semantic information beyond the schema, so it meets the baseline for high schema coverage.

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

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

The description clearly states 'Cancel a subscription by id' with the title specifying 'Unsubscribe from Alerts'. It uses a specific verb and resource, and implicitly distinguishes from sibling tools like 'subscribe' and '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 includes ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation not deletion) and relation to 'recent_alerts'. It provides context for appropriate use but does not explicitly mention when not to use this tool versus 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 (readOnlyHint, idempotentHint, etc.) are complemented by description details on return values (verdict types, citation, percent delta) and domain limitations. 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 structured with a trigger phrase list, purpose statement, usage guidelines, domain scope, and return details. Slightly verbose but every sentence contributes meaningful information.

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

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

Despite no output schema, the description adequately explains the verdict types and returned data. It could mention error handling or unsupported claim types, but for a single-parameter tool with clear domain, it is reasonably complete.

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

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

The schema has 100% coverage with a well-described 'claim' parameter. The description adds value by clarifying the natural language expectation, providing examples, and explaining the processing pipeline (NL parsing, entity resolution, etc.).

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 verifies natural-language claims against authoritative sources, with specific examples and domain (company-financial claims). It differentiates from sibling tools like deep_research by focusing on factual verification with a verdict.

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 guidance ('Use whenever the agent needs to check whether something a user said is factually correct') and mentions it replaces multiple sequential calls. However, it lacks explicit when-not-to-use or comparison to all siblings, though the domain and function are clear.

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