Dev Feeds

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

Description adds behavioral traits beyond annotations: it's a probing operation (consistent with readOnlyHint), notes cost implications for Anthropic (BYO key, pay directly), and explains default model (free). 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?

One well-structured paragraph, front-loaded with action and purpose. Every sentence contributes meaning: action, scope, default behavior, optional parameter details, use cases.

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

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

Given no output schema, description explains return structure (per-model fields + combined view). It covers parameters, use cases, and cost implications. No gaps remain for typical agent usage.

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 valuable extra context: default model specifics for 'models', API key format for '_apiKey', and example for 'context'. This improves understanding 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 verb 'Probe and score visibility' and resource 'LLMs', specifying the scope (business/brand/product/topic). It distinguishes from sibling tools by being unique in purpose (AI visibility scoring) among the listed siblings like ask_pipeworx, deep_research, etc.

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

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

Description mentions use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), providing clear context. It does not explicitly exclude other scenarios or point to alternatives, but the context is sufficient for typical agent decisions.

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 valuable context beyond annotations: it routes to 5,462 tools across 1,419 sources, fills arguments, works on every tier, and returns citations. It does not contradict the readOnly/idempotent hints and clearly conveys the tool's scope and behavior.

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

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

The description is long but front-loaded with the critical directive 'PREFER OVER WEB SEARCH' and includes dense, valuable information (domain list, examples, escalation paths, return format). Each section earns its place, though it could be more concise with tighter structuring.

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 adequately covers the return format (structured answer with pipeworx:// URIs) and provides comprehensive usage context, including alternatives and typical question examples. It gives the agent a complete understanding of the tool's role and behavior.

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

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

The input schema already documents the 'question' parameter and its aliases with 100% coverage. The description adds useful examples and domain scope, but does not introduce new parameter-level details; the schema is sufficient, 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 clearly states that the tool routes factual questions to the appropriate verified source and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default general-purpose 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?

Explicit guidance is provided: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and clear escalation criteria (use ask_pipeworx_grounded for hallucination-resistant single answers, deep_research for broad/multi-part questions). This gives the agent concrete 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 already declare read-only, open-world, idempotent, and non-destructive. The description adds valuable context about its experimental nature, the possibility of live candidate routing improvements, and the current state of inactivity. 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 compact and front-loaded, with each sentence adding meaningful information: beta relationship, current status, usage guidance, and clarification that it is a full working router. 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 lack of an output schema, the description covers the essential context: the experimental nature, current equivalence to ask_pipeworx, and usage instructions. It could mention potential future behavior changes more explicitly, but the description is sufficiently complete for a beta router.

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 provides 100% coverage, fully describing the 'question' parameter and its aliases. The description offers no additional parameter details, but the schema does the heavy lifting, so the 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 identifies it as a beta version of ask_pipeworx, a universal router with 5,462 tools, and clearly distinguishes it from siblings by emphasizing the experimental routing improvements. The verb 'route' is implied but the resource is well-defined, and it differentiates from the stable ask_pipeworx.

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

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

It provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing,' and explains that results are compared against the stable router. It also clarifies the current state where it matches ask_pipeworx exactly, giving clear context, though it does not explicitly mention when NOT to use it.

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

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

The description discloses significant behavioral traits beyond the annotations: returns verbatim evidence quotes, provides specific refusal reasons, uses only tool result content, and costs an extra LLM call. It also clarifies the routing mechanism across many sources, going well beyond the 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 dense but every sentence carries weight: purpose, mechanism, return format, usage scenarios, and tradeoff. It is organized logically, front-loading the core idea before details, and contains no filler.

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

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

Despite having no output schema, the description fully specifies the success and refusal response shapes, including exact refusal reason strings. It also covers cost implications and use cases, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% as all six parameters are documented as aliases for the natural-language question. The description adds no additional parameter semantics, but with full schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a hallucination-resistant answer mode for high-stakes reads that picks the right tool and extracts answers strictly from tool results. It distinguishes itself from the sibling ask_pipeworx by emphasizing evidence-backed answers and explicit refusal 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?

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and explains the cost tradeoff, making the usage boundary 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 the annotations, which already mark it as read-only, idempotent, and non-destructive. It details parallel fan-out, response shapes (market, analysis, evidence fields), safety mechanisms (low-confidence short-circuit, closed market detection, wide-spread warnings), resolution-rule risk parsing (cancellation_rule), parent event extraction, news fallback behavior, and the effect of the include_raw parameter on response size. There is no contradiction with annotations.

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

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

The description is very long and detailed, which is justified by the tool's complexity, but it lacks conciseness. It is front-loaded with the core purpose and uses a structured organization (classifiers, examples, response shapes, etc.), but many sections could be condensed. The verbosity prevents a higher score.

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

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

Given the lack of an output schema, the description fully compensates by thoroughly explaining all return fields, edge cases, and behaviors. It covers low-confidence matches, closed markets, wide spreads, resolution rules, parent events, news fallback, and the impact of include_raw. It also provides usage context like response size estimates and reliance on market_match_confidence. The description is complete for an agent to correctly invoke and interpret the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds some context beyond the schema, such as examples of market inputs and an explanation of depth default and behavior, but these are largely repetitions of schema descriptions. The description does not introduce significant new semantic information for the parameters, keeping the score at the baseline.

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

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

The description clearly states the tool's core function: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the input types (slug, URL, question text) and outlines the process (resolve market, classify bet, fan out to data packs, return evidence packet and comparison). This distinguishes it from sibling tools like polymarket_edges, which focus on edge scanning, by emphasizing comprehensive research for a single bet.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on when to trust the output by instructing agents to inspect market_match_confidence before using the analysis block, and describes blocking conditions like low_confidence_match and market_closed_or_inactive. However, it does not explicitly mention alternatives or when not to use this tool, which prevents a score of 5.

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

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

Annotations already indicate read-only, open-world, idempotent. Description adds specific data sources (SEC EDGAR/XBRL, FAERS), metrics retrieved, handling of off-calendar fiscal years, sorting behavior, and return format including citation URIs. 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?

Description is front-loaded with key action and preference instruction. However, it is somewhat lengthy with multiple example phrases and details; could be slightly more concise while retaining all value.

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

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

Given no output schema and two distinct entity types, the description fully explains expected return data (paired data with metrics, citations), behavior (sorted by primary metric), and efficiency gains. No gaps remain.

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

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

Schema coverage is 100% for 2 params. Description adds significant meaning: explains how 'type' determines data retrieved, gives examples for 'values' (tickers/CIKs vs drug names), and notes max/min constraints. This goes well beyond the schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with explicit examples of trigger phrases. It distinguishes itself from sibling tools like entity_profile and sequential lookups.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides clear examples of when to use (e.g., 'compare X and Y', 'which is bigger'). No ambiguity.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context beyond that: account/payment requirements, parallel routing across 5,462 tools, explicit 'never invented' gaps[], citation_uri resolvability, hop field, contradictions[] for standard/thorough, semantic excerpting of large records, and latency expectations (15-60s, thorough up to ~90s). No contradiction with annotations.

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

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

The description is long but information-dense; every sentence adds meaningful guidance. It is front-loaded with the critical account requirement and quickly establishes what the tool is not. However, it is one continuous block of text without paragraph breaks, which slightly hampers scannability. For a tool this complex, 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?

Despite lacking an output schema, the description fully explains the return packet (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gap handling, contradiction reporting, citation fetchability, hop field, and semantic excerpting. It also covers auth, pricing, latency, limitations, and sibling alternatives. This is comprehensive for a complex research tool.

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

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

Schema coverage is 100% for both params, so baseline is 3. The description enriches the depth parameter with practical consequences (thorough needs a paid plan, time expectations, multi-step resolution) and clarifies that 'question' should be broad/multi-part since decomposition is the point. This goes beyond the schema's already-detailed enum descriptions, warranting a 4.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources' in one call. It explicitly distinguishes from open-web search and contrasts with sibling tools like ask_pipeworx ('For a single lookup use ask_pipeworx'). It even notes the alternative for breaking news, making the purpose and 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?

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and concrete exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx.' It also covers account prerequisites and the alternative if not signed in ('use ask_pipeworx instead'). This is model-level 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 indicate read-only, idempotent, non-destructive behavior. The description adds: returns top-N relevant tools with names, descriptions, full schemas with examples, and that results are ready to call directly without a second lookup. 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 paragraph that efficiently covers purpose, supported domains, output format, and usage guidance. Every sentence adds value without redundancy.

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

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

For a tool with 6 parameters (100% schema coverage) and no output schema, the description fully explains input (query as natural language, limit), output (top-N tools with schemas ready to call), and context (use first to discover options). No gaps.

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

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

Schema coverage is 100% with descriptive parameter names. The description explains the 'query' parameter accepts natural language and lists aliases, plus provides examples. This adds value beyond the schema, justifying a score above the baseline of 3.

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

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

The description clearly states the tool's action ('Find tools by describing the data or task') and lists specific domains it covers (SEC filings, financials, etc.). It distinguishes itself from sibling tools by being the discovery/search tool, and emphasizes returning results ready to call.

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 when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and sequencing advice.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral context: fans out across multiple sources, details returned fields, notes patent soft-fail due to API sunset, and explains data freshness (LATEST 10-K). No contradictions.

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

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

Description is long but well-structured, front-loading example queries. Every sentence serves a purpose (usage guidance, return details, limitations). Slightly verbose 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?

No output schema exists, so description bears full burden. It thoroughly explains all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and covers limitations (patent soft-fail, name not supported). Complete for the tool's purpose.

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

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

Schema coverage is 100% (both parameters described in schema). Description adds meaning: explains that value can be ticker or zero-padded CIK, and that names not supported. Also clarifies type enum is limited to 'company'. Adds marginal 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 verb+resource: 'full cross-source profile of a US public company'. It distinguishes from siblings by explicitly preferring it over chaining single-pack lookups and referencing resolve_entity for name-based lookups.

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

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

Explicitly states when to use (holistic view) and when not to (names not supported; use resolve_entity first). Includes imperative 'ALWAYS PREFER over chaining' for 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds behavioral info about fetching directly and falling back to a proxy if blocked, which is not in annotations. However, it doesn't describe return format or error handling.

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

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

Three concise sentences (27 words) front-load the core purpose and add essential context without waste. Every sentence earns its place.

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

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

Given the tool's simplicity and complete annotations/schema, the description covers purpose, usage logic, and reliability. However, it omits return value structure (e.g., normalized feed items), which would help the agent understand output without an output schema.

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

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

Schema coverage is 100% with clear property descriptions. The description does not add extra meaning beyond what the schema already provides for url, limit, and query. Baseline 3 is appropriate.

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

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

Description clearly states "Fetch and normalize any RSS / Atom / RDF feed by URL," specifying the verb and resource. It also distinguishes from sibling list_feeds by recommending its use for curated sources.

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

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

Explicitly advises "Use list_feeds first for curated sources," providing clear when-to-use guidance and an alternative. Also mentions CF-robustness and proxy fallback for reliability context.

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

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

Annotations already indicate destructive and idempotent hints. Description adds usage context but no new behavioral traits beyond what annotations and schema imply.

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 action, 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?

Given the tool's simplicity (one parameter, no output schema, clear annotations), the description fully covers purpose and usage contexts.

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 for the single parameter 'key'. Description does not add additional semantic detail 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?

Explicitly states 'Delete a previously stored memory by key', clearly identifying verb and resource. Pairs with related siblings remember and recall, distinguishing usage.

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 concrete when-to-use scenarios: stale context, task completion, sensitive data removal. Mentions pairing with siblings but does not explicitly state when not to use.

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

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

Discloses key behaviors: fetches page, extracts title/description/links, emits markdown format. Consistent with annotations (readOnly, idempotent, non-destructive) and adds context beyond 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?

Single, well-structured paragraph front-loads the action, then specifies output format, and ends with use cases. No redundancy or fluff.

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

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

Given only 2 parameters (1 required), no output schema, and strong annotations, the description clearly explains the process and output format, making it fully 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% with both 'url' and 'max_links' described. Description adds no new detail for parameters; merely restates their purpose. Baseline 3 is appropriate.

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

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

Description starts with a specific verb-resource pair ('Generate llms.txt file') and scope ('for any URL'), clearly differentiating from siblings like 'scan_competitor_ai_presence' or 'validate_claim'.

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

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

Explicitly lists three use cases (client indexing, own project drafting, competitor auditing), providing clear context for when to use. Lacks explicit 'when not to use' statements, but use cases are sufficient to guide selection.

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

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

Annotations already declare read-only and idempotent; description adds that feeds are 'curated software-development' and lists returned fields, providing useful context beyond annotations.

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

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

Two sentences: first states purpose and output fields, second covers optional filters and sibling pointer. No wasted words.

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

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

For a simple listing tool, description specifies output fields, filters, and sibling relationship. No output schema exists, but the description compensates adequately.

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

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

Schema descriptions already cover both parameters (query and category) at 100%. Description restates their usage but adds 'dev' as an example category value, which is sufficient.

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 curated software-development feeds with specific fields (id, title, category, source) and distinguishes from 'read_feed' by suggesting to pass an id to that tool.

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

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

Provides optional filters (category 'dev' or keyword) and explicitly directs to 'read_feed' for a single feed, guiding appropriate usage.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds that it returns specific fields and lists only active subscriptions by default, with an option to include inactive. No contradictions.

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

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

Two sentences, succinct, front-loaded with the core 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?

Given the simple tool (one optional param, good annotations, no output schema needed), the description fully covers what an agent needs: purpose, output, default behavior, and usage hints.

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

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

Input schema has 100% coverage for the single parameter 'include_inactive' with its own description. The description reiterates the default behavior but adds no new parameter semantics 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?

Clearly states the action ('List the caller's active subscriptions') and specifies return fields. Differentiates from sibling tools like subscribe and unsubscribe by focusing on listing existing 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?

Explicitly says when to use: 'to review what you're monitoring before adding more or to find an id to cancel'. Provides concrete use cases.

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

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

Annotations are all false and provide no meaningful behavioral hints, so the description carries the burden. It discloses a rate limit ('Rate-limited to 5 per identifier per day'), confirms it is free and doesn't count against quota, and mentions that the team reads digests daily. This goes beyond the structured fields and covers relevant side effects, though it does not explicitly describe the submission result or error behavior.

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

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

The description is longer than average, but it is front-loaded with the core purpose and every sentence adds needed context for a feedback tool: when to use, when not to use, content expectations, and rate limits. It is somewhat dense, but the structure is logical and no sentences feel wasted.

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 straightforward 3-param feedback tool with no output schema, the description covers all critical context: purpose, usage boundaries, rate limits, content policy, and expected dispatch cadence. Sibling-tool differentiation is handled by the explicit exclusion. The guidance is complete enough for an agent to decide and invoke correctly without additional information.

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

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

Schema description coverage is 100%, so the parameters are already well-documented. The description adds valuable semantic guidance on the message field ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and reinforces the type categories, which helps the agent formulate meaningful values beyond what the schema enumerations provide.

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

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

The description opens with a specific verb plus resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and clearly distinguishes this tool from siblings by framing it as feedback exclusively for Pipeworx tools. It also lists concrete categories (bug, feature, data_gap, praise), making its purpose 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?

Provides explicit when-to-use guidance with examples: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives strong exclusions ('if the tool came from a different MCP server... file it with that server instead') and content rules ('don't paste the end-user's prompt'), leaving no ambiguity about appropriate use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. The description adds valuable context: data is self-aggregating from CF analytics-engine, no PII, cached 5min–1h, and explains window behavior. No contradictions.

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

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

The description is concise (4–5 sentences), front-loaded with the main purpose, followed by bullet-like use cases, and ends with technical details. Every sentence adds value with no fluff.

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

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

For a simple tool (1 optional parameter, no output schema), the description covers purpose, use cases, data source, caching, and privacy. It is self-contained and leaves no obvious gaps.

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

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

Schema coverage is 100% with a detailed description of the 'window' parameter already in the input schema. The tool description does not add new information about the parameter beyond what is in the schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume trending on Pipeworx, using a specific verb ('Returns') and resource ('trending data'). It differentiates from sibling tools like 'discover_tools' by focusing on real-time agent usage.

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

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

The description lists three concrete use cases (discovering hot data, confirming canonical tools, seeing alignment) providing clear context for when to use it. However, it does not explicitly state when not to use it or name alternative tools.

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

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

Discloses key behaviors: monotonicity violations, partition-sum checks, Jaccard similarity threshold (0.30), partition filter for placeholders, and fill check with book depth. No contradiction with annotations (readOnlyHint, idempotentHint). Adds significant value beyond annotations.

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

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

The description is dense but well-structured, starting with the overall purpose then detailing each mode and sub-behaviors (semantic anchor, partition filter, fill check). Every sentence adds value, though it could be slightly more organized with bullet points.

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

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

Despite no output schema, the description thoroughly explains the response structure (opportunities array with fields, partition_check object, fill check details). It also mentions related tool for custom sizing. Complete for the tool's complexity.

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

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

Schema coverage is 100% with parametric descriptions. The tool description enriches meaning by explaining the behavior of each parameter (e.g., event slug format, topic as seed question) and recommending usage. Adds context beyond the schema.

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

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

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three call modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk by detailing its unique methodology.

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

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

Provides explicit guidance on when to use each mode (no args for trending scan, event for specific market, topic for cross-event). Mentions using polymarket_fill_risk for custom sizing, but does not compare to all sibling tools. Still, usage 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 goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) by detailing caching (1h at KV level), how segments compute edges, Kelly sizing, filter effects, and diagnostic output. No contradictions with annotations.

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

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

The description is lengthy but well-structured, front-loading purpose and then detailing segments, edge metrics, knobs, and output structure. Every sentence adds value given the complexity, though it 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?

Given 9 parameters, no output schema, and complex behavior (three segments with nested logic, caching, diagnostics), the description is exceptionally thorough. It explains the output structure (by_segment, diagnostics, fed_candidates), all edge metrics, filter knobs, and caching policy.

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

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

All 9 parameters have schema descriptions, but the tool description adds significant extra context (e.g., slippage_pp explains Polymarket's zero fees but thin depth, min_partition_leg_kelly clarifies why min_kelly doesn't apply to partitions). This enriches the meaning beyond the schema.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets to find opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx data disagreement and segmenting opportunities into three families.

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

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

The description explicitly says it's built for 'what should I bet on today' and explains the three segments (model-driven, structural arbitrage, concentrated longshot) and tradeable-edge knobs. It provides guidance on when to use filters but does not explicitly exclude alternatives or mention when not to use this tool vs siblings.

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

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

The description adds significant value beyond annotations by detailing the time-series data, expired opportunities, decay calculation method, snapshot gaps, and TTL limitations. 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 quite lengthy, especially the response structure explanation, which could be more concise. However, it is well-organized with front-loaded purpose, response details, and limitations.

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

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

Given no output schema, the description fully explains the three response arrays, limitations, and data gaps. It provides all necessary context for an agent to correctly invoke and interpret the tool's output.

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

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

Both parameters have schema descriptions coverage at 100%, and the description adds context such as default values, clamping, and the meaning of window families. Minor inconsistency: description says 'max 30' for days while schema says 'clamp 2-30'.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it is shrinking. It gives specific output structure but lacks a concise one-liner at the top.

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 good usage context by contrasting fresh wide edges with old ones and explaining the value of knowing edge age. However, it does not explicitly state when not to use this tool or mention alternatives among siblings.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds further behavioral context: walks the order book ladder, returns specific fields like slippage and verdict, and warns about forced directional risk and thin legs. No contradiction with annotations.

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

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

The description is well-structured with clear sections for single-market and basket modes, but it is somewhat lengthy. However, every sentence adds value, and the use of capitalization for key terms aids readability. Minor conciseness improvements could be made.

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

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

Given the tool's complexity (two modes, multiple return fields, risk warnings), the description is comprehensive. It covers prerequisites, mode selection, parameter interpretation, return fields, and risk warnings. The absence of an output schema is mitigated by detailing the return fields in the description.

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

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

Schema description coverage is 100%. The description adds significant meaning beyond the schema: explains default auto behavior for side in basket mode, interpretation of size_usd for basket as settlement notional, clamp range 10–1,000,000, and the difference between single-market and basket parameter usage.

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

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

The description clearly states the tool's core function as a 'realizable-vs-theoretical edge check against live CLOB order-book depth'. It explicitly distinguishes between single-market and basket modes, providing specific use cases and differentiating from sibling tools like polymarket_arbitrage 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?

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (partial fills convert arb to directional risk) and when not to use (theoretical overround on thin books).

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description details response fields (raw probabilities, top_spreads_pp), safety fields (compatibility_warning with two specific cases, temporal_alignment, skipped counters). It thoroughly explains behavioral nuances like temporal misalignment making spreads meaningless, and when legs are incompatible due to metric type mismatches.

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

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

The description is front-loaded with the core purpose and then progressively detailed, structured with sections for modes and safety fields. While thorough, it is somewhat lengthy (over 250 words) and could be tightened without losing value, but every sentence contributes to understanding.

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

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

Given no output schema, the description sufficiently explains the response structure: per-venue prices, matched spreads, compatibility_warning with distinct cases, temporal_alignment, and skipped counters. It covers corner cases (incompatible bet shapes, unrelated events) and provides enough detail for an agent to correctly interpret results.

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

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

Schema coverage is 100% (both parameters have descriptions), and the description adds significant meaning: it explains the dual-mode, lists the exact 10 topic shortcuts, notes override behavior for explicit tickers, and provides usage examples (fed, btc). This goes well beyond the schema's basic descriptions.

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

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

The description clearly states it computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit event tickers) and gives concrete examples. Among sibling tools like polymarket_arbitrage, this tool is unique in being cross-venue, and the description effectively distinguishes its purpose.

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

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

The description explains when to use topic shortcuts vs explicit pairings, and warns that pre-mapped topics often return compatibility_warning, so not all presumed spreads are tradeable. However, it does not explicitly mention alternatives or when to use other tools like polymarket_arbitrage instead, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds that it returns normalized items with specific fields, which is consistent and provides useful output context 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?

Two efficient sentences: first states purpose and source, second describes return format and optional filter. No redundancy, 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?

The description covers the core functionality, input prerequisites, output format, and optional filtering. It lacks error handling or return value details but is adequate for a simple read tool given rich annotations.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description echoes the parameter purpose but does not add new constraints or formatting details, meeting the baseline for full schema coverage.

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

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

The description clearly states it reads a curated software-development feed by its ID, distinguishing it from siblings like list_feeds (which provides the IDs) and fetch_feed (if present). It specifies the resource and action.

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 obtaining the feed ID from list_feeds, establishing a clear prerequisite. However, it does not explicitly contrast with alternatives like fetch_feed or state when not to use, missing some exclusion 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 indicate read-only, idempotent, non-destructive. The description adds beyond that: scoping to identifier and listing behavior when key omitted. 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?

Front-loaded with core action, then use cases, scoping, and pairing. Each sentence serves a purpose, though slightly verbose.

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 retrieval tool with one optional parameter, the description covers retrieval, listing, scoping, and relationships. Annotations and schema are rich enough; description is complete.

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

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

Schema covers parameter fully with description about omitting key to list all. The description reinforces this, adding value but not significantly beyond schema.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all saved keys. It distinguishes itself from sibling tools like remember and forget by explicitly pairing with them.

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

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

The description explains when to use: to look up stored context without re-deriving it. It provides scoping details but does not explicitly state when not to use or give alternatives among siblings.

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

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

The description states that setting mark_read:true flags returned events as read, which implies a modification of state. However, annotations declare readOnlyHint:true, indicating no state change. This is a direct contradiction. Additionally, the mark_read feature undermines idempotentHint:true since repeated calls with the same parameters can yield different results. The description fails to align with annotations.

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

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

The description is four sentences, front-loaded with the core purpose, followed by payload details, filtering, mark_read behavior, and polling suitability. Every sentence serves a clear purpose, and there is no redundancy or fluff. It is appropriately concise and well-structured.

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

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

Given the rich schema (100% coverage) and annotations, the description covers the return format (source, citation_uri, payload), filtering options, mark_read behavior, and polling. It also provides an alternative access method. However, it does not explain default limit or behavior when both mark_read and unread_only are set, but these are minor omissions for a read tool with good schema documentation.

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 each parameter has a baseline description. The tool description adds value by providing examples (e.g., 'sec_8k' for type), explaining that 'since' refers to fired_at >= time, and clarifying the effect of mark_read on subsequent calls. This contextual information enhances understanding beyond the schema.

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

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

The description clearly states the tool pulls fired events from a subscription feed and returns recent alerts. It specifies what each alert carries (source, citation_uri, payload) and mentions filtering by type and since. While it does not explicitly distinguish from siblings like fetch_feed, the purpose is specific and unambiguous.

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

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

The description mentions polling is fine and provides an alternative URL for scripts/dashboards, giving some usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., fetch_feed, read_feed) or when not to use it (e.g., for historical data not in feed). The guidance is implicit rather than explicit.

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 operations. Description adds multi-source fan-out, fallback logic, and USPTO soft-fail, providing valuable context beyond annotations.

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

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

Single paragraph but efficiently packs use cases, sources, parameter tips, and sibling reference. No filler, though could be slightly more structured.

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

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

Despite no output schema, description explains return structure. Covers fallback, soft-fail, and parameter constraints. Fully adequate for the complexity.

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

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

Schema has 100% coverage, but description enhances with examples for 'since' (e.g., '30d', '1m') and clarifies 'value' accepts ticker or CIK, and 'type' only supports 'company'.

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

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

Description uses specific verbs ('change feed', 'fans out') and resources (SEC, GDELT, GNews, USPTO). It distinguishes from sibling entity_profile by stating when to use which.

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 (queries like 'What's new with X') and when not to (use entity_profile for static profile). Provides parameter examples and fallback behavior.

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

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

Beyond idempotentHint=true, it adds scoping by identifier, authenticated persistence, 24-hour retention for anonymous sessions. No contradiction with annotations.

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

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

Four sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value.

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

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

For a simple store tool with no output schema, it fully explains behavior, lifetime, and relationship to sibling tools. 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% and schema descriptions are adequate. The description does not add new parameter details, but the baseline 3 is appropriate.

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

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

The description clearly states the tool saves data for reuse across sessions with concrete examples like 'a resolved ticker, a target address', distinguishing it from siblings recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and pairs with recall/forget. Does not explicitly state when not to use, but the context is clear enough.

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

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

Annotations already declare readOnly, idempotent, and non-destructive; the description adds valuable context about internal cascading through lookup endpoints, auto-disambiguation, and the citation URIs returned. No contradiction, and the added details go beyond the annotation baseline.

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

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

The description is well-structured: examples, purpose, type-specific details, and a benefit note. It's slightly longer than minimal but every sentence earns its place, effectively front-loading the core purpose and usage trigger.

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

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

With no output schema, the description thoroughly covers return values for both entity types (ticker, CIK, RxCUI, citation URIs) and accepted input formats. It omits failure modes or edge cases, but is otherwise complete for the intended use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds concrete examples (AAPL, 0000320193, ozempic) and explains auto-disambiguation behavior, enhancing the schema's basic field descriptions with practical usage semantics.

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

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

The description uses a specific verb ('resolve') with a clear resource (names to canonical identifiers) and provides concrete utterance examples. It distinguishes itself from siblings like entity_profile (which likely profiles rather than resolves IDs) by focusing on identifier lookup.

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 FIRST whenever you have a name but need an ID,' providing a clear conditional trigger. It also notes that using the tool 'replaces 2-3 manual lookups,' giving additional context on when to invoke it over 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 declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds operational context (probes each entity, ranks, returns specific metrics) and notes that first entity is treated as subject. 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 three sentences, front-loaded with the core purpose, and every sentence adds value. No redundant or extraneous information.

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

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

Given 4 parameters and no output schema, the description covers inputs and outputs well: it explains the probing mechanism, the output format (ranked list with score/confidence/signal density), and provides a use case. Minor omission: does not reinforce the 2-8 entity constraint.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the 'entities' array as 'your brand + N competitors' and the 'context' parameter as disambiguation, which enriches 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 the tool's verb ('Compare AI visibility'), resource ('multiple entities'), and specific actions (probes with ai_visibility_check, ranks). It differentiates from sibling tools like ai_visibility_check by specifying side-by-side comparison across entities.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and hints at the alternative (using ai_visibility_check for single entities), but does not explicitly state when not to use this tool or list alternatives.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description reveals the composite fan-out architecture, potential 5-30s delays for new versions, and graceful partial failure handling (sources_failed listed). This adds critical behavioral context not captured by annotations.

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

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

The description is well-structured and front-loaded with the core purpose. Every sentence adds value—explaining the composite nature, return structure, limitations, and edge cases—without redundancy or 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 complexity (composite, multiple sources, potential partial failures), the description is fully complete. It explains the return format (summary block with fields, details, links, versions), limitations (NPM only), and behavior on failure (timeout, sources_failed). No output schema is needed with this level of detail.

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

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

Schema descriptions already cover both parameters comprehensively (100% coverage). The description does not add new semantic details beyond what the schema provides (e.g., parameter formats, constraints). It meets the baseline but does not enhance parameter understanding.

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

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

The description clearly states it is a composite check for npm packages, listing the sources (deps.dev and bundlephobia) and the questions it answers (e.g., 'is X safe/popular/small'). It also distinguishes itself from siblings by noting 'NPM ecosystem only' and explicitly mentioning alternatives for other package ecosystems.

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

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

The description provides explicit when-to-use guidance ('Use whenever an agent asks...') and when-not-to-use ('PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). It also covers partial failure behavior and timeout expectations.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds: embedding model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), character limit (200K with truncation/flagging), and offset for passages. 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 sentences packed with purpose, use case, benefits, workflow pairing, and technical details. No wasted words; front-loaded with core message.

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 return format (passages with offsets and scores). Covers all relevant details: input constraints, tech specs, and integration hints. Fully equips 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 provides 100% coverage with descriptions. Description adds nuanced context: 'text' is 'already pulled' content, 'query' has example phrases, 'limit' has default and range. Supplies meaning beyond schema.

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

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

The title and first sentence immediately specify 'semantic search INSIDE a fetched record.' It clearly differentiates from sibling tools by describing its specific use case (large documents) and relationship with ask_pipeworx_grounded.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for workflow guidance. Lacks explicit when-not-to-use but provides strong contextual direction.

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 reveals important behavioral traits beyond what annotations provide: it requires authentication, details delivery channel limits (SMS 10/day cap, webhook auto-disabled after 10 failures), and mentions OAuth account requirements. Annotations indicate idempotentHint=true but the description does not contradict this; it adds useful context about the creation operation.

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

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

The description is well-structured, starting with purpose, then requirements, then supported types with examples, and finally delivery channels. While it is lengthy, every sentence provides value. It could be slightly more concise but remains efficient.

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

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

Given the complexity (3 params, nested objects, no output schema), the description covers prerequisites, type-specific filters, delivery options, and behavioral constraints. It does not explain idempotency behavior in detail or the exact return format beyond 'subscription id', but overall it is sufficient for an agent to correctly invoke the tool.

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

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

Schema coverage is 100%, yet the description adds substantial meaning: it explains the purpose of each parameter, provides examples (e.g., params:{topic:'fed'}), and details constraints on delivery subfields (e.g., phone verification, signing secret for webhooks). This goes well 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 that the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It lists specific supported types (sec_8k, polymarket_edge, etc.) and distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description explicitly requires a Pipeworx OAuth account and notes that anonymous and BYO accounts cannot persist subscriptions. It provides detailed guidance on supported types and their parameters, as well as delivery channel constraints. However, it does not explicitly state when to use this tool versus alternatives like list_subscriptions or unsubscribe.

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, openWorld, idempotent, non-destructive. The description adds that it returns example questions drawn from a live catalog of thousands of tools, and mentions meta-tools. No contradictions, and it provides useful behavioral context beyond annotations.

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

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

The description is somewhat lengthy but well-structured: it starts with example queries, then explains the output and usage. It is front-loaded with key information, though slight tightening could improve conciseness.

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

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

The description explains the return structure (category-bucketed example questions with tool calls) and usage patterns. Given no output schema, it covers essential information for an agent to use the tool correctly. It is complete for its purpose.

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

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

Schema coverage is 100% with a description of the 'topic' parameter. The description adds meaning by explaining the effect of omitting vs specifying the topic, and lists example topic values, providing more clarity than 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 that this tool returns category-bucketed example questions for Pipeworx, with exact tool and argument shapes, and is the onboarding entry point. It distinguishes from sibling tools by being the first tool to use when unsure of 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?

The description explicitly says to use this first when the agent does not know what Pipeworx can do, and provides guidance on arguments (omit for full spread, pass topic for focus). It does not explicitly state when not to use it, but the context is clear.

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

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

Discloses important behavioral traits beyond annotations: ownership enforcement, row deactivation (not deletion), and that historical events remain available via recent_alerts. Annotations already indicate non-destructive and non-read-only, and the description adds context about what 'destructive' means here.

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

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

Two sentences with no wasted words. First sentence states action and constraint, second explains behavior. Front-loads the core purpose.

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

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

Covers all critical aspects: action, required parameter, ownership restriction, side effects (deactivation not deletion), and linkage to sibling tool for historical data. No gaps given the tool's simplicity.

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

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

The only parameter id is fully described in the schema. The description adds value by stating it is 'returned by subscribe', linking the parameter to its source, which aids agent understanding.

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

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

Clearly states the action (cancel a subscription), the resource (by id), and distinguishes from siblings like subscribe and list_subscriptions. Mentions ownership enforcement and retention of historical events, which further clarifies its role.

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 (cancel own subscription) and who can use it (only owner). Implicitly tells when not to use (cannot cancel others' subscriptions). References sibling recent_alerts for historical events, but no explicit exclusion of alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it details the verdict types (confirmed, approximately_correct, refuted, inconclusive, unsupported), the dual-path processing logic, and the inclusion of verbatim evidence with citations. This goes beyond the annotations.

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

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

The description is relatively long but front-loaded with clear usage examples and key features. Every sentence adds value: examples, dual-path explanation, return values, and efficiency claim. A minor reduction in redundancy (e.g., 'routed to the right live source' could be shortened) would improve conciseness.

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

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

Despite lacking an output schema, the description thoroughly explains the return values (verdict, actual value with citation, reasoning) and covers both processing paths. It does not mention error handling or edge cases (e.g., unavailable sources), but given the tool's complexity, the description is adequate and mostly complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value: it explains that tolerance_pct overrides the default implied by the claim wording (capped at 5%), provides usage examples for claim format, and suggests a range of 1-2% for hallucination detection. This enriches the static 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 multiple usage examples ('Is it true that…', 'fact check', etc.) and clearly states the tool's purpose: natural-language claim verification against authoritative sources. It distinguishes between company-financial claims (SEC EDGAR fast path) and other claims (grounded pipeline), making it specific and differentiated from siblings.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also contrasts with alternatives by claiming it replaces 4-6 sequential calls. However, it does not explicitly state when NOT to use the tool or provide exclusion criteria.

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