Usgs Volcano

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining the per-model return structure (score, confidence, signals, raw_response) and combined view, and clarifies that Anthropic calls require a BYO key and direct payment, which are behavioral traits beyond annotations.

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

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

The description is a single, well-structured paragraph that front-loads the primary purpose and then efficiently covers details. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description enumerates the key return fields and combined view. Parameters are fully covered. It mentions use cases but could more explicitly address error handling, rate limits, or data freshness. Overall, it provides sufficient context 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%, so baseline is 3. The description adds meaning by explaining the default model, the conditional need for _apiKey, and how 'context' helps disambiguate entities, going beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It specifies the default model and the option to use Anthropic with an API key, and distinguishes itself from siblings by focusing on multi-model visibility scoring for brand audits.

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 frames usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also notes when to provide the _apiKey for Anthropic. However, it does not explicitly state when not to use this tool or provide direct comparisons to siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds value by disclosing routing behavior (picks from 5,563 tools), argument filling, return of structured answers with stable citation URIs, and that it works on every tier in one fast call. The only gap is no mention of rate limits or what happens on failed lookups. With strong annotation coverage, the additional context justifies a 4.

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 yet efficient, front-loading the most critical guidance ('PREFER OVER WEB SEARCH') and then detailing what the tool does. Every sentence serves a purpose—explicit usage boundaries, examples, sibling differentiation, and tier/account context. It could be slightly shorter by trimming repeated domain lists, but it is well-structured and 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?

Given the tool's high complexity (6 parameters, 1 required, wide domain coverage, many sibling tools, no output schema), the description fully equips an agent to invoke it correctly. It covers purpose, usage scope, alternatives, input format, return format, and tier compatibility. The schema covers all parameters, and the description compensates for the lack of output schema by describing the 'structured answer with stable citation URIs'.

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 meaning by clarifying that the question should be in natural language and can include aliases (query, q, prompt, text, input). However, the schema already documents all properties well. The description does not provide additional parameter semantics beyond what the schema offers, so it stays at baseline 3.

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

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

The description specifies a broad verb ('ask' / 'route') and a clear resource ('current or historical data' from '5,563 tools across 1462 verified sources'), and explicitly distinguishes it from sibling tools like ask_pipeworx_grounded and deep_research by stating when to use each. The name 'ask_pipeworx' could be vague alone, but the description provides enough specificity to stand apart.

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 'PREFER OVER WEB SEARCH' guidance, lists when to use (factual questions about real-world entities), and names alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions, breaking-news for 'what's the world saying'). Also clarifies 'START HERE' as default and gives concrete example queries. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: that the tool has candidate routing improvements live, that it currently matches ask_pipeworx due to no active candidate, that it is a full working router (not a fallback), and that its results are used for merge decisions. 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 relatively concise at two sentences plus a fallback note. It front-loades the beta identity and router equivalence. Some redundancy (e.g., 'same 5,563 tools, same arguments, same response shape' could be more concise) prevents a perfect score.

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

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

Given the tool's simplicity (single required parameter, all aliases), the presence of annotations, and its role as a beta variant of a known tool (ask_pipeworx), the description is fully adequate. It explains the purpose, current state, usage guidance, and behavioral specifics for an experimental tool.

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

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

Schema coverage is 100% with descriptions for all six parameters (all aliases for question). The description does not add meaning beyond stating that the arguments are identical to ask_pipeworx. With full schema coverage, baseline of 3 is appropriate.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,563 tools and arguments. It distinguishes itself as the experimental edge version for testing routing improvements, contrasting with the stable sibling tool.

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

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

Explicitly tells when to use this tool: 'Use it exactly like ask_pipeworx when you want the newest routing.' It explains that results are compared against the stable router to decide merges, and notes that currently no candidate is active so it matches ask_pipeworx exactly. This provides clear guidance on selection.

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

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

Despite annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds critical behavioral traits: it reveals the internal routing mechanism against 5,563 tools across 1462 sources, specifies the return structure including refusal reasons, and explicitly states the cost impact (one 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 remarkably concise yet packed with actionable information: what it does, how it differs, when to use it, what it returns, and cost trade-offs. Every sentence serves a clear purpose with no redundancy.

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

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

Given the parameter count (6, all aliases), full schema coverage, no output schema, and the complexity of a hallucination-resistant tool with multiple refusal modes, the description is complete. It explains the return structure and refusal reasons, though without an output schema the agent must infer exact types from the description text.

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

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

Schema coverage is 100% and the schema already describes all six alias parameters well. The description adds marginal value by confirming the question is in natural language, but does not add details about length limits or formatting. Baseline 3 would be too low given the schema covers everything; a 4 acknowledges the small extra clarity.

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 'Hallucination-resistant answer mode for high-stakes reads' and explains the extraction process. It differentiates from the sibling ask_pipeworx by specifying that it returns grounded answers with evidence and explicit refusals, and notes the cost difference.

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

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

The description explicitly mentions when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also provides concrete domains where it's appropriate (financial verdicts, legal claims, medical lookups, public statements).

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, destructiveHint) by detailing classifier types, fan-out examples, response shapes, resolver contract, parent event extractor, news fields, safety checks, and edge cases like closed markets and resolution-rule risk. There is no contradiction with annotations.

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

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

The description is extremely long and dense, covering many scenarios in a verbose wall of text with capitalized sections. It front-loads the main purpose but lacks efficient structuring. While thorough, the verbosity hampers quick comprehension for an AI agent.

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

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

Given the lack of output schema, the description thoroughly explains return values, including market_match_confidence, parent_event extraction, news fields, and safety mechanisms. It covers edge cases like closed markets, wide spreads, and resolution-rule risk. The description is complete for a research 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% for all three parameters, so the schema already documents them well. The description adds some context (e.g., default for depth, recommendation for include_raw), but the main value is in overall behavior rather than parameter semantics. Baseline 3 is appropriate.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet, market-vs-model comparison). The purpose is distinct from sibling tools like polymarket_arbitrage or polymarket_edges, as it is the go-to for single bet 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?

The description explicitly provides usage cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It gives numerous examples of fan-outs for different bet types, offering clear context. However, it does not explicitly state when not to use this tool or mention alternatives, though the context implies it as the primary research 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?

Description adds rich behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), sorting by primary metric, citation URIs, and off-calendar fiscal year handling.

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 verbose but well-structured with examples, usage guidance, data sources, and value proposition. Each sentence adds value, though could be slightly more concise.

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

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

Covers input specification, behavioral details (parallel call, sorting), output format (paired data + citation URIs), and data sources, making it complete for a tool with 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 has 100% coverage with descriptions, but the description adds meaning by specifying the exact data fields returned for each entity type (e.g., revenue, net income for companies; adverse event counts for drugs).

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

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

The description explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' and contrasts with sequential single-pack lookups, clearly differentiating 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?

Includes 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and example queries, but does not explicitly exclude single-entity use cases.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds rich behavioral detail: decomposition into facets, parallel routing to 5,563 tools, return structure (findings packet with evidence, confidence, gaps, contradictions), timing (15-90s), iteration logic for standard/thorough, and citation_uri conditions. No contradictions with annotations.

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

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

The description is long but front-loaded with critical information (account requirement, alternative). All sentences add value given the tool's complexity, though some details (e.g., hop field, citation_uri conditions) could be more tightly integrated. Still highly effective and not padded.

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 covers what the agent needs: account/plan requirements, input semantics, decomposition/parallel processing, output structure (findings, gaps, contradictions, citations), timing, iteration behavior, and source type. No gaps in context for correct invocation.

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

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

Schema has 100% coverage (both parameters described). The description adds significant value beyond schema: explains depth enum values in full (quick=3 facets, standard=5 with gap recovery, thorough=8 paid), clarifies that question can be natural language and multi-part, and notes the paid plan constraint for 'thorough'.

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 grounded multi-source research across structured data sources using parallel tools, and distinguishes itself from siblings like ask_pipeworx by targeting broad/multi-part questions over structured data. Examples and explicit exclusions (e.g., not open-web search) make the purpose precise.

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?

Exceptional guidance: explicitly states when to use (broad/multi-part structured questions), when not to (single lookup → ask_pipeworx, breaking news → ask_pipeworx), and provides fallback (if not signed in, use ask_pipeworx). Also mentions paid plan requirement for 'thorough' depth.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false; the description adds that it returns top-N tools with full schemas and examples ready to call. No contradiction, but could mention aliases or rate limits.

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

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

The description is concise, well-structured, front-loaded with purpose, and every sentence adds value without verbosity.

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 discovery tool, the description adequately covers what it returns (names, descriptions, schemas, examples) and when to call it. No output schema is necessary for this purpose.

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

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

Schema coverage is 100% and the description adds useful alias info (task, q, description, search) beyond the schema, providing extra clarity on how to invoke the tool.

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 'Find' and the resource 'tools', and distinguishes from sibling tools by being a discovery tool for browsing available tools.

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

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

The description explicitly says when to use it ('when you need to browse...') and advises to call it first when many tools are available, but does not explicitly state when not to use it or list alternatives.

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

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

Annotations already indicate idempotent, read-only, non-destructive, open-world. Description adds useful context: fans out across multiple sources, patents section soft-fails until USPTO API reactivation (May 2025), and uses GDELT→GNews fallback for news.

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?

All sentences are informative with no fluff. Front-loaded with trigger phrases and purpose, then detailed breakdown of what the tool returns. Efficient and well-structured.

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

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

Despite no output schema, description comprehensively lists all returned data: cik, company_name, recent_filings with URIs, fundamentals with specific fields and sort order, patents (with caveat), news fallback, and LEI. Covers all aspects for a holistic profile tool.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. The tool description restates the same info (ticker/CIK, 'names not supported') but adds minimal new value. Baseline 3 with slight reinforcement.

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's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides trigger phrases and distinguishes from sibling tools by noting it should be preferred over chaining individual lookups.

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

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

Explicitly states when to use: 'when the user asks for a holistic view.' Provides alternatives: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' Also notes limitations: names not supported, use resolve_entity first.

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 destructiveHint=true and readOnlyHint=false, so the description's 'Delete' aligns but adds little beyond stating the obvious. It provides context about clearing sensitive data, which is minor additional insight.

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

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

Two sentences, front-loaded with the action, no wasted 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?

Given a single parameter, annotations, and no output schema, the description fully covers purpose, usage, and data sensitivity. No gaps.

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

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

Schema coverage is 100% with a clear description for the single 'key' parameter. The description's 'by key' adds no new information beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the action ('Delete') and resource ('previously stored memory by key'). It also distinguishes from sibling tools by mentioning 'remember' and 'recall'.

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

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

The description provides explicit use cases: when context is stale, task is done, or to clear sensitive data. It pairs with remember and recall, indicating alternatives, but lacks explicit when-not-to-use instructions.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds that it fetches an external page and extracts content, which is useful behavioral context. However, it does not disclose potential side effects like rate limiting or error handling, keeping the score at 3.

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

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

The description is two sentences long, front-loads the core purpose, and includes specific examples of use cases without any wasted 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?

The description explains what is extracted (title, description, key links) and the output format (single text blob, ready to drop at site-root/llms.txt). With no output schema, this is adequate. Slightly more detail on edge cases or format structure would be needed for a 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 description coverage is 100%, so the schema already documents both parameters adequately. The description adds no extra semantic information beyond what the schema provides, resulting in a baseline score of 3.

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

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

The description uses a specific verb+resource ('generate a production-ready llms.txt file for any URL') and clearly distinguishes the tool from siblings by focusing on AI crawler indexing. No sibling does the same task.

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

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

The description explicitly lists three use cases (client indexing, own project drafting, competitor auditing), providing clear context for when to use. It does not state negatives or alternatives, but the use cases are sufficient.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint. Description adds 'smallest practical fingerprint' hinting at lightweight nature, but no contradictions. Adequate but minimal extra value.

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

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

Two sentences, no waste, front-loaded with key information. Every word earns its place.

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

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

No parameters, output schema exists, description fully explains return content. Complete for a simple filtered list tool.

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

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

No parameters; schema coverage 100%. Description adds context about what is listed (elevated status) beyond schema, meeting the baseline for zero parameters.

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

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

The description clearly states it lists volcanoes above Normal/Green status, with verb 'list' and specific resource. Distinguishes from siblings like list_volcanoes by focusing on elevated status 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?

Implicitly indicates used for a quick snapshot of current unrest. Does not explicitly state when not to use, but context of sibling tools and clarity of purpose compensate.

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 thoroughly describe safety (readOnlyHint, idempotentHint, etc.). Description adds temporal context ('recent') and content specifics (observatory updates, VAN, VONA) which go slightly beyond annotations, but lacks details on data freshness, limits, or response format.

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

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

Description is a single, well-structured sentence that front-loads key purpose and capabilities. No unnecessary words or repetition.

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 list tool with optional filters, full schema coverage, and an output schema (implied), the description is sufficient. It clearly explains what notices are retrieved. Could slightly improve by noting that output is textual or structured, but not required.

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

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

Input schema has 100% description coverage for both parameters (limit, volcano_slug). Description mentions filtering by volcano slug but adds no new meaning beyond what schema provides. Baseline 3 is appropriate.

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

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

Description clearly identifies the tool as listing recent USGS volcano notices and reports, specifying types (VAN, VONA) and filter capability by volcano slug. This distinguishes it from sibling like 'list_volcanoes' and other query tools.

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

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

Description implies usage for retrieving volcano notices, but does not explicitly state when to use this tool versus alternatives (e.g., 'recent_alerts'), nor does it provide exclusions or context for selection. Usage is inferred but not guided.

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 returns specific fields and defaults to active subscriptions, plus scope ('caller's'). No contradiction.

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

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

Two sentences covering purpose, return fields, and usage guidance. No excess words.

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

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

Given no output schema, description fully explains what is returned. Also mentions default behavior and usage context. Complete for a simple list tool.

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

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

Schema coverage is 100%, so baseline 3. Description doesn't explicitly describe the include_inactive parameter, but the schema already covers it adequately.

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

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

Clearly states 'List the caller's active subscriptions' and lists return fields. Distinguishes from siblings like subscribe, unsubscribe, and list_elevated.

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 it 'to review what you're monitoring before adding more or to find an id to cancel'. Implies context but doesn't specify when not to use.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by specifying the exact scope ('every US volcano monitored by USGS') and the data fields returned, giving the agent useful behavioral context beyond the annotations.

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

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

Two succinct sentences: the first conveys the core purpose and output, the second the optional filter. No redundant words, and key information is front-loaded, achieving excellent conciseness.

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

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

Given the simple tool (1 optional param, full schema, comprehensive annotations, and an output schema), the description covers the scope, filter, and returned data adequately. Nothing essential is missing for agent invocation.

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

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

Schema coverage is 100%, so the schema fully documents the 'observatory' parameter. The description merely restates the filter option without adding new details, meeting the baseline but not exceeding it.

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 action ('List'), the resource ('every US volcano monitored by USGS'), and the specific data included (alert level and aviation color code). It also mentions the optional filter, making the tool's purpose precise and distinguishable from unrelated sibling tools.

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

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

The description explains what the tool does but provides no guidance on when to use it versus alternatives. While siblings are in different domains, the description does not explicitly state usage context or exclusions, limiting its helpfulness for selection.

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

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

Annotations are uninformative (all false), so the description carries the full burden. It discloses key behaviors: return of a claim_token when filing without an account, later retrieval via claim_token, rate limiting ('5 per identifier per day'), quota impact ('doesn't count against your tool-call quota'), and team review cadence. It also provides content guidance ('don't paste the end-user's prompt'). This goes beyond what annotations offer.

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

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

The description is a single dense paragraph, front-loaded with the core purpose. It is longer than the calibration examples but every sentence contributes operational detail (scope, exclusions, token flow, rate limits). It could be slightly tightened by separating usage rules, but it remains efficient and well-ordered.

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 4-parameter tool with no output schema and uninformative annotations, the description is comprehensive. It covers the tool's purpose, usage criteria, exclusions, claim token lifecycle, rate limit, quota impact, team response, and content guidance. There are no significant gaps; it fully equips an agent to select and invoke the tool correctly.

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

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

The schema covers all parameters with descriptions, but the tool description adds meaningful semantics, especially for claim_token: it explains the two-step flow (filing returns a token, then passing it back later to read status). It also gives practical guidance on message length ('1-2 sentences typical') and context structure. This enriches the schema definitions, though the schema already provides solid coverage.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and distinguishes itself from sibling tools by focusing on feedback versus asking/research tools. It also clarifies scope ('ONLY for tools served by this Pipeworx connection').

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

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

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an exclusion (different MCP server) and how to disambiguate ('Pipeworx tool names are the ones this connection lists'), fully guiding tool selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: caching (5min-1h), data source (CF analytics-engine), privacy (no PII), and data structure (pack, tool, count). No contradictions.

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

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

Two concise sentences plus a bulleted list of use cases. Front-loaded with the main output, no redundant 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?

Despite no output schema, the description fully explains what is returned (top tools, packs, volume), includes caching info, data source, and privacy. With one optional parameter, the description covers all necessary context for correct invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description goes beyond by explaining that shorter windows surface what's hot and longer windows show steady-state demand, adding practical context for parameter selection.

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

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

The description uses a specific verb 'returns' and clearly states the resource: top tools, top packs, and total call volume over recent windows. It distinguishes itself from siblings by focusing on trending/aggregated data rather than specific queries.

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

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

Provides three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) and explains when to use shorter vs longer windows. However, it does not explicitly state when not to use 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?

The description adds extensive behavioral context beyond annotations: semantic anchor (≥0.30 Jaccard similarity), partition filter (placeholder fraction >20% returns null), and fill check against live CLOB depth. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is lengthy but well-structured with clear sections for each mode, thresholds, and response details. While it could be slightly trimmed, every sentence adds necessary context for a complex tool.

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

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

Despite no output schema, the description fully specifies the response structure (opportunities array, partition_check fields, fill_check results). It covers modes, algorithms, thresholds, and edge cases (e.g., placeholders, low similarity), making it comprehensive.

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

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

Schema coverage is 100% with parameter descriptions. The description significantly enriches this by explaining the difference between event and topic modes, providing example values, and detailing the algorithmic behavior for each parameter.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It specifies three distinct modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk, which serve different purposes.

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

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

Explicit guidance is given for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It also references when to use polymarket_fill_risk for custom sizing, providing clear alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral details: caching (1h at KV level), model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation (net of slippage, Kelly sizing), safety checks (24h move warning), and tradeable-edge filters. No contradiction with annotations.

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

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

Description is very long with many detailed enumerations (model families, alpha values, exact filter thresholds). While comprehensive, it could be more concise without losing key information. Front-loads purpose but then dives into specifics that might overwhelm an agent.

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

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

Given high complexity (9 params, no output schema, nested response logic), the description thoroughly explains the response structure (by_segment with three categories, fed_candidates, diagnostics), caching, model details, edge components, and knob effects. Covers caching, reliability notes, and why certain segments may be empty.

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

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

Input schema has 100% coverage with descriptions for all 9 parameters. The description further enriches understanding: e.g., slippage_pp explains Polymarket zero fees but bid/ask costs, min_partition_leg_kelly explains why it is needed for partition arbs. Adds meaning beyond schema.

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

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

Description clearly states it scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, with explicit use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by being a discovery tool that doesn't require paging through hundreds of markets.

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

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

Provides explicit context for use (discovery, Fed bets excluded, need paid data for reliable signals) and guidance on knobs like min_liquidity and max_spread_pp. Explains when segments might be empty and how to interpret diagnostics. Lacks explicit 'do not use when' versus siblings, but is otherwise strong.

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

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

Annotations declare readOnly, idempotent, non-destructive. Description adds detailed behavior: reads daily snapshots, returns tracked/expired/snapshot_dates, explains decay computation. Provides behavioral context beyond annotations without contradiction.

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

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

Description is dense but well-structured: starts with purpose, then details response format, then limits. Each sentence adds value. Could be slightly more concise, but not wasteful.

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

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

No output schema, but description fully explains response structure (tracked, expired, snapshot_dates) and computed fields. Complete for a complex tool with no output schema.

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

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

Schema coverage is 100% with clear descriptions. Description does not add new meaning beyond default values and context already in 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 it provides edge persistence and decay telemetry from polymarket_edges snapshots, answering a specific question about edge duration. This distinguishes it from siblings like polymarket_edges (which likely provides raw edges) and 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?

Gives explicit context: answers 'how long has this edge existed and is it shrinking?', contrasts fresh vs old edges. Includes limits about TTL and decay computation. Does not explicitly state 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?

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, which are consistent with the description. The description adds rich behavioral context: walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and for basket mode theoretical_sum vs realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk. 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 detailed but well-structured with clear sections for mode descriptions, input requirements, and return values. Every sentence adds value, though slightly verbose (e.g., lists many return fields). It could be marginally more concise, but no critical waste.

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

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

Given the tool's complexity (two modes, multiple return fields, no output schema), the description is highly complete. It explains both modes, input parameters, output fields, and usage context. It covers edge cases like forced_directional_risk and thin_legs. The only minor gap is not explaining 'forced_directional_risk' in detail, but it's still sufficient for an agent.

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

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

Schema description coverage is 100%. The description adds significant value beyond the schema: explains default values (side default buy_yes for single, auto for basket; size_usd default 1000), clamping range (10-1,000,000), and how parameters are interpreted in different modes (e.g., size_usd as spend vs target proceeds for single-market; as settlement notional for basket).

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

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

The description clearly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly differentiates from siblings by specifying 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'.

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

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

The description provides explicit when-to-use guidance, stating 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale: theoretical overround on thin books is not capturable and partial basket fills convert an arb into an unhedged directional position. It implicitly references sibling tools (polymarket_arbitrage, polymarket_edges) as alternatives.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds significant behavioral detail: compatibility warnings for mismatched bet shapes, temporal alignment checks, and skipped cross types. No contradiction with annotations.

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

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

The description is verbose but well-structured: purpose first, then modes, then response fields, then safety. Every sentence adds value, but some redundancy exists (e.g., repeated warnings). Still appropriate 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 no output schema and 3 parameters, the description thoroughly covers modes, response structure (spread, top_spreads_pp, compatibility_warning, temporal_alignment), and edge cases. It is complete enough for an AI agent to use effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how parameters interact (topic override by explicit tickers) and provides examples. It does not detail the response schema beyond spreading, but given high coverage, a 4 is warranted.

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

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

The description clearly identifies the tool as a cross-venue spread between Kalshi and Polymarket, with a specific verb ('compute spread') and resource ('same resolving question'). It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on venue comparison.

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

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

Explicitly describes two modes (topic shortcuts vs explicit tickers) and when each is appropriate. It warns that most pre-mapped topics return compatibility warnings and that real spreads are rare, guiding the agent away from 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 readOnly and idempotent; description adds scoping detail (anonymous IP, BYO key hash, account ID) and behavior when key omitted. No contradictions.

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

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

Three concise sentences with no wasted words. Front-loaded with core functionality.

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 tool with one optional parameter and no output schema, description covers purpose, scoping, and relationships. Lacks details on return format but acceptable.

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

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

Schema coverage is 100%, and description adds explicit note that omitting key lists all keys, which is already implied but usefully reinforced.

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 retrieves a value saved via remember or lists all keys when omitted. Provides concrete examples like ticker or address. Distinguishes from siblings remember and forget.

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

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

Explicitly says to use for retrieving context stored earlier and to pair with remember/forget. Does not mention alternatives or 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?

Annotations already indicate read-only, idempotent, open-world. The description adds significant behavioral context: the mark_read parameter side effect (flags events read so next call only shows newer ones), and details about returned fields (source, citation_uri, raw payload), which goes beyond annotations.

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

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

Five sentences, no fluff. Front-loaded with the primary action and key fields. Every sentence serves a purpose: what it does, what data it returns, how to filter, how mark_read works, and alternative access method.

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 return values (source, citation_uri, raw payload). It covers filter parameters, side effects, and polling behavior. Minimal gaps for a read-only tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical usage hints: examples for type filtering (e.g., 'sec_8k'), ISO timestamp for since, and explanation of mark_read's effect. This adds value beyond the basic schema descriptions.

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

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

The description clearly states it pulls fired events from the subscription feed, returns recent alerts with key fields (source, citation_uri, raw payload), and specifies filtering options. It distinguishes the tool's purpose well among siblings like list_subscriptions or recent_changes.

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 context: polls work fine, and mentions an alternative HTTP endpoint for scripts/dashboards. However, it lacks explicit when-not-to-use guidance against sibling tools like list_subscriptions or recent_changes.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: parallel fan-out to three sources, GDELT→GNews fallback, USPTO soft-fail, relative date parsing, and output format (changes grouped by source, total_changes, citation URIs). No contradictions.

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

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

The description is a single dense paragraph but front-loaded with example queries and clear definitions. It is substantive without excess, though breaking into bullet points could improve readability.

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

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

Given no output schema, the description fully explains return values ('changes[] grouped by source + total_changes count + pipeworx:// citation URIs'), covers edge cases (fallback, soft-fail, relative dates), and provides sibling differentiation. Highly 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 the description adds meaning beyond the schema: explains 'since' with examples (ISO date or relative shorthand like '7d', '30d'), notes type only supports 'company', and describes the return structure in detail, compensating for the lack of output 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 uses specific verbs ('change feed') and resources ('company') and distinguishes from sibling tool 'entity_profile', which is for static profiles. It clearly states the tool provides a multi-source change feed (SEC, news, patents) for a given time window.

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

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

The description includes explicit example queries ('What's new with X', 'latest on Y') and clearly states when to use an alternative ('Use entity_profile instead when you want the static profile...'). It also describes fallback behavior (GDELT→GNews).

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 idempotent and non-destructive. Description adds that memory is key-value pairs scoped by identifier, with persistence details (authenticated vs anonymous sessions). 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?

Five sentences, front-loaded with purpose. Concise yet comprehensive without fluff. Could be slightly more structured but effective.

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

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

Given simple parameters, no output schema, and good annotations, the description covers storage mechanism, scoping, persistence, and pairing with siblings. No significant 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?

Input schema has 100% coverage with descriptions. Description adds key examples (e.g., 'subject_property') and value as any text, but does not fundamentally add beyond 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 saves data for later reuse across conversations and sessions. It provides specific use cases (resolved ticker, target address, user preference, research subject) and distinguishes it from sibling tools recall and forget.

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

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

Explicit guidance on when to use: 'Use when you discover something worth carrying forward.' Mentions pairing with recall and forget. No explicit when-not, but sibling tools are listed for context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true. The description adds significant transparency: it explains that the tool cascades through multiple lookup endpoints, degrades gracefully if external sources (GLEIF, OpenFIGI) are unavailable, labels identifiers with source, and lists unresolved identifiers explicitly. 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 relatively long but every sentence adds value. It front-loads with common query examples and key usage instruction. However, it could be slightly more structured (e.g., bullet points for the two types) to improve skimmability. Overall, no wasted text.

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

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

Given no output schema, the description fully explains what identifiers are returned for each entity type (CIK, ticker, LEI, FIGI, RxCUI, etc.) and covers edge cases (unresolved identifiers, degraded sources). For a complex multi-source resolving tool, this provides complete context for the agent to understand and trust the result.

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

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

Schema description coverage is 100% and defines the two parameters. The description adds substantial meaning: for the 'type' enum it details what each resolves, including callouts like 'cross-source identity spine' and 'graceful degradation'; for 'value' it gives concrete examples (AAPL, 0000320193, ozempic) and explains that ISINs resolve to legal entities via GLEIF mapping. This goes well beyond the schema's short 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 resolves names to canonical/official identifiers, listing specific query patterns ('What's the ticker for…', etc.) and explicitly saying 'Use FIRST whenever you have a name but need an ID.' It distinguishes itself from sibling tools that do other entity operations (compare_entities, entity_profile) by being the identity resolver.

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

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

It explicitly tells the agent to 'Use FIRST whenever you have a name but need an ID' and explains the two supported types (company, drug) with details on what identifiers each returns. While it doesn't list when not to use it or name alternatives explicitly, the context and sibling list imply it's the go-to resolver before other entity tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by explaining the internal process ('Probes each entity with ai_visibility_check') and the output structure ('ranked list with score, confidence, signal density per entity'), which goes beyond what annotations provide.

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

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

The description is three sentences: purpose, mechanism, and utility. It is front-loaded with the main action, and every sentence adds value without redundancy or verbosity.

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 rich annotations, full schema coverage, and no output schema, the description adequately explains the return format and internal logic. It covers the most important aspects for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, but the description adds meaningful context: the first entity is treated as 'subject for narrative' and models are explained with defaults ('workers-ai free default'). This clarifies usage beyond the raw schema.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It specifies the action (probe, rank, surface), the resource (AI visibility of entities), and distinguishes it from sibling ai_visibility_check by doing batch comparison.

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

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

The description provides a clear use case: competitive AI-marketing audits. It implies when to use (comparing multiple entities) but does not explicitly state when not to use it or mention alternatives like ai_visibility_check for single entities.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds critical behavioral details: external API calls (deps.dev, bundlephobia), potential 5-30s delay on first measurement, and graceful degradation with sources_failed field. No contradiction.

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

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

The description is comprehensive yet each sentence adds unique value. It starts with the main purpose, then usage, then limitations and return details. No redundant or unnecessary text.

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

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

Given the tool's complexity (composite external API calls) and lack of output schema, the description thoroughly explains the return format (summary block, per-advisory detail, links, alternative versions) and failure modes. It is complete for an agent to understand behavior.

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

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

Schema coverage is 100% and already describes both parameters. The description adds that scoped packages are accepted and version defaults to latest. This is helpful but not extensive, 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?

The description clearly states the tool's purpose: a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs like 'fans out' and lists exact checks. Even without similar siblings, the purpose is unambiguous.

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

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

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also states NPM-only and directs users to deps.dev for other ecosystems. This clearly delineates when and when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context: embedding model (BGE-base-en), similarity measure (cosine), chunking strategy (500-char overlapping windows), and character limit (200K chars with truncation flag). This fully informs the agent of internal behavior beyond annotations.

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

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

The description is concise (4-5 sentences), front-loaded with purpose, and each sentence adds value. No redundant information; covers purpose, usage, technical details, and limitations efficiently.

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

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

Despite no output schema, the description explains return values (passages with offsets and scores), behavior limits, and example usage. It fully covers what an agent needs to know 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% with detailed descriptions for all three parameters. The description does not add significant meaning beyond what the schema already provides, though it contextualizes usage. 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 performs semantic search inside a fetched record, specifying the verb 'search inside' and the resource 'fetched record'. It distinguishes itself by explaining when to use it (when the record is too large for the prompt) and mentions a complementary sibling tool (ask_pipeworx_grounded).

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

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

Explicitly tells when to use the tool: 'Use when the record is too big to cram into the prompt'. It also pairs with ask_pipeworx_grounded, providing a clear workflow alternative. This gives strong context for agent decision-making.

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

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

The description adds significant behavioral context beyond annotations, including SMS delivery cap (10/day), webhook auto-disable after 10 failures, and one-time signing secret. 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 well-structured: purpose first, then prerequisites, then types with examples, then delivery details. Every sentence adds value, and it remains concise despite covering complex behavior.

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

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

Despite no output schema, the description covers parameter details, behavioral constraints, error scenarios (auto-disable, verification), and return value. It is fully self-contained for an AI agent to 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 description enriches each parameter with concrete examples (e.g., sec_8k items codes, polymarket_edge topics, delivery channel details) and constraints not present in the schema, such as phone verification requirement.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, returns the new subscription ID, and distinguishes from sibling tools like list_subscriptions 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?

The description specifies prerequisites (Pipeworx OAuth account) and lists supported types with examples. However, it lacks explicit guidance on when not to use or alternatives like list_subscriptions for existing subscriptions.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds context about returning example questions from a live catalog of thousands of tools, and the format of the response (category-bucketed with exact tool+argument shapes). 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 somewhat lengthy with many example user queries at the start, but each part serves a purpose. Could be more concise without losing clarity.

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

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

For a simple discovery tool with no required parameters and no output schema, the description is highly complete. It covers purpose, when to use, parameter details, and behavioral 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?

Only one parameter 'topic' with 100% schema coverage. Description adds value by listing example topic values and explaining the default behavior (omit for cross-category spread), which is beyond the schema.

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

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

The description clearly states the tool's purpose as the onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It distinguishes itself from sibling tools like 'ask_pipeworx' by specifying it's for exploring capabilities, not for direct answers.

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

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

Explicit guidance to use this tool first when unfamiliar with Pipeworx capabilities, or to learn how to call meta-tools. Provides optional topic filtering but does not explicitly state when not to use it.

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

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

The description discloses that the row is deactivated (not deleted) and historical events remain accessible via 'recent_alerts'. This adds critical behavioral context beyond annotations, which only hint at idempotency and non-destructiveness.

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

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

Two concise sentences that front-load the primary action and quickly cover constraints and side effects. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, constraints, and downstream effects, making it self-sufficient for an AI agent.

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

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

The single parameter 'id' is already well-described in the schema as a uuid returned by subscribe. The description adds no further semantic details beyond 'by id', so it meets the baseline for 100% 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 states 'Cancel a subscription by id', clearly specifying the action (cancel), resource (subscription), and method (by id). This distinguishes it from the sibling 'subscribe' tool.

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

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

It explicitly notes ownership enforcement ('you can only cancel your own subscriptions') and links to 'recent_alerts' for viewing history after deactivation. This provides clear guidance on when to use and what to use afterwards.

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?

Even though annotations already mark readOnlyHint=true and destructiveHint=false, the description adds substantial behavioral context beyond annotations: it explains the special meaning of verdicts (could_not_verify means the check did not happen and must not be treated as evidence; unsupported means no source covers it), describes the return payload (verdict, actual value with citation, reasoning), and outlines the fallback routing logic. No contradictions with annotations.

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

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

The description is long but appropriately dense. It front-loads concrete example queries, then states the use case, then details behavior, return format, edge cases, and performance benefits. Every sentence earns its place; there is no fluff or redundancy.

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

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

Despite having no output schema, the description fully explains the return value (verdict, actual value with citation, reasoning), enumerates all possible verdicts, clarifies ambiguous outcomes, and covers error behavior (verification_error with stage/detail). It also gives parameter guidance and routing logic, making it complete for an agent to invoke the tool safely and interpret results correctly.

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

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

Schema description coverage is 100%, so both parameters are already described in the schema. The description adds extra semantics for tolerance_pct: that it overrides the implied tolerance, the recommended 1–2 range for hallucination detection, and the default behavior (implied by wording, capped at 5). This goes beyond what the schema provides and meaningfully helps the agent set the parameter correctly.

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

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

The description opens with natural-language triggers ('Is it true that…', 'fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. This clearly distinguishes it from siblings by positioning it as a consolidated tool that replaces 4–6 sequential calls, so the agent knows exactly what it does and why it exists.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' which is clear and actionable. It also explains the two routing paths (SEC EDGAR for company-financial claims, grounded pipeline for everything else). However, it does not explicitly mention when not to use it or name an alternative tool for non-verification research, so it stops short of a perfect score.

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