Virustotal

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds value by detailing return format (per-model {score, confidence, signals, raw_response} + combined view) and explaining billing implications for Anthropic probes. It does not cover rate limits or potential latency, but these are secondary.

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

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

The description is compact (three sentences) and front-loaded with the core purpose. No redundant information; 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 explains return format clearly. With 100% parameter coverage and comprehensive annotations, the description provides all necessary context for correct invocation.

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

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

Schema coverage is 100% and the description enriches each parameter: entity is described with examples, models lists supported values with defaults, _apiKey explains its pass-through nature and requirement, context adds disambiguation purpose. This goes beyond the schema definitions.

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

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

The description uses specific verb 'probe' and resource 'LLMs for what they know about a business / brand / product / topic' and clearly states it scores visibility per model. It distinguishes from siblings like scan_competitor_ai_presence by focusing on direct LLM probing rather than scanning.

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

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

The description provides clear usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring' and explains when to pass _apiKey for Anthropic. However, it does not explicitly state when not to use this tool versus alternatives.

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

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

Annotations already cover readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds useful behavioral context: it routes to thousands of tools, fills arguments, returns structured answers with citations, and is described as 'one fast call' that works on every tier. This goes beyond the annotations without contradicting them.

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

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

The description is long (7 sentences) but front-loaded with 'PREFER OVER WEB SEARCH' and each sentence provides distinct value: scope, mechanism, trigger phrases, examples, default status, alternatives. It is somewhat verbose but the content justifies the length for a default QA 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?

For a tool that can route to 5,529 tools, the description is remarkably complete: it covers use cases, triggers, alternatives, output format (structured answer with citations), and operational context (works on every tier, one fast call). No output schema exists, but the description explains enough about returns to set expectations. Missing failure modes are not critical here.

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 all 6 parameters (all aliases for 'question') with descriptions, so schema coverage is 100%. The description does not add further parameter-level semantics; examples appear in schema examples but not in the description itself. Baseline 3 is appropriate because the schema carries the full load.

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 routes questions to 5,529 tools across 1,455 verified sources and returns structured answers with stable pipeworx:// citation URIs. It explicitly distinguishes itself from ask_pipeworx_grounded and deep_research, so the agent knows exactly what this tool does and when to prefer it.

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

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

Usage guidance is explicit and thorough: it says 'PREFER OVER WEB SEARCH' for a long list of data types, defines trigger phrases like 'what is', 'look up', 'find', provides concrete examples, and explicitly states when to step up to alternatives ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also clarifies that breaking-news queries are handled by this tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds valuable operational context: enabled live under test, retired candidates, no fallback (full working router), and comparison behavior. This goes beyond annotations without contradicting them.

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

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

The description is a single paragraph that is information-dense but efficient. Each sentence adds distinct value: beta status, identicality, usage guidance, and fallback behavior. The inclusion of a specific date and parentheses is slightly cluttered but not enough to lower to 3.

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

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

Given the tool's complexity (a universal router to thousands of tools) and the absence of an output schema, the description adequately covers what it is, its current state, and how to use it. It references the response shape of ask_pipeworx, which is acceptable since that sibling exists, but it does not explicitly state what the response contains beyond that.

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

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

Schema description coverage is 100%, with all six parameters (one required plus five aliases) clearly described as aliases for 'question.' The description itself does not discuss parameters, but the schema fully explains their meaning, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a beta universal router with access to the same 5,529 tools and same arguments as ask_pipeworx. It explicitly differentiates from the stable ask_pipeworx sibling by describing its role as an experimental edge for testing candidate routing improvements.

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?

Directly instructs when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' Also explains the evaluation context (results compared against stable router) and notes that no candidate is active, so it currently matches ask_pipeworx exactly, providing honest usage 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?

Goes well beyond the annotations (readOnlyHint, idempotentHint) by describing the actual extraction process (ONLY tool result content), the detailed refusal reasons (not_in_source, no_tool_match, etc.), the return structure with evidence and confidence, and the extra LLM call cost. This provides critical transparency about failure modes and limitations.

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

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

The description is dense but every sentence earns its place: purpose, behavior, return/refusal formats, use cases, and cost comparison. It is front-loaded with the key concept and uses structured lists (refusal reasons) for clarity without unnecessary fluff.

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

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

Given the tool's complexity and the absence of an output schema, the description fully covers the return contract (success and failure), practical use cases, relationship to sibling tool, and cost implications. It is complete and self-sufficient for an agent to understand when and how to invoke it.

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

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

Schema coverage is 100%, with all 6 parameters being aliases for 'question' and fully described in the schema. The description does not add parameter-level semantics beyond stating that the tool 'fills arguments' and accepts a question, but given the schema's thorough coverage, this is sufficient. 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 'Hallucination-resistant answer mode' for 'high-stakes reads', with a specific verb ('EXTRACTS') and resource (routing across 5,529 tools/1455 sources). It also distinguishes itself from sibling 'ask_pipeworx' by highlighting the grounded extraction behavior and refusal mechanism.

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

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

Explicitly states when to use ('Use whenever an answer will be quoted, cited, or acted on...') and when not to ('prefer ask_pipeworx for casual lookups'). Also references the sibling 'ask_pipeworx' as an alternative, making the decision 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?

The description extensively discloses behavioral traits beyond annotations: fan-out process, response shapes (market, analysis, evidence), resolver contract with confidence levels, parent event extraction, news fallback handling, safety mechanisms (low-confidence short-circuit, closed market handling, wide-spread tradeability), and resolution-rule risk. This far exceeds annotation coverage (readOnlyHint, openWorldHint, idempotentHint) and provides rich behavioral context.

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

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

The description is long but well-structured with sections (e.g., RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR) that each earn their place given tool complexity. Core purpose is front-loaded. Minor redundancy (e.g., repeating low_confidence_match explanations) could be trimmed, but overall it's appropriate for the tool's sophistication.

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 (3 parameters, no output schema, rich behavioral nuances), the description is remarkably complete. It covers input formats, classifiers, fan-out examples, all response fields, resolver confidence handling, parent event extraction, news fallback, safety edge cases, liquidity warnings, and cancellation rules. No critical gaps for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with all three parameters described. The description adds significant value by providing examples for 'market' (slug, URL, question text), explaining 'depth' enum values (quick vs thorough) with default, and clarifying 'include_raw' default behavior and use cases. This enhances understanding beyond the schema definitions.

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

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

The description clearly states 'Research a Polymarket bet' with specific verb+resource and details the tool's process: pulling Pipeworx data, resolving market, classifying, fanning out, and returning evidence. It distinguishes from sibling tools by its focus on Polymarket bets with detailed classifier and fan-out examples, making its purpose unambiguous.

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

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

The description explicitly states when to use the tool with examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It provides context on input formats (slug, URL, question text) and mentions classifiers, but does not explicitly exclude alternatives or mention when not to use it compared to sibling tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds rich behavioral details: pulls specific financial data from SEC EDGAR/XBRL, handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and replaces many sequential lookups. No contradictions.

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

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

Concise at ~120 words, front-loaded with query examples. Every sentence adds value. Could be slightly reduced but is efficient.

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

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

No output schema, but description explains return format (paired data + citation URIs) and sorting. Covers all essential aspects for a 2-param tool. Adequately 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 covers 100% with descriptions, but description adds context: type='company' pulls 10-K data, type='drug' pulls FAERS data; values are tickers/CIKs or drug names. This adds value beyond the schema enum.

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

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

Description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific query examples. It distinguishes from siblings like entity_profile (single entity lookup). Verb 'compare' and resource 'entities' are explicit.

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 recommends over sequential single-pack lookups. Explains when to use company vs drug type and what data each pulls. Does not explicitly state when not to use, but context implies for single entities use other tools like entity_profile.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses extensive behavioral details: results include findings packets with verbatim evidence, confidence, source, fetched_at, stable citations, gaps[] (never invented), contradictions[] for standard/thorough, hop fields, semantic excerpting rather than head-truncation, second-hop iteration mechanics, and latency expectations (15-60s, up to 90s). This fully informs the agent of the tool's behavior and output characteristics.

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 front-loaded with critical information (account requirement first, then core purpose, then usage guidance, then mechanics and latency). Every sentence adds value, though the density is high. It could be slightly more concise, but for such a complex tool, the length is justified.

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

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

Given the tool's complexity (multiple depth levels, parallel tool routing, output packet structure, gaps/contradictions, citation URIs, timing), the description covers all essential aspects comprehensively. It explains the full operational model, return behavior, and constraints, leaving no major gaps for an agent to make incorrect assumptions.

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

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

The schema already fully describes both parameters (question and depth) with 100% coverage. The description adds further meaningful semantics by explaining how depth values map to facet counts (quick=3, standard=5, thorough=8), what each depth level does (gap recovery, contradiction scan, iterative hops), and notes the paid plan requirement for thorough. This goes beyond the schema's basic enum 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 performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with a specific verb (research) and resource (structured data). It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, which is for single lookups.

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

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

The description provides explicit usage guidance: 'Best for broad/multi-part questions over structured data' and contrasts with 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx'. It also notes the account requirement and suggests an alternative for unsigned users, giving clear when-to-use and 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 indicate read-only, idempotent, non-destructive. Description adds that it returns top-N relevant tools with full input schemas and curated examples, ready to call directly, enhancing transparency 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?

Well-structured with front-loaded verb 'Find tools by describing the data or task', followed by use cases and return format. Every sentence adds value; no redundancy.

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

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

Complete for a discovery tool: explains purpose, usage, return format (names, descriptions, schemas with examples), and integration guidance. Output schema not needed.

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

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

Schema coverage 100%; description adds context on natural language input, multiple aliases (task, q, description, search), and provides examples, going 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 finds tools by describing the data or task, lists many specific examples, and distinguishes itself from sibling tools by being the discovery entry point.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use guidance and implying when not to.

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, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it makes one parallel call, describes the specific data sources (SEC, XBRL, USPTO, GDELT, GLEIF) and returned fields, notes a patent API sunset and soft-fail behavior, and gives full detail on how it operates 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 lengthy and dense, containing a lot of specific detail (e.g., URIs, exact data fields). While front-loaded with example queries, it could be more concise and structured to improve readability. Not all details are necessary for an agent to invoke the tool correctly.

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

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

Given only 2 parameters, high schema coverage, and no output schema, the description fully covers what the tool does and what it returns (cik, company_name, recent_filings, fundamentals, patents, news, LEI). It provides complete context for an agent to understand inputs and expected outputs.

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 already present. The description adds value by providing concrete examples (ticker 'AAPL' or zero-padded CIK) and clarifying that names are not supported. This enriches the parameter understanding beyond the schema alone.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company, with multiple example queries and explicit preference over chaining individual lookups. It distinguishes from sibling tools like resolve_entity by mentioning it as a prerequisite for name inputs, and from more focused tools by emphasizing the holistic nature.

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

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

Explicitly says to use this tool for holistic views and to prefer it over chaining single-pack lookups. It specifies that names are not supported and directs to use resolve_entity first if only a name is available. This provides clear when-to-use and when-to-use-alternative 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 show destructiveHint=true and idempotentHint=true. Description adds helpful context ('clear sensitive data', 'saved earlier') without contradicting annotations.

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

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

Three efficient sentences, front-loaded with purpose, no unnecessary words.

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

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

For a simple 1-parameter tool with no output schema, the description fully covers purpose, usage, and relationships to siblings.

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

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

Schema description coverage is 100% with baseline 3. Description does not add new meaning beyond the schema's 'Memory key to delete', so score remains 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?

Description clearly states 'Delete a previously stored memory by key' with specific verb and resource, and distinguishes from siblings by mentioning 'Pair with 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?

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data', and directs to sibling tools 'remember' and 'recall'.

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

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

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds context: fetches page, extracts specific elements, emits standard format. No contradictions; behavior is well-disclosed.

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: one sentence for purpose, one for process, one for use cases. No redundant information, well-structured and front-loaded.

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

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

Given no output schema, the description explains the output format (single text blob) and location (site-root/llms.txt). Annotations cover safety. The tool is simple and complete.

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

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

Schema coverage is 100% with adequate descriptions for both parameters (url, max_links). The description does not add meaningful detail beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action (Generate), the resource (llms.txt for any URL), and the outcome (markdown file for AI crawlers). It distinguishes from siblings by its specific purpose and mentions extraction of title/description/key links.

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: indexing a client's site, drafting for own project, auditing competitors. It lacks exclusions or comparisons to siblings but provides clear guidance on when 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?

The description discloses returned fields (id, type, params, created_at, last_fired_at, fire_count) and defaults (only active subscriptions). Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true; the description adds value by detailing output composition and filtering behavior.

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

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

Two sentences: first states purpose and return fields, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

For a simple list tool with one optional parameter, no output schema, and complete annotations, the description provides sufficient context about return fields and usage. No gaps given complexity.

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

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

Schema coverage is 100% with the parameter 'include_inactive' fully described. The description uses 'cancelled' instead of 'inactive' in schema, adding slight clarification, but overall the parameter details are already in the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, specifying the verb 'List' and resource 'subscriptions'. This distinguishes it from sibling tools 'subscribe' and 'unsubscribe'.

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

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

The description advises using the tool to review monitored subscriptions before adding more or to find an id to cancel, providing explicit use cases. It implies when not to use (e.g., to avoid duplicate subscriptions) but does not explicitly name 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 provide safety traits (readOnlyHint, etc.). Description adds useful detail on return data (stats, scores, tags) and a GUI link, enhancing transparency.

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

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

Two sentences, front-loaded with purpose, concise listing of return values. No wasted words.

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

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

Given the simple single-param tool, annotations, and output schema context, the description fully covers purpose and expected outputs.

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

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

Schema covers the param fully (100% coverage). Description reinforces the 'no scheme' rule with an example but does not add significant extra meaning.

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

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

The description clearly states it looks up a domain's reputation via VirusTotal, specifies the input format (no scheme), and lists the returned data. It distinguishes from sibling lookup tools (lookup_file, lookup_ip, lookup_url) by focusing on domains.

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?

No explicit guidance on when to use vs alternatives, though the domain-specific nature is implied. Lacks when-not or alternative tool mentions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds value by detailing the return fields (malicious/suspicious counts, type, size, names, tags), which is helpful behavioral context.

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

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

The description is concise with three sentences that are front-loaded. Every sentence adds value: purpose, return details, and usage context. No wasted words.

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

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

Given the tool's simplicity (1 param, clear annotations, output schema present), the description covers purpose, usage, and output completely. No gaps.

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

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

Schema coverage is 100%, so the parameter 'hash' is already well-described in the schema. The description repeats the hash types but does not add new semantic meaning beyond what the schema provides.

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

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

The description clearly states it looks up a file by hash (sha256, sha1, or md5), which is a specific verb and resource. It distinguishes itself from sibling lookup tools for domain, IP, and URL by specifying file hash.

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: 'Useful for triaging hashes seen in alerts or logs.' It does not explicitly mention when not to use it or name alternatives, but the context is sufficient for typical usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description adds value by specifying the exact data returned (ASN, country, etc.), complementing the safety profile.

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

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

The description is a single sentence that efficiently conveys purpose and return value with no unnecessary words. It is front-loaded with the key action and resource.

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

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

Given the presence of an output schema (context signals) and comprehensive annotations, the description fully covers the tool's behavior: it explains the input (IPv4), output fields, and safety profile, making it complete for an 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?

Schema coverage is 100% and the parameter 'ip' is described as 'IPv4 address' in both schema and description. The description does not add extra formatting or validation details beyond the schema, so a baseline score is appropriate.

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

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

The description explicitly states the tool looks up an IPv4 address and lists the returned fields (last-analysis stats, ASN/owner, country, network range, reputation score), clearly distinguishing it from sibling tools like lookup_domain, lookup_file, and lookup_url.

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

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

The description gives clear context for use (looking up IPv4 addresses) and implicitly differentiates from siblings via the 'IPv4' specificity, but does not explicitly state when not to use or name 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?

Adds behavioral details beyond annotations: URL is canonicalized, no submission required, returns last-analysis stats. Consistent with readOnlyHint and idempotentHint annotations. No contradictions.

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

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

Three sentence description is front-loaded with purpose, no extraneous details. Every sentence adds value.

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

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

For a single-parameter lookup tool with output schema, description fully covers purpose, behavior, and user expectations. No missing context.

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

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

Schema coverage is 100% with a clear description of 'url' parameter. Description adds meaning: canonicalization implies URL normalization, which is not in 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 explicitly states purpose: 'Look up a URL's reputation.' It details return values (stats, categories, redirect info) and distinguishes from siblings (e.g., lookup_domain, lookup_file) by specifying URL-specific behavior.

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

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

Clear context: this is a read-only lookup for existing reports, with no submission step. Does not explicitly exclude cases or name alternative tools, but sibling list implies other tools for different entity types.

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 no annotations, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), quotas ('doesn't count against your tool-call quota'), the claim_token workflow, and how the team processes feedback daily. This goes well beyond what annotations would 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 dense but every sentence earns its place: purpose, usage criteria, exclusions, feedback specifics, claim_token handling, and rate limits. It is front-loaded with the most critical information and maintains a logical flow without redundancy.

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

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

Given the tool's complexity (4 params, nested objects, no output schema), the description fully covers when to use, how to use, what to expect, and limitations. It even addresses the fallback claim_token mechanism, making it self-sufficient for an 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?

While schema coverage is 100%, the description enriches parameter understanding significantly. It explains the claim_token lifecycle ('Filing without an account returns a claim_token; pass it back later...'), clarifies the type field mappings, and instructs what to include in the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt').

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

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

The description opens with a specific action: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the resource (Pipeworx team) and the scope (tools served by this connection), distinguishing it from sibling tools like ask_pipeworx or discover_tools.

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

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

Provides explicit use cases: bug, feature/data_gap, praise. Also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' It even explains how to identify when the tool is relevant ('Pipeworx tool names are the ones this connection lists').

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, but description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching behavior (5min-1h), and aggregation nature. No contradiction with annotations.

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

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

Three sentences covering purpose, use cases, and behavioral details. No redundant information; front-loaded with the 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?

For a simple read-only tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use it, and its behavioral traits. No gaps remain.

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

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

Schema covers 100% of parameters with enum descriptions. The description adds 'Shorter windows surface what's hot right now; longer windows show steady-state demand', providing extra guidance 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 explicitly states 'Returns the top tools, top packs, and total call volume over a recent window', using a specific verb and resource. It clearly distinguishes from siblings like discover_tools by focusing on trending usage based on agent call patterns.

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

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

Three concrete use cases are listed (discovering hot data sources, confirming canonical tools, aligning use case). While it doesn't explicitly exclude alternatives, the context is clear on when to use this tool.

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

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

Discloses internal processes: walks child markets, computes partition_sum checks, applies Jaccard similarity threshold (≥0.30), filters placeholder slugs, and performs fill check against CLOB depth. No contradiction with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

Description is thorough but slightly verbose. Uses semantic capitalization for key concepts and clear separation of modes. Could be more terse, but every sentence adds value.

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

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

Despite no output schema, description details response structure (opportunities array, partition_check object with field names). Covers edge cases (low Jaccard similarity, placeholder filtering, fill check details). Fully explains behavior for a complex 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%, but description adds significant context: event accepts full URLs, topic triggers cross-event search with similarity filtering. Explains behavior differences beyond schema definitions.

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

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

States verb 'Find arbitrage opportunities' with specific methods (monotonicity violations + partition-sum checks). Distinguishes modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

Explicitly instructs when to use each mode: no args for trending scan, event for a specific market slug, topic for cross-event scanning. Provides rationale for cross-event mode and warns against trading when fill check shows non-realizable edge.

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 comprehensively discloses behavioral traits beyond the annotations: it details the three model families, caching behavior (1h KV-level), diagnostic information for empty segments, and tradeable-edge knobs. 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 lengthy and contains extensive detail on model families, which may be more than necessary for a quick understanding. While it is front-loaded with the purpose, the density of information could be condensed. Some redundancy exists (e.g., tradeable-edge knobs mentioned twice).

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 (9 parameters, no output schema), the description is remarkably complete. It covers all major behaviors, response structure, filtering, caching, and diagnostics, leaving no significant gaps for an agent to understand how 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?

The input schema has 100% coverage with detailed descriptions for all 9 parameters. The description adds some high-level context (e.g., 'tradeable-edge knobs') but does not provide additional semantics beyond what the schema already conveys. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It is built for discovering betting opportunities, which distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

The description provides clear context for when to use the tool ('what should I bet on today') and includes usage notes (e.g., Fed bets are surfaced but excluded from ranking). However, it does not explicitly mention when not to use it or directly compare to alternatives, though the context implies differentiation.

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

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

Annotations declare readOnly, openWorld, idempotent. Description adds details: reads snapshots, provides time-series, trend, decay, and notes gaps and limitations. 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?

Comprehensive but dense; response format mixed into description. Could be more structured with sections, but front-loaded purpose saves clarity.

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

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

Without output schema, description fully explains return fields (tracked, expired, snapshot_dates) with detailed structure. Covers purpose, usage, parameters, response, and limitations.

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

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

Both parameters have schema descriptions (100% coverage). Description adds defaults, range, and context (e.g., 'lookback', 'snapshot family'), augmenting schema.

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

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

Clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?' Distinguishes from sibling polymarket_edges by focusing on time-series instead of current snapshot.

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?

Explains when to use by contrasting fresh vs old edges. Implicitly suggests using polymarket_edges for current edges, but does not explicitly list alternatives or 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specific behaviors: walks the ladder, returns top_of_book, vwap_fill_price, slippage, verdict, and warns about risk of partial basket fills converting arb to unhedged directional. 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?

Well-structured with bold headings and bullet-like text, front-loaded with core purpose. However, the description is somewhat verbose due to detailed return fields; 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?

The description thoroughly covers both modes, all return fields, and risk warnings. Given no output schema, the description compensates fully, making it complete for an agent to understand what the tool returns and when to use it.

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

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

Schema coverage is 100%, but description adds contextual meaning: explains side auto-detection logic for basket mode, default values, and differences between single and basket modes. Provides significant value beyond schema.

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

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

The description clearly states the tool checks realizable-vs-theoretical edge against live order book depth, with explicit single-market and basket modes. It differentiates from siblings by directing use before polymarket_arbitrage signals or polymarket_edges trades 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?

Explicitly states when to use (before arb signals or trades >$500) and explains consequences of not using (unhedged directional positions). However, does not explicitly state when not to use (e.g., for small trades), though this is implicit.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context, detailing compatibility_warning conditions, temporal_alignment, and counters for skipped comparisons. This goes well beyond the annotations and discloses edge cases clearly.

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

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

The description is front-loaded with purpose and modes, then details response and safety fields. It covers necessary information but is somewhat lengthy. Nevertheless, every sentence adds value given the tool's complexity.

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

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

Without an output schema, the description adequately explains the response (leg-by-leg prices, spread array, safety fields). It covers compatibility warnings and temporal alignment, providing a complete picture for an AI agent. Minor improvement could be exact JSON structure, but current level is sufficient.

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

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

Schema coverage is 100%, with each parameter described. The description adds value by explaining that topic is pre-mapped with specific shortcuts and that explicit parameters override the topic-mapped side. It also clarifies the response structure. Baseline is 3, and the description provides additional context.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb ('spread') and resource ('cross-venue'), and distinguishes itself from siblings by its unique focus on cross-platform comparison.

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

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

The description explains two modes (topic shortcuts and explicit tickers) and warns that most pre-mapped topics return compatibility warnings, guiding appropriate use. It implies when to use custom pairings but does not explicitly state when not to use the tool or compare to alternatives beyond the topic list.

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

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

Annotations already report readOnlyHint, idempotentHint, destructiveHint. Description adds scoping to identifier and behavior of omitting key (list all). No contradiction.

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

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

Three sentences, front-loaded with primary action, then examples, then scoping. 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?

Covers return behavior (value or list), scoping, and pairing with other tools. No output schema, but description is sufficient for agent to understand what to expect.

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 clear description for key. Description restates the omit-to-list behavior but adds no new meaning beyond schema, so baseline 3.

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

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

Clearly states the tool retrieves a value saved via remember or lists all keys, with specific use cases like user's target ticker or addresses. 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 looking up stored context without re-deriving, notes pairing with remember and forget, and mentions scoping. Lacks explicit when-not-to-use but context is clear.

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

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

The description adds useful details like mark_read side effects and polling suitability. However, it contradicts the annotation readOnlyHint=true by describing a state-changing operation (marking events read), which is a significant inconsistency.

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 with two main sentences plus parameter details. It is front-loaded with the primary purpose. Slight room for improvement in structure but no wasted words.

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

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

Covers all 5 parameters, explains return fields, and provides an alternative endpoint. Without an output schema, the return description is helpful. Contradiction reduces completeness slightly.

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 schema by explaining mark_read behavior and the return fields (source, citation_uri, raw payload). This helps the agent understand parameter effects and output format.

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

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

The description clearly states the verb 'pull', the resource 'fired events from your subscription feed', and distinguishes itself by specifying the return fields. It is specific and not a tautology.

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 guidance on polling and an alternative HTTP endpoint. Mentions filtering by type and since, and the mark_read behavior. Lacks explicit when-not-to-use or sibling tool comparisons, but offers enough context for typical 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 safe read-only behavior. Description adds details about fan-out to multiple sources (SEC, GDELT→GNews, USPTO), fallback logic, relative date parsing, and output structure (changes[] grouped by source, total_changes, citation URIs).

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 yet well-organized: front-loaded with example queries, then source details, parameter constraints, and output format. Every sentence adds value; no redundancy.

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

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

Despite no output schema, description explains the return shape (changes[] grouped by source + total_changes + citation URIs). Covers fallback behavior and soft-fail for USPTO. Complete for a complex multi-source 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% but description adds value by explaining 'since' accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y') and recommending '30d' or '1m' for typical monitoring. This clarifies usage beyond schema.

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

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

The description clearly states the tool returns a change feed for a company over a time window, using example queries ('What's new with X', 'latest on Y'). It distinguishes itself from the sibling entity_profile by specifying when to use that instead.

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 (change feed) and when not to (static profile: use entity_profile). Examples of acceptable queries are provided, and alternative tool is named.

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

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

Beyond annotations (idempotent hint), description adds critical behavioral traits: persistence for authenticated users, 24-hour retention for anonymous, and key-value scoping. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose. Each sentence provides essential information without redundancy. Highly efficient.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, behavioral notes, and pairing. No gaps remain for agent understanding.

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

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

Schema description coverage is 100%, so baseline is 3. Description provides example key patterns (subject_property, target_ticker) which adds some value but does not significantly expand beyond schema.

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

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

The description clearly states the tool saves data for reuse, with a specific verb ('save') and resource ('data'). It distinguishes from sibling tools like recall and forget, making its purpose unambiguous.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. It provides context on scoping, retention, and pairing with recall/forget, offering clear guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses graceful degradation if GLEIF/OpenFIGI are unavailable, explicit `unresolved` fields for failed identifier resolution, and source-labeling of each identifier. No contradiction with annotations exists; these behaviors are consistent with readOnly/openWorld hints.

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

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

The description is long but well-organized: example queries first, then purpose, supported types with detailed fields, degradation behavior, and benefit. Each clause adds information; no filler. However, it could be slightly tighter by removing redundant mentions of accepted inputs already in the schema.

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

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

With no output schema, the description takes responsibility for explaining return values, listing CIK/ticker/name/LEI/FIGI for companies and RxCUI/ingredient/brand/citation for drugs. It also covers partial-failure behavior. It stops short of describing exact response structure or error handling, but is sufficient for a lookup tool.

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

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

Schema coverage is 100%, with the value parameter already documented with examples. The description repeats the accepted input formats (ticker, CIK, company name; brand/generic name) but adds no new parameter-level meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description explicitly states the tool resolves user-spoken names to canonical/official identifiers, with concrete example queries like "find the CIK for…" and "what's the LEI for…". It clearly distinguishes from siblings by emphasizing it produces IDs needed by other tools, not general 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?

It gives explicit when-to-use guidance: "Use FIRST whenever you have a name but need an ID." It also clarifies the tool replaces 2-3 manual lookups. However, it doesn't explicitly state when not to use it or name alternative tools, so it falls short of a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds rich behavioral context: probes each entity, ranks by score, surfaces most/least recognized, returns ranked list with score, confidence, signal density. 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?

Three sentences, front-loaded with core purpose, efficient without redundancy. Every sentence adds value: what it does, why you'd use it, what you get.

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

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

Given 4 params, no output schema, and no nested objects, the description covers purpose, input constraints, output structure (ranked list with metrics), and use case example. Sufficient for 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?

Schema coverage is 100% with good parameter descriptions. Description adds value by noting first entity is treated as 'subject' for narrative, and adding constraint of 2-8 entities. This goes beyond 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?

Description clearly states it compares AI visibility across multiple entities, ranks them, and surfaces most/least recognized. Distinguishes from sibling ai_visibility_check (single entity) by explicitly describing multi-entity comparison. Verb 'compare' and resource 'AI visibility' are specific.

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

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

Explicitly states use case: competitive AI-marketing audits. Provides example question to clarify intent. Does not explicitly state when not to use or list alternative tools, but the context of 'compare against competitors' implicitly distinguishes from single-probe 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?

Discloses partial failure behavior, timeout for bundlephobia first measurement (5-30s), and graceful degradation with sources_failed list. Adds context beyond readOnly/openWorld/idempotent annotations.

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

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

Well-structured with overview, usage, return format, limitations. Slightly verbose but every sentence adds value.

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

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

Covers return format (summary fields, links, alternatives), limitations (NPM only, timeout), and graceful degradation. Adequate for a composite tool without output schema.

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

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

Schema covers both parameters with full descriptions. Description adds no new parameter info 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?

States explicit purpose: composite check for npm package evaluation covering license, advisories, bundle size, etc. Distinguishes from sibling tools (none similar).

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 when to use: for questions about safety/popularity/size. Mentions NPM-only in v1 and alternative approaches for other ecosystems.

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?

Highly transparent: describes use of BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation and flagging. These details go far beyond the annotations (which only mark readOnly, openWorld, idempotent, non-destructive). 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 well-structured paragraph: starting with purpose, then usage, then technical details. Every sentence contributes distinct information 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?

For a tool with no output schema and moderate complexity, the description covers all bases: when to use, how text is chunked and embedded, limits, pairing with siblings, and what the return includes (passages with offsets and scores). No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description enriches parameters by clarifying the max length for 'text' (~200K chars), providing natural-language query examples for 'query', and noting default for 'limit' (5). This adds moderate value beyond the schema.

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

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

The description starts with 'Semantic search INSIDE a fetched record' and gives concrete examples like SEC 10-K body, article, long tool result. It explicitly states the use case: 'Use when the record is too big to cram into the prompt.' This clearly distinguishes it from sibling tools such as 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?

The description explains when to use search_within (when text is too large for the prompt) and how it pairs with ask_pipeworx_grounded for grounded reasoning. It provides a clear usage pattern but does not explicitly list when not to use other siblings, though the context is 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?

The description discloses that subscriptions are persistent (requires OAuth), always-on feed with optional delivery channels, and notes the webhook secret is returned once. Annotations indicate idempotentHint=true, but the description does not clarify idempotency behavior. However, there is no contradiction with annotations, and the disclosure is otherwise thorough.

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 moderately long but well-structured with bullet-like examples. Front-loaded with main purpose and returns value. Every sentence adds necessary detail; no redundant information. Slightly verbose due to examples, but justified by complexity.

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

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

Given the complexity (5 subscription types, nested delivery options), the description covers prerequisites, type-specific params, delivery channels, and constraints. No output schema exists, but the description mentions the return value (new subscription id). Missing explicit return format details, but adequate for selection and invocation.

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

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

Schema coverage is 100%, and the description adds substantial meaning: it explains each subscription type's parameter requirements with examples, details delivery channel restrictions (e.g., SMS 10/day cap, phone verification), and provides webhook signing details. This goes well 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 starts with a clear verb+resource: 'Create a proactive monitoring subscription to a live-data event stream' and states it returns the subscription id. It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description explicitly states the requirement for a Pipeworx OAuth account and lists supported event types with example parameters. It does not directly say when not to use this tool versus alternatives, but the context from sibling tool names and the detailed examples provide adequate guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns category-bucketed example questions drawn from a live catalog, which is useful extra context beyond the safe-read nature.

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

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

The description is a single paragraph but well-organized with parentheses and clear lists. It is informative but slightly verbose; could be split into shorter sentences without losing meaning.

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 simple nature (1 optional parameter, no output schema), the description fully explains purpose, usage, output format, and relationship to other tools. It is complete for an onboarding tool with good annotation coverage.

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

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

Schema coverage is 100% with the 'topic' parameter described. The description repeats the allowed values and explains behavior when omitted, adding semantic value beyond the schema by telling the agent when and how to use the 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 it is an onboarding entry point for what to ask Pipeworx, returning categorized example questions. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'discover_tools' by being the first-use tool to learn capabilities.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you'. Also explains optional topic parameter usage and that omitting it gives a full spread. Provides clear when-to and when-not-to context.

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

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

Beyond annotations, the description discloses ownership enforcement, soft-delete behavior, and that historical events remain available via 'recent_alerts'. 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?

Three sentences, front-loaded with main action, each sentence provides necessary detail without 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?

For a simple 1-parameter tool with detailed annotations, the description covers ownership, persistence, and side effects completely.

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 parameter 'id' is described. The description adds no additional meaning beyond the schema.

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

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

The description clearly states 'Cancel a subscription by id.' It specifies verb and resource, and distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

The description implies usage for canceling subscriptions, and mentions ownership enforcement. However, explicit guidance on when to use versus alternatives is missing.

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 open-world behavior. The description adds critical behavioral context: the distinction between could_not_verify (check did not happen) and unsupported (no source found), including the verification_error field, and explicitly warns that could_not_verify must not be treated as evidence. It also names the two processing pipelines and the return payload structure.

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

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

The description is longer than average but information-dense. It front-loads trigger phrases and purpose, then transitions to routing, return values, and critical caller warnings. Every sentence contributes meaningful guidance for a complex tool; slight verbosity prevents a 5.

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

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

With no output schema, the description fully explains the return values: verdict enum, actual value with pipeworx:// citation, and reasoning. It also covers error semantics and edge cases (could_not_verify, unsupported) and the two data paths. This is complete for the tool's complexity.

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

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

Schema description coverage is 100%, with detailed descriptions and examples for both claim and tolerance_pct. The tool description adds minimal parameter-specific meaning (e.g., 'exact percent-delta math' ties to tolerance), but the schema already carries the burden, so the baseline of 3 applies.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases and a specific verb+resource ('validate claim'). It distinguishes itself from siblings by covering both company-financial claims and any other factual claim, making its scope unmistakable.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear when-to-use context. It also describes the automatic routing for different claim types and notes it replaces 4–6 sequential calls, but it does not name alternative sibling tools for situations where this tool is not appropriate.

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