Data Kcmo

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety. The description adds context: it probes LLMs, returns per-model scores with confidence/signals/raw_response, and that passing an API key probes Anthropic with direct payment. No contradictions.

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

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

Three concise sentences, front-loaded with purpose. Every sentence adds value with no redundancy or fluff.

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

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

Given full parameter schemas, comprehensive annotations, and no output schema, the description adequately summarizes return structure (per-model + combined view). All necessary information for an agent to use the tool effectively is present.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning beyond schema by explaining the API key's payment model and context for disambiguation, and noting the default model. This elevates from baseline 3.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies the resource (LLMs) and action (probe and score), and distinguishes from siblings by mentioning AI-marketing audits, pre-launch checks, and competitive monitoring.

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 indicates usage for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It provides guidance on default model and when to include an API key, but does not explicitly exclude alternatives or compare to sibling tools.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond by disclosing routing behavior (5,529 tools, 1455 sources), argument filling, stable citation URIs in the response, and operational traits like 'one fast call' and 'works on every tier'. 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 comprehensive and well-structured, starting with a strong 'PREFER OVER WEB SEARCH' directive and then listing examples and alternatives. However, it is quite long, and some statements like 'START HERE for most questions' and 'Use whenever...' are slightly redundant. It earns a high score but not a 5 due to length.

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

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

Given the moderate complexity and the rich annotations, the description is fully complete. It explains what the tool does, when to use it, how it behaves, and what it returns (structured answers with citations). It also covers edge cases like news/breaking news and defines escalation paths to sibling tools. No output schema exists, but the description adequately covers return value expectations.

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

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

The input schema already documents the 'question' parameter and its aliases with 100% coverage, so the baseline is 3. The description adds value by providing numerous examples of valid question types and explicit domain coverage, which effectively clarifies the expected input semantics. This is a clear bonus over 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 what the tool does: it answers factual questions by routing to thousands of verified sources and returning structured data with citations. It uses specific verbs like 'answers' and 'routes', and the resource is well defined as 'authoritative structured data with citations'. It also distinguishes itself from siblings by labeling itself as the default entry point and mentioning alternatives.

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: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', and lists concrete trigger phrases and examples. It also gives clear when-not-to-use instructions: 'Step up only when needed' and names specific alternatives (ask_pipeworx_grounded, deep_research) with reasons. This is exemplary usage differentiation.

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

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

The description goes beyond annotations by explaining the beta nature, live candidate routing, current inactivity of candidates, and the fact that it is a fully functional router rather than a fallback. It also discloses that behavior may change during tests and that results influence merges, adding valuable context beyond the readOnly/idempotent 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 three sentences, front-loaded with the core purpose. Each sentence adds meaningful information—status, usage, and a caveat—without fluff. It is slightly longer than strictly necessary, but the extra sentence covers crucial experimental context, making it 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 simplicity of the schema (one real parameter) and strong annotations, the description provides sufficient context. It explains the beta status, current parity with ask_pipeworx, and the comparison process. The lack of output schema is mitigated by the note that the response shape matches ask_pipeworx, making the description adequate for a router tool.

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

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

The schema already provides 100% coverage with all parameters described as aliases for the required 'question' field. The description adds no parameter-specific detail, but it does note 'same arguments' as ask_pipeworx, which references external context. This meets the baseline for high schema coverage.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by highlighting its experimental routing improvements, making its purpose unambiguous.

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

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

The description explicitly states to 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router. This provides clear when-to-use guidance and implicitly contrasts with the stable alternative, effectively differentiating usage scenarios.

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

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

Annotations already indicate read-only/idempotent, and the description adds crucial behavior: it extracts only from tool results, returns specific refusal reasons, and outlines the exact return shape. It also mentions the extra LLM call cost, providing rich 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?

Despite being longer than average, every sentence is purposeful. It front-loads the core purpose, then efficiently covers return format, refusal reasons, use cases, and cost trade-offs 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?

With no output schema, the description fully documents expected outputs (success and refusal structures), explains failure modes, and provides usage context. It is comprehensive for the tool's complexity.

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

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

Schema description coverage is 100% (all aliases for question), so the description need not add much. It doesn't introduce new parameter details, but the schema already defines the question parameter and its aliases, which meets 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 function: hallucination-resistant grounded answering for high-stakes reads. It distinguishes itself from 'ask_pipeworx' by emphasizing evidence-based extraction and explicit refusals, making it unique among 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?

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use this tool vs. the alternative.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds extensive behavioral details: short-circuiting on low confidence and closed markets, news fallback via GNews, wide-spread warnings, cancellation rule parsing, and evidence summarization. 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 dense, mixing core purpose with low-level implementation details. While comprehensive, it lacks conciseness and structure (e.g., bullet points or sections), potentially overwhelming an AI agent.

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

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

Given the tool's complexity (3 parameters, no output schema, many edge cases), the description covers input formats, classifiers, response shape, resolver contract, parent events, news fallback, and cancellation rules. Some details about the return value are textual but adequate.

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

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

Schema coverage is 100%, with each parameter having a description. The tool description does not add significant meaning beyond the schema. Examples in the schema's 'examples' field provide usage context but are not part of the description.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying input formats and output components. It distinguishes from sibling tools like polymarket_edges and deep_research by combining resolution, classification, and fan-out in one 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 lists use cases ('should I bet on X', etc.) and explains when results are trustworthy via safety mechanisms (low_confidence_match, market_closed_or_inactive). Does not explicitly list alternatives, but the context of sibling tools implies differentiation.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specific data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, and sorting by primary metric—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?

Front-loaded with trigger phrases; every sentence adds value. Slightly long but justified by the amount of useful 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?

With complete schema, good annotations, and no output schema, the description fully covers behavior: return format (paired data + citation URIs), sorting, efficiency claims, and data coverage.

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

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

Schema coverage is 100%, baseline 3. The description adds meaning by explaining what data each 'type' pulls and specifying tickers/CIKs for company and names for drug, plus a usage example.

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 'side-by-side comparison of 2–5 companies or drugs' and provides trigger phrases. It unambiguously identifies the tool's purpose and distinguishes it from 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 states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing clear when-to-use guidance and alternatives to avoid.

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

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

Goes well beyond annotations by disclosing account/paid requirements, the gaps[] behavior (never invented), facet decomposition and parallel routing, second-hop iteration by depth, expected latency, and the citation_uri fetchability guarantee. No contradiction with readOnlyHint/openWorldHint/idempotentHint.

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

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

The description is long (≈250 words) but information-dense, front-loading the account requirement and primary alternative. No sentence is filler, though the wall-of-text format could benefit from bullet points for easier scanning.

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 comprehensively explains the return format: findings packet with evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop, and citation_uri. It also covers latency and edge cases, making the tool fully understandable for an agent.

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

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

Schema already covers both parameters (100%), but the description adds extra meaning: depth values are tied to facet counts (quick=3, standard=5, thorough=8) and behaviors like gap recovery and contradictions scanning. It also clarifies that broad/multi-part questions are acceptable.

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 function: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It explicitly contrasts with open-web search and with ask_pipeworx for single lookups, making its unique scope 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?

Provides explicit guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead.' This clearly distinguishes when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe, non-destructive read operations. The description adds valuable behavioral details: it returns the top-N most relevant tools with names, descriptions, and full input schemas, and states each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations and helps the agent understand the tool's outputs and usage pattern.

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

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

The description is two sentences, both front-loaded and substantive. The first sentence states the core purpose, and the second explains when to use it and what it returns. There is no extraneous information, and each sentence earns its place. It is concise yet complete.

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 that there is no output schema, the description adequately explains the return format: a list of tools with names, descriptions, and full input schemas. It covers the key aspects: purpose, usage timing, and output quality. It could potentially mention pagination or result limits, but the limit parameter addresses that indirectly. Overall, it is complete enough for an agent to decide when and how to use this tool.

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

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

Schema description coverage is 100%, with parameters for query (and aliases) and limit. The description provides examples ('look up FDA drug approvals', 'analyze housing market trends') and explains that the query accepts natural language. While the schema already covers the parameter details, the description adds context by illustrating typical input patterns, which is mildly helpful but does not significantly extend the schema's meaning.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It also lists specific domains (SEC filings, financials, FDA drugs, etc.), making the scope concrete. The verb 'find tools' distinguishes it from sibling tools that perform specific analyses (e.g., compare_entities, deep_research), so the agent can differentiate.

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 advises: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance. It does not list explicit when-not or alternatives, but the sibling list and the recommendation to use first imply it is for exploration before selecting other 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?

Description details parallel fan-out across multiple sources, soft-fall for patents, fallback mechanics for news, and exact data returned with ordering. This goes well beyond the annotations, which only cover safety and idempotency.

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 example queries, each sentence adds value. Despite length, it remains structured and eliminates 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?

No output schema exists, so the description must explain returns; it does so comprehensively, listing all data categories and ordering. Combined with full parameter coverage, the description is complete for effective use.

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

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

Schema already provides 100% coverage, but the description adds context like 'Names not supported — use resolve_entity first' and example values, enhancing usability beyond the schema alone.

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

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

Description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call' and gives example queries. It distinguishes itself from alternative chaining approaches, making its 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?

Explicitly advises to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and directs users to use resolve_entity first if they only have a name, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructive and idempotent hints. Description adds usage context but does not disclose what happens if key does not exist or if deletion is permanent. Only marginal additional behavioral detail beyond annotations.

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

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

Two concise sentences, front-loaded with purpose, no wasted words. Every sentence earns its place.

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

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

For a simple tool with one required parameter and no output schema, description adequately covers purpose and usage. Could mention return value or idempotency behavior, but overall sufficient.

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

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

Schema coverage is 100% with a single parameter 'key' described as 'Memory key to delete'. Description adds no extra parameter meaning beyond what schema provides, so baseline 3 applies.

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

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

Description clearly states 'Delete a previously stored memory by key', which is a specific verb+resource. It distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly provides when-to-use conditions: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with remember and recall, guiding agent on 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?

The description details behavior beyond annotations: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown as a single text blob. This complements annotations (readOnlyHint, idempotentHint) with actionable process info, with no contradictions.

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

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

The description is two concise sentences plus a brief bullet list of use cases. Every sentence adds value, the main purpose is front-loaded, and there is no wasted text.

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

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

Given the tool's simplicity (2 parameters, no output schema, clear annotations), the description covers purpose, behavior, output format, and usage contexts completely. It explains the output as a single text blob in markdown, which is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description implies the url parameter and hints at max_links (max number of link entries), but adds no new meaning beyond the schema's parameter descriptions (e.g., default and max values are already 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 generates a production-ready llms.txt file for any URL, specifying the verb (generate) and resource (llms.txt for a URL). It differentiates from siblings by focusing on file generation for AI crawlers, with concrete use cases like client indexing or auditing competitors.

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

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

The description provides explicit usage contexts: getting a client's site indexed, drafting for own project, or auditing a competitor's AI visibility. It does not explicitly mention when not to use or compare to siblings, but the contexts are clear enough for an agent to decide.

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 no extra behavioral context beyond stating it searches and returns metadata. 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?

Single sentence, front-loaded with purpose, no wasted words. Efficient and clear.

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

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

Given the schema covers all parameters and annotations cover safety, the description is complete enough. It explains the return values and how to use the result with another tool.

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

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

Schema coverage is 100% with clear parameter descriptions (limit, query, offset, _apiKey). The description does not add meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the tool searches the Kansas City, MO open-data catalogue by keyword and returns dataset names, descriptions, and Socrata resource ids. It distinguishes itself from siblings like kcmo_query and kcmo_recent.

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 tells when to use (searching by keyword) and mentions using the result with kcmo_query. It does not explicitly state when not to use, but the purpose is clear from the name and context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining the Socrata API usage, SoQL clauses, pagination parameters, and optional API key for rate limits.

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

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

Two short, direct sentences with no wasted words. Every sentence provides essential 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?

With 8 parameters and no output schema, the description covers purpose, resource discovery, SoQL syntax, and optional API key. Slightly more detail on ordering/grouping could be added, but it is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the resource_id pattern, mentioning the keyless endpoint, and referencing valid SoQL clauses.

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

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

The description clearly identifies the tool as running raw SoQL queries against Kansas City open-data resources, specifies the resource ID format, and explicitly contrasts with sibling tools (kcmo_datasets, kcmo_recent) for finding IDs.

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

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

The description advises using kcmo_datasets or kcmo_recent to find resource IDs, implying when to use this tool. It provides clear context but stops short of explicit when-not-to-use or alternative exclusions.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive. The description adds that results are newest-first, which is useful but not extensive. 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 plus a brief preference list. Every sentence serves a purpose, no wasted words. Information is front-loaded.

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

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

For a read-only tool with no output schema and fully documented parameters, the description adequately explains purpose, datasets, filtering, and when to use alternatives.

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% description coverage for all 4 parameters. The description reinforces the where filter and newest-first ordering but adds minimal new info beyond the schema.

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

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

The description explicitly states it returns recent records from Kansas City open datasets by friendly name, specifies datasets (311, crime), and notes newest-first ordering. This clearly distinguishes it from siblings like kcmo_datasets and kcmo_query.

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

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

Explicitly advises to prefer this tool over web search for specific queries and directs users to kcmo_query for anything beyond a SoQL where filter. Provides clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds value by specifying the default behavior (active subscriptions) and the exact return fields, providing context beyond the structured 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 two sentences, front-loaded with the purpose, and every sentence adds value with no filler. Highly concise and structured effectively.

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

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

For a simple list tool with one optional parameter and no output schema, the description provides all necessary context: purpose, return fields, default filtering, and usage scenarios. It is fully adequate for the complexity level.

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

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

Schema coverage is 100% with one parameter fully described. The description mentions 'active subscriptions' implying the default filter, but adds no new meaning beyond the schema. Baseline 3 is appropriate given the schema already documents the parameter well.

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

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

The description clearly states 'List the caller's active subscriptions' and specifies the returned fields. It distinctly identifies the tool's function and distinguishes it from sibling tools like subscribe/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 provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to leverage the tool, though it doesn't explicitly state when not to use it.

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

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

Annotations provide no behavioral hints (all false), so the description carries full weight. It discloses non-obvious behavior: claim_token flow for follow-up reads, rate limit of 5 per identifier per day, and no impact on tool-call quota. This goes well beyond the structured data.

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

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

The description is a single dense paragraph, but every sentence carries meaningful content. It is front-loaded with purpose and then systematically covers usage, exclusions, mechanics, and limitations. Slightly long, but appropriately so given the tool's complexity; a 5 would require even tighter organization.

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

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

The tool is relatively complex with four parameters, nested objects, and a follow-up claim_token workflow. The description covers the workflow, rate limits, exclusions, and what to report, making it self-contained. No output schema exists, but the return behavior is explained well enough for correct invocation.

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

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

Schema coverage is 100% with helpful descriptions, so baseline is 3. The description adds extra semantics by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:...})') and adding guidance for message content (avoid pasting end-user prompts). This justifies a 4, though not a 5 since context object details are already 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's purpose: to tell the Pipeworx team about broken, missing, or desired functionality. It distinguishes from siblings by explicitly framing this as feedback about the Pipeworx connection's tools, contrasting with tools like ask_pipeworx or discover_tools.

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

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

Provides explicit when-to-use criteria (bug, feature, data_gap, praise) and an explicit when-not-to-use exclusion (tools from other MCP servers). It also offers guidance for uncertainty, noting that Pipeworx tool names are those listed by this connection.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds: 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count). Cached 5min-1h depending on window.' This provides useful behavioral context beyond annotations, though annotations cover the main safety profile.

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

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

Description is concise, well-structured with bullet-like use cases, and every sentence adds value. No wasted words; front-loaded with the core function.

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

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

Given only one optional parameter, no output schema, and strong annotations, the description provides sufficient context: what it returns, use cases, caching, and data origin. No missing information for an agent to use it 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?

Single parameter with enum (24h, 7d, 30d) and 100% schema coverage. Description adds semantic value: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose appropriately.

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+resource: 'returns the top tools, top packs, and total call volume over a recent window.' It distinguishes from sibling tools (e.g., ask_pipeworx, discover_tools) by being an aggregation/trending tool, not a Q&A or search tool.

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

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

Explicitly lists three specific use cases (discovering hot data sources, confirming canonical tool, aligning use case). Mentions caching behavior but does not explicitly state when not to use or compare to alternatives. However, the use cases provide strong 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds substantial context: it details the fill check using live CLOB depth, semantic anchor (Jaccard similarity), partition filter, and response structure. It also explains behavioral constraints (e.g., deviations >3pp trigger signals, placeholder fraction >20% nullifies signal). 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 somewhat lengthy but highly information-dense. It front-loads the purpose and mode options, then dives into details. Every sentence adds value, though some technical details (e.g., Jaccard threshold, placeholder fraction) could be slightly more concise. Still, structure is logical and readable.

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

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

Despite no output schema, the description fully explains the return structure (opportunities array, partition_check object, fill check details). It covers edge cases (deviations >3pp, low similarity, placeholders) and references a sibling tool for custom sizing. The tool is complex, and the description leaves no significant gaps.

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

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

Schema description coverage is 100%. The description goes far beyond the schema by explaining internal algorithms for each parameter (monotonicity checks, partition sum, fill calculation) and providing concrete examples (slugs like 'fed-decision-may-2026', seed questions). This adds significant meaning for proper parameter use.

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

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

The description explicitly states the tool's purpose: find arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending_scan, event, topic) and provides clear examples, differentiating it from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description gives explicit when-to-use guidance for each mode: no args for trending_scan, event for specific markets, topic for cross-event scanning. It explains the logic behind each mode, including conditions to avoid (e.g., placeholder slugs, low similarity) and references sibling tools for custom sizing, providing comprehensive usage instructions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the description is not burdened with basic safety. It adds significant behavioral details: caching at KV level keyed on all knobs (1h), edge calculation net of slippage, Kelly sizing caps, and diagnostics for empty segments. 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 comprehensive but quite verbose (almost an entire paragraph of dense technical detail). It is well-structured with segments and bullet-like lists, but could be trimmed for quicker agent parsing. The front-loading of the main purpose is good, but the rest is heavy.

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 nested behavior, the description provides thorough context: response structure (by_segment, fed_candidates, diagnostics), edge calculation details, knob behaviors, and caching policy. It fully compensates for the lack of output schema by describing return fields in 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 coverage is 100% with good descriptions in the schema itself. The description adds extra context for key parameters like min_partition_leg_kelly (explaining why min_kelly doesn't apply to partitions) and slippage_pp (Polymarket fee context). This additional semantics justifies a score above baseline 3.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the exact model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge detection with multiple signal 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?

The description explicitly says 'Built for "what should I bet on today"' and mentions scenarios like Fed bets being excluded. It provides context on when to use tradeable-edge knobs (min_liquidity, max_spread_pp) and filtering. However, it doesn't explicitly contrast with other Polymarket tools or state when not to use it.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description goes beyond by detailing response structure (tracked, expired, snapshot_dates), decay computation, and limits (60-day TTL, daily closes vs intraday), providing rich behavioral context.

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

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

The description is well-structured with clear sections (RESPONSE, LIMITS) and front-loaded with purpose. Every sentence adds value with no redundancy, making it concise yet informative.

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

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

Given the two simple parameters and absence of output schema, the description fully explains return fields (tracked items with time-series, expired items with lifespan, snapshot dates) and limitations, making it complete for effective use.

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

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

Input schema covers both parameters with descriptions, but the description adds defaults (days=14, window='1wk') and enumerates allowed values for window, which significantly aids usage beyond the schema alone.

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

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

The description clearly states this tool provides 'edge persistence and decay telemetry' from daily snapshots, distinguishing it from sibling `polymarket_edges` which likely gives current edges. The high-level question further clarifies its unique 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 implies usage for historical edge analysis vs. current edges from `polymarket_edges`, but does not explicitly state when not to use it or provide comparative alternatives among the sibling tools.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing safety. The description adds detailed behavioral context: walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), and explains the dominant loss mode (partial basket fills). No contradictions.

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

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

The description is lengthy (~200 words) but well-structured: summary sentence, required-parameter note, then separate sections for single-market and basket modes, finishing with usage guidance. Minor verbosity, but every sentence adds value for a complex tool with two modes.

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, no output schema), the description covers nearly all necessary aspects: modes, required parameters, return fields (including risk metrics like thin_legs and forced_directional_risk), and usage guidance. Could be improved by defining verdict values ('clean', 'degraded', 'cannot_fill') more explicitly, but still highly complete.

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

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

Schema coverage is 100%, providing baseline a 3. The description adds significant value beyond the schema: it clarifies that one of market or event is required (not reflected in schema optionality), explains side auto defaults for basket, and elaborates on size_usd interpretation (max spend vs target proceeds, clamp bounds). This greatly aids correct invocation.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', with two distinct modes (single-market and basket). It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by specifying it is a pre-trade risk check. The verb 'check' and resources 'market'/'event' are specific and not tautological.

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 THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It provides context for when to use (before significant trades) and warns against partial basket fills converting arbitrage into directional risk. No alternatives are listed, but the instruction is clear and actionable.

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

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

The description thoroughly discloses behavioral traits: compatibility_warning conditions, temporal alignment checks, skipped cross-type/subtype counters, and that pre-mapped topics may not yield tradeable spreads. Annotations indicate read-only, idempotent behavior, and the description aligns with these.

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 and well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). However, it is somewhat lengthy; minor trimming could improve conciseness without losing information.

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

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

Despite no output schema, the description fully explains the response structure (leg-by-leg prices, spreads, safety fields) and their meanings. Given the complexity of cross-venue spread computation, this is highly complete.

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

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

Schema coverage is 100%, and the description adds significant context: the list of topic shortcuts, explanation of explicit tickers, and how they override the topic side. This goes beyond the schema definitions.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like polymarket_arbitrage by focusing on cross-venue comparisons.

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

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

The description explains two modes (topic shortcuts vs explicit tickers) and when to use each. It warns that pre-mapped topics often return warnings, setting expectations. However, it does not explicitly contrast with alternatives like polymarket_arbitrage or specify when not to use this tool.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds dual behavior (retrieve/list) and pairing with remember/forget, but could detail return format more.

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 fluff, efficiently conveys all needed 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?

Covers purpose, usage, scoping, and sibling relationships well. Missing explicit return format or error handling, but sufficient given no output schema.

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

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

Schema coverage is 100% and description paraphrases the schema's parameter description without adding new semantic details.

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, distinguishing it from sibling tools (remember, 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?

It explicitly advises when to use: to look up stored context without re-deriving, and implies when not (use forget for deletion). Also notes scoping to identifier.

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

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

The description adds significant behavioral context beyond annotations: it explains that mark_read:true flags events as read to affect future calls, describes the content of alerts, and notes the tool returns the most recent alerts. Annotations already indicate safety, and the description enriches understanding without contradiction.

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

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

The description is four sentences, each serving a distinct purpose: stating the purpose, listing returned fields, explaining filtering and mark_read, and noting polling and an alternative endpoint. No superfluous content.

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 covers return contents, parameter usage, behavioral effects (mark_read), and practical concerns (polling, alternative access). It is thorough enough for an agent to use the tool correctly.

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

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

With 100% schema coverage, baseline is 3. The description adds value by explaining the filtering effect (e.g., example type 'sec_8k', mark_read behavior) and the relationship between parameters like since and mark_read, going beyond the schema's basic descriptions.

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

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

The description clearly states the tool retrieves recent alerts from a subscription feed, specifying the data returned (source, citation_uri, raw payload). It distinguishes itself from sibling tools like list_subscriptions or subscribe by focusing on fired events.

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

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

The description indicates polling is appropriate and mentions an alternative REST endpoint for scripts/dashboards, providing context for when to use this tool versus other access methods. It does not explicitly state when not to use it, but the guidance is effective.

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

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

The description adds significant behavioral context beyond the annotations, including details about fanning out to multiple sources, fallback mechanisms, and soft-fail for patents. All behavioral claims are consistent with the read-only, idempotent, non-destructive annotations.

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

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

The description is front-loaded with example queries and is structured in clear paragraphs. While it is relatively long, every sentence adds value, and the information is well-organized without redundancy.

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

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

Given the tool's complexity (multiple data sources, date handling, fallback) and the absence of an output schema, the description provides a high-level overview of the return structure but lacks specifics on the exact format of the changes array or citation URIs. This leaves some gaps for an AI agent.

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

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

Schema coverage is 100% and each parameter is described in the schema. The description enriches this with example values (e.g., '7d', '30d') and best practices (e.g., 'Use "30d" or "1m" for typical monitoring'), adding value beyond the schema.

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

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

The description clearly states the tool provides a change feed for a company in a given timeframe using specific verbs like 'What's new', 'latest', and 'updates'. It distinguishes itself from the sibling tool 'entity_profile' by explicitly noting when to use that alternative for static profiles.

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

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

The description provides explicit guidance on when to use this tool versus alternatives, including example queries and a recommendation to use 'entity_profile' for static profiles. It also advises on typical monitoring values for the 'since' parameter (e.g., '30d' or '1m').

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds valuable context: 'Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours' and 'scoped by your identifier'. No contradiction with annotations.

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

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

Three well-structured sentences, front-loaded with purpose, each sentence adds unique value. No redundancy.

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

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

Given only two simple parameters and no output schema, the description covers purpose, usage, persistence behavior, and relationship to sibling tools. 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 already provides clear descriptions for both key and value (100% coverage). The description adds context with example key patterns and value types, but the schema is already sufficient. Still, it adds moderate extra value.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' and specifies it is a key-value store scoped by identifier. It distinguishes from siblings like recall and forget by mentioning them as complementary tools.

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

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

The description explicitly advises when to use: 'when you discover something worth carrying forward' and provides examples (resolved ticker, target address, user preference). It also mentions alternatives: 'Pair with recall to retrieve later, forget to delete.'

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, and non-destructive. The description adds valuable context beyond these: it cascades through several endpoints, degrades gracefully, explicitly labels sources, and states unresolved identifiers. This meaningfully supplements 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 dense but well-structured, front-loading examples and separating supported types with clear sections. Every sentence carries information, and the length is justified by the tool's complexity. It is not overly verbose for the amount of behavior it covers.

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

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

Given the absence of an output schema, the description thoroughly explains expected return content for both entity types, including source labels, unresolved handling, and graceful degradation. It also conveys the internal multi-endpoint nature, making the tool's behavior predictable for an agent.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The tool description further enriches understanding by detailing what each type returns (e.g., CIK, LEI, FIGI for company; RxCUI, ingredient, brand for drug) and the cross-source identity spine, going beyond the schema.

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

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

The description uses a specific verb ('resolve') with an explicit resource (user-spoken name to canonical identifiers) and provides concrete usage examples. It clearly distinguishes from sibling tools by emphasizing it is the first step for name-to-ID conversion, a niche none of the siblings cover.

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

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

The description gives a precise when-to-use directive: 'Use FIRST whenever you have a name but need an ID.' It also enumerates supported types with input formats. It lacks explicit when-not-to-use scenarios or alternative tool mentions, but the guidance is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds valuable context: it probes each entity with ai_visibility_check, ranks results, and returns per-entity score, confidence, and signal density. No contradiction with annotations.

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

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

Three sentences, front-loaded with the main action. Every sentence adds value: action, mechanism, use case, output. No redundant or filler content.

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 4 parameters, 100% schema coverage, no output schema, and annotations covering safety, the description adequately explains behavior and output structure (ranked list with metrics). It lacks details on pagination or error handling, but given the tool's simplicity, it is sufficiently 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. The description adds meaning beyond schema by explaining that the first entity is treated as the 'subject' for narrative and that context disambiguates common names. This helps the agent understand parameter intent.

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 ('Compare') and resource ('AI visibility across multiple entities'), clearly distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (likely different comparison method). It details the process of probing, ranking, and surfacing recognition scores.

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?

States explicit use case ('competitive AI-marketing audits') and provides an example question. Implies when to use this tool over ai_visibility_check for multi-entity comparison, but lacks explicit 'when not to use' or alternative tool mentions beyond the sibling list.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timeouts. This goes beyond annotations.

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

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

The description is a single long paragraph, front-loaded with purpose but dense. It contains necessary details but could be more structured (e.g., bullet points for return fields). It is moderately concise given the complexity.

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

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

Given the complexity (multiple sources, output, failure modes), the description covers the main points: return summary block fields, per-advisory detail, links, alternative versions, and graceful degradation. Without an output schema, this is sufficient for most 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 the description adds nuance: 'package' is npm package name and scoped packages are accepted, 'version' defaults to latest published. It also explains the composite nature combining two services, adding meaning beyond the bare schema descriptions.

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

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

The description clearly states the tool does a composite check for adding npm packages, combining deps.dev and bundlephobia. It specifies the exact verb ('scan'/'check') and resource (npm package), and distinguishes itself by noting 'NPM ecosystem only in v1', which differentiates from other dependency tools.

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

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

Explicit when-to-use guidance: 'Use whenever an agent asks is X safe / popular / small' or 'what does adding lodash cost me'. Also provides when-not-to-use for other ecosystems (PyPI, Maven, etc.) and directs to deps.dev directly. This clearly helps the AI decide.

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, etc.), the description reveals key behaviors: BGE-base-en embeddings, cosine over 500-char windows, 200K char cap with truncation flagging, and output includes offsets and similarity scores. No contradiction with annotations.

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

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

Three sentences, each earning its place: purpose and use case, how it works, technical details. No wasted words. Front-loaded with the key action.

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

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

Given no output schema, the description adequately describes the return format (passages with offsets and scores). It covers input, output, constraints, and even pairs with another tool, making it complete for an agent.

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

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

With 100% schema coverage, the description adds value by clarifying 'text' as document text, 'limit' as max passages, and 'query' as natural-language query with examples. It also mentions the 200K cap and truncation, exceeding the schema.

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

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

The description clearly identifies the tool as performing semantic search inside a fetched record, using specific examples like SEC 10-K and articles. It differentiates from sibling tools like ask_pipeworx_grounded by explaining when to use each.

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 to use this tool when the record is too large for the prompt, saving context. It also pairs with ask_pipeworx_grounded. However, it does not explicitly mention when not to use it or provide exclusions.

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

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

The description adds significant behavioral details beyond annotations: OAuth requirement, SMS cap (10/day), webhook auto-disable after 10 failures, and the one-time nature of the webhook signing secret. Annotations (readOnlyHint=false, idempotentHint=true) are not contradicted; the creation action aligns with a non-read operation, and the description does not conflict with idempotency (though not explicitly stated).

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 two paragraphs: core purpose and requirements, then detailed types and delivery channels. It is informative without being verbose, though some type-specific details could be streamlined. The first sentence clearly states the tool's 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?

Given the lack of output schema, the description clearly states the return value ('Returns the new subscription id'). It covers prerequisites, all subscription types with parameter formats, delivery options with constraints, and error behavior (webhook auto-disable). This provides an agent with sufficient information to use the tool correctly.

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

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

Schema coverage is 100%, and the description enriches parameter meaning with concrete examples for each subscription type (e.g., sec_8k items codes, polymarket_edge topic, fred_series series_id). It also adds constraints like SMS delivery requiring verified phone and webhook restrictions (HTTPS only, localhost rejected). 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 begins with a clear verb+resource statement: 'Create a proactive monitoring subscription to a live-data event stream.' It explicitly names the output ('Returns the new subscription id') and distinguishes the tool from siblings like 'list_subscriptions' and 'unsubscribe' which cover different actions on subscriptions.

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

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

The description provides context on when to use the tool (creating subscriptions) and includes prerequisites ('Requires a Pipeworx OAuth account'). It also lists supported subscription types with examples, implying appropriate scenarios. However, it does not explicitly contrast with tools like 'recent_alerts' that might serve as alternatives for one-time alert checks.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive. Description adds that it returns example questions with tool+argument shapes, drawn from a live catalog, and supports optional topic filtering. No contradictions or missing behavioral traits.

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

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

Well-structured and front-loaded with alternative phrasings, but slightly verbose. Every sentence contributes value, though could be tightened.

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

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

For a simple onboarding tool with one optional parameter and no output schema, the description fully explains its purpose, usage, and when to invoke it. No gaps given its 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%, and description goes beyond by explaining the 'topic' parameter's purpose, listing possible focus areas, and noting that omitting it gives a full spread.

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 category-bucketed example questions from the live tool catalog, serving as an onboarding entry point. It distinguishes from sibling tools by focusing on suggesting questions rather than answering them directly.

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

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

Explicitly says to use this tool first when unsure what Pipeworx can do, and to learn meta-tool calls. No explicit when-not-to-use, but the context is clear enough.

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

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

Discloses key behavioral detail beyond annotations: 'The row is deactivated (not deleted) so its historical events stay available via recent_alerts.' This clarifies side effects and complements the annotations (destructiveHint=false).

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. Front-loaded with action verb and object. Every sentence adds essential information.

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

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

For a simple single-parameter tool with no output schema, the description provides complete understanding: what it does, constraints, side effects, and relation to other tools. Combined with annotations, it is fully adequate.

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

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

Schema has 100% coverage with a clear parameter description. The description adds cross-reference ('returned by subscribe'), adding marginal value beyond the schema. Baseline score of 3 is appropriate.

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

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

Description clearly states the action ('Cancel a subscription by id') and distinguishes from sibling 'subscribe'. It specifies the resource and the precise operation.

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 mentions ownership enforcement ('you can only cancel your own subscriptions'), providing clear usage context. Does not explicitly state when not to use or name alternatives, but the context is sufficient.

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

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

The description goes beyond the annotations (readOnly, openWorld, idempotent) by explaining critical behavioral nuances: the meaning of could_not_verify (the check failed, not evidence), the distinction between unsupported and could_not_verify, and the source-routing behavior. This is exactly the kind of context agents need.

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

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

The description is detailed and information-dense, but it is longer than ideal. It fronts the key trigger phrases, but the critical warning about could_not_verify is placed later in a long paragraph. Still, every sentence carries useful information, and the structure is logical.

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

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

Given there is no output schema, the description thoroughly explains the return values (verdict list, actual value with citation, reasoning), the important error semantics, and the two processing pipelines. It is complete enough for an agent to use the tool correctly and interpret results.

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

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

Schema coverage is 100% and both parameters already have detailed descriptions, including the tolerance_pct behavior and claim examples. The tool description itself does not add additional parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It includes explicit example phrasings, distinguishes claim verification from other research tools, and mentions the verdict output types. This 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 explicitly states when to use this tool: 'whenever the agent needs to check whether something a user said is factually correct.' It also explains the two internal paths (SEC EDGAR for financial claims, grounded pipeline for anything else) and notes that it replaces 4–6 sequential calls, providing clear usage context.

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