Coingecko

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by disclosing that the default model is free (Workers AI) and that probing Anthropic requires a BYO key with direct payment. It also outlines the return structure (per-model {score, confidence, signals, raw_response} + combined view), which is not in the annotations. No contradiction.

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

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

The description is three sentences long, front-loads the primary purpose, and contains no redundant or irrelevant information. Every sentence serves a clear function: stating the action, detailing configuration, and listing output structure. It is efficient and well-structured.

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

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

Despite lacking an output schema, the description fully explains the return format (per-model structure + combined view) and covers all parameters with examples. For a tool with 4 parameters and no output schema, this is complete and sufficient for an agent to understand invocation and expected 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 description coverage is 100%, so baseline is 3. The description enhances parameter meaning by providing concrete examples for entity (e.g., 'Pipeworx', 'Acme Corp pricing') and clarifying that _apiKey is 'passed straight through to api.anthropic.com'. It also explains the purpose of context ('helps disambiguate common names'). These additions go beyond the schema's basic 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 uses a specific verb 'Probe' and a clear resource 'LLMs', defines the output as a visibility score (0-100) per model, and explicitly lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). This distinguishes it from siblings like scan_competitor_ai_presence by focusing on AI visibility scoring.

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 states when to use the tool: for AI-marketing audits, pre-launch brand checks, and competitive monitoring. It implicitly provides context by mentioning default model and BYO key for Anthropic, but does not explicitly exclude alternatives or compare to sibling tools like scan_competitor_ai_presence, which would warrant a 5.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context: it routes across 5,798 tools, fills arguments, returns a structured answer with stable pipeworx:// citation URIs, and is positioned as a fast default entry point. This goes beyond the annotations without contradicting them.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and organized around purpose, examples, and escalation paths. Some later parts become list-like, but the structure is navigable and the content earns its place for a broadly scoped tool.

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

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

Given the absence of an output schema, the description covers the essentials: input type, routing behavior, answer format, citation scheme, examples, and when to step up to sibling tools. It does not discuss failure behavior or unsupported query types, but for a general-purpose query tool this is reasonably complete.

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

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

Schema coverage is 100%, so the schema already documents all six parameters, including the question field and its aliases. The description's examples reinforce the natural-language input style but do not add significant meaning beyond what the schema provides. A 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 identifies a specific verb and resource: ask Pipeworx a natural-language factual question, which it routes to the right underlying tool and answers with citation URIs. It also distinguishes itself from siblings like ask_pipeworx_grounded, deep_research, and web search, so an agent can tell them apart without opening schemas.

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: prefer over web search for factual/structured-data questions, use for queries starting with 'what is', 'look up', 'find', etc. It also names alternatives and escalation conditions: ask_pipeworx_grounded for verbatim-evidence single answers and deep_research for broad/multi-part questions.

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

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

Beyond the readOnly, openWorld, idempotent, and non-destructive annotations, the description clarifies that routing behavior may change live depending on active candidates and that currently no candidate is active. It also corrects a likely assumption by stating there is no fallback—this is a fully working router with an experimental edge. No contradiction with annotations.

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

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

The description is well-organized, front-loaded with the key identity and current state, and every sentence adds relevant context. It is slightly longer than necessary due to some repetition of 'same ... same ...' and 'matches exactly,' but the rhetorical clarity remains high.

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 complex universal router with no output schema, the description provides critical operational context: current parity with the stable version, experimental behavior, and confirmation that it is a fully working router. The response shape is stated to be identical to ask_pipeworx, allowing an agent to infer behavior from the sibling tool. It stops short of describing the exact return format, but the sibling comparison covers that gap adequately.

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

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

Schema coverage is 100%, so the schema already documents all parameters and aliases. The description only says 'same arguments,' which assures compatibility with ask_pipeworx but adds no new semantic detail. 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 immediately identifies ask_pipeworx_beta as the experimental variant of ask_pipeworx and explains it is the same universal router over 5,798 tools. It clearly distinguishes this from the stable ask_pipeworx sibling and states its function as a question-router. The detail about identical arguments and response shape removes ambiguity.

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 an explicit condition for use: use exactly like ask_pipeworx when you want the newest routing. It also explains that results are compared against the stable router. It does not explicitly state the inverse condition (prefer stable ask_pipeworx for production), but the beta/stable framing makes that context clear.

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

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

Annotations already mark this as read-only and non-destructive, but the description adds materially richer behavioral context: the exact success return shape, explicit refusal reasons, the extraction-only guarantee, and the extra LLM call cost. No contradiction with annotations exists.

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 not bloated; every sentence carries distinct information: purpose, routing behavior, output/refusal contract, usage guidance, and cost trade-off. The most important distinction is front-loaded before the longer behavioral details.

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 compensates by specifying the success response fields and all refusal reason values. It also covers the key selection context, cost, and relationship to ask_pipeworx, making it complete for correct invocation and decision-making.

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

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

Schema coverage is 100%, with the question parameter and all aliases already documented in the schema. The description adds no new parameter-level meaning, but it does not need to because the schema fully explains the only meaningful input.

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

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

The description states a specific purpose: a hallucination-resistant answer mode that extracts answers only from the fetched tool result. It clearly differentiates from ask_pipeworx by emphasizing groundedness and the no-invention constraint, making sibling selection unambiguous.

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

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

Explicitly says when to use this tool: whenever an answer will be quoted, cited, or acted on, especially in high-stakes domains like financial, legal, or medical lookups. It also gives an exclusion rule, preferring ask_pipeworx for casual lookups, and notes the extra LLM call cost.

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

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

The description discloses numerous behavioral traits beyond annotations: low-confidence short-circuit, closed market handling, wide spread warnings, cancellation rule parsing, and resolver match confidence levels. It explains the response structure and edge cases comprehensively. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

The description is lengthy but well-structured with labeled sections (e.g., RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR). It front-loads the core action and use cases. While every sentence adds value, it could be slightly more concise for quick scanning. Overall, it earns its length given the tool's complexity.

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

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

The description covers all relevant context for the tool: inputs, processing steps, output shapes, edge cases (low-confidence, closed markets, wide spreads), cancellation rules, and safety mechanisms. Without an output schema, it thoroughly describes the response structure. It is complete given the tool's complexity and the richness of annotations.

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

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

With 100% schema description coverage, the description still adds value: it explains the 'depth' parameter (quick vs thorough), the 'market' parameter accepts multiple formats (slug, URL, question text), and 'include_raw' controls verbosity. It also provides examples and clarifies default behavior, going 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's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the inputs (slug, URL, question text) and outputs (evidence packet + comparison). It distinguishes from sibling tools by being specifically for Polymarket bets with Pipeworx data, which is unique among the listed siblings.

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

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

The description explicitly provides use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It includes classifiers and fan-out examples, giving clear context. However, it does not explicitly state when NOT to use this tool or suggest alternatives, which would further strengthen guidance.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) indicate safe, read-only, idempotent behavior. Description adds critical behavioral details: off-calendar fiscal year handling, result sorting by primary metric, return format with citation URIs. No contradictions.

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

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

Front-loaded with example queries. Every sentence provides value (examples, purpose, behavior description, return format). Slightly verbose but justified by the complexity of the tool.

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

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

No output schema, but description explains return format: 'paired data + pipeworx:// citation URIs per entity.' Also mentions replacing multiple lookups. Could detail error handling for missing entities, but sufficient for the tool's complexity.

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

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

Schema coverage is 100%. Description adds examples (tickers/CIKs for company, drug names for type) but does not significantly expand beyond what the schema already provides (enum for type, min/max items for values). Adequate but not exceptional.

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

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

Description starts with user query examples, then explicitly states: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly defines what each type does (financials for company, adverse-event data for drug). Differentiates from sibling 'entity_profile' which appears to handle single entities.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides context for when to use this tool. Does not explicitly list exclusions, but the guidance is strong and clear.

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

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

Beyond the annotations (read-only, idempotent, non-destructive), the description discloses many behavioral traits: account and paid-tier requirements, parallel tool routing, returned evidence fields, explicit gaps[] for unanswered facets, contradictions[] scans, semantic excerpting, citation fetchability, and expected latency. It even states that findings are never invented, which is valuable risk information.

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

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

The description is long but front-loaded with the most critical operational constraint (account required) and the key alternative (ask_pipeworx). Each paragraph adds useful context, though some depth details repeat what is already in the schema, preventing a perfect score.

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

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

For a complex research tool with no output schema, the description is remarkably complete: it explains the return packet structure, confidence/source/citation fields, gap handling, contradiction behavior, excerpting, latency, and depth-tier differences. An agent has enough information to know what to expect and how to invoke 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?

The input schema already covers both parameters fully, including depth's enum semantics and the question's natural-language, broad/multi-part nature, so the baseline is 3. The description adds some operational context such as paid-tier requirements and latency expectations, but it does not materially enrich the parameter meaning beyond what the schema already provides.

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

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

The description uses a specific verb and resource: "Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources... in ONE call." It clearly distinguishes itself from open-web search and from the simpler ask_pipeworx sibling, and it names the intended use case: broad/multi-part questions over structured data.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use ask_pipeworx if not signed in, and use ask_pipeworx for a single lookup. It also gives concrete example questions that fit the tool's purpose, so an agent can confidently route to 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, destructiveHint=false. The description adds value by explaining that results include 'full input schemas (with curated examples)' and that each result is 'ready to call directly'. No contradictions with annotations. It gives a clear picture of behavior without requiring additional lookup.

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

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

The description is concise (4 sentences) and front-loaded with the core purpose. Every sentence adds value: first sentence states action, second lists use cases, third explains output format, fourth gives usage guidance. No redundancy or filler.

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

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

Given the tool has 6 parameters, no output schema, and moderate complexity (aliases), the description adequately covers what an agent needs: purpose, when to use, output format (names, descriptions, schemas with examples), and a usage hint. It doesn't detail the exact response structure, but the lack of an output schema is mitigated by the description of what each result contains.

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%, meaning all 6 parameters are documented in the schema. The description does not add new detail about param syntax beyond what the schema provides (e.g., aliases are already listed). However, it does give high-level examples of task descriptions, which indirectly help with query formulation. 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 uses specific verbs ('Find', 'browse', 'search', 'discover') and identifies the resource ('tools'). It lists concrete use cases (SEC filings, financials, FDA drugs, etc.) and distinguishes the tool from sibling tools by positioning it as a discovery/exploration tool rather than a specific data 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?

The description explicitly states when to use this tool ('Call this FIRST when you have many tools available'). It does not provide explicit when-not-to-use guidance or list alternatives, but the context (sibling tools are all specific) and the instruction to use it for 'browsing' versus direct answering make usage clear.

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

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

Annotations already mark this as readOnly, idempotent, openWorld, and non-destructive. The description goes far beyond that by disclosing the parallel fan-out across many sources, soft-fail behavior for the USPTO API sunset, the semantics of empty sections and sources_used/sources_failed, name resolution via SEC EDGAR, and the private-company resolved:false behavior. No contradiction with annotations exists.

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

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

The description is long, but every sentence carries operational meaning and the layout is disciplined: trigger phrases first, then sources, then return sections, then input rules, then edge cases. The dense semicolon-separated list is an appropriate structure for a tool with this much behavioral surface area. It is front-loaded and contains no filler.

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

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

There is no output schema, so the description must carry all return-semantics weight. It does: it enumerates every returned field, the source behind each, the failure behavior, the resolution behavior, and the meaning of empty sections. Given the tool's complexity and the absence of an output schema, the description is complete enough for an agent to invoke it correctly and interpret results accurately.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantics beyond the schema: it clarifies that 'type' accepts 'company' and 'ticker' interchangeably, that 'value' can be a ticker, zero-padded CIK, or company name, and that names resolve via EDGAR. It provides concrete examples for each accepted shape, which materially improves an agent's ability to supply correct inputs.

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

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

The description opens with concrete trigger phrases and immediately states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It names the resource ('company profile') and distinguishes itself from chaining single-pack lookups by explicitly saying it is preferred for holistic views. This is unambiguous and clearly differentiated from sibling research 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?

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides example query phrasings and enumerates accepted input forms. Edge cases are covered: private companies return resolved:false, empty sections are real 'no data,' and person/place support is 'coming soon.' This gives the agent 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?

Description adds minimal context beyond annotations (e.g., 'clear sensitive data'). Annotations already declare destructiveHint=true and readOnlyHint=false, so the description adds little new behavioral insight.

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

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

Two sentences, no wasted words. Action verb is front-loaded, and the description is compact 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?

For a simple tool with one parameter and no output schema, the description is fully adequate. It tells what the tool does, when to use it, and how it relates to other tools.

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

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

Schema covers the single parameter 'key' with a clear description ('Memory key to delete'). Description does not add additional meaning beyond the schema, resulting in a baseline score of 3.

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

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

Description clearly states 'Delete a previously stored memory by key.' This is a specific verb+resource combination that distinguishes it 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 ('context is stale, task done, clear sensitive data') and pairs with 'remember' and 'recall' as alternatives.

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

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

Annotations already declare read-only and idempotent behavior. The description adds specific process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This provides useful context beyond annotations without contradiction.

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

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

The description is a single, well-structured paragraph that front-loads the primary purpose and efficiently covers usage, behavior, and output format with no extraneous words.

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

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

For a simple tool with 2 parameters, no output schema, and full annotation coverage, the description is complete. It explains the input, process, and output format ('single text blob ready to drop at site-root/llms.txt').

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 default and max for 'max_links' ('default 25, max 50'), but does not significantly extend meaning beyond the schema.

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

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

The description clearly states the verb 'Generate' and the resource 'llms.txt file for any URL', and distinguishes the tool from siblings like ai_visibility_check and scan_competitor_ai_presence by specifying its unique purpose for AI crawler indexing.

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

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

The description explicitly lists use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It lacks explicit when-not to use, but the use cases are clear and direct.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying exact return fields (price, market cap, changes, etc.) and that data is 'live', which complements annotations without contradiction.

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

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

Two sentences, no wasted words. Purpose is front-loaded, then return details are listed. Perfectly concise and well-structured.

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

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

Given the simple tool (1 param, safe annotations, and an output schema present), the description is complete. It covers what the agent needs to know without redundancy.

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% on the single 'id' parameter, with a clear description and examples. The tool description reinforces the format (lowercase) and provides examples, adding marginal 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 states 'Get live cryptocurrency data by CoinGecko ID' with a specific verb and resource, and lists exact return fields (USD price, market cap, etc.). It clearly distinguishes from sibling tools like search_coins, which are for discovery.

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

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

No explicit when-to-use or when-not-to-use guidance is given. The context of sibling tools implies use for specific coin data vs. search_coins for searching, but the description itself does not address 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and side effects. The description adds behavioral context about the data returned (prices, changes, volume) and ranking method (market cap), which goes beyond annotations without contradicting them.

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

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

The description is a single, clear sentence followed by a helpful example. No unnecessary words or repetition; every part earns its place.

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

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

Given the presence of an output schema (not shown but indicated), the description does not need to detail return values. It covers the core functionality and example usage, and the annotations handle safety and idempotency. The description is complete for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already fully describes all three parameters (limit, order, vs_currency). The description does not add new semantic information beyond the schema; it only provides an example that mirrors the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb 'Get', the resource 'top cryptocurrencies ranked by market cap', and the specific data fields (current prices, 24h changes, volume). It distinguishes from sibling tools like 'get_coin' (single coin) and 'get_trending' (trending coins), making the purpose unambiguous.

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

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

The description provides an example usage but does not explicitly state when to use this tool versus alternatives or mention any exclusions. The example implies typical use, but there is no direct guidance on selection criteria beyond the inferred purpose.

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 a safe, read-only, idempotent operation. The description adds value by specifying the output fields (coin IDs, names, symbols, market cap ranks, trend scores) and the ranking criterion (24-hour search activity), providing context beyond annotations.

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

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

Two concise sentences front-load the purpose and list outputs. 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?

Given no parameters and an existing output schema, the description provides enough context: what the tool does, how it ranks, and what it returns.

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

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

The description states 'No parameters required,' which matches the empty input schema. With 0 parameters, the baseline is 4, and the description adds no extra parameter meaning but is sufficient.

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

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

The description clearly states the tool retrieves top trending cryptocurrencies on CoinGecko, ranked by 24-hour search activity, and lists the specific fields returned. This distinguishes it from siblings like search_coins or get_coin.

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 notes 'No parameters required,' making usage obvious. However, it does not provide explicit guidance on when to choose this tool over alternatives like search_coins or get_coin, though the purpose 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?

The description adds value beyond annotations by detailing the return fields (id, type, params, timestamps, fire_count). Annotations already declare readOnlyHint=true and destructiveHint=false, so additional behavioral context is minimal but sufficient.

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 that efficiently convey purpose, return fields, and usage. No unnecessary words, front-loaded with key information.

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

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

For a simple list tool with one parameter and no output schema, the description fully explains what the tool does, what it returns, and when to use it. No gaps.

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

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

Schema description coverage is 100% for the single parameter 'include_inactive'. The description does not add extra meaning beyond what the schema already provides, so 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 lists the caller's active subscriptions, specifying the resource and action. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing.

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.' While it doesn't list exclusions, the context is clear and helpful.

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 the full burden. It discloses the rate limit (5 per day), the free/quota-free nature, the claim_token return behavior and follow-up mechanism, and that reports are read daily and influence roadmap. This is exceptional transparency beyond the schema/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 longer than typical but nearly every sentence adds distinct information. It could be tightened by dropping the motivational sentence about roadmap impact, and the rate limit/quota-free info could be condensed, but it remains well-structured and front-loaded with 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?

Despite lacking an output schema, the description fully explains the token-based follow-up and the behavioral contract (account-optional, rate limit, scope). All four parameters are covered in both schema and description, and the nuanced use case (reporting issues about Pipeworx tools vs. other servers) is thoroughly addressed.

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

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

Schema coverage is 100% with each parameter described, so the baseline is 3. The description adds valuable usage nuance: the claim_token reuse pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and a strong instruction to describe issues in terms of Pipeworx tools/packs rather than pasting user prompts. This enhances but does not fully replace schema detail.

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

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

The description opens with a specific verb-resource pair ('Tell the Pipeworx team') and immediately defines the tool's scope: broken, missing, or needs-to-exist items. It clearly distinguishes this from sibling tools by explicitly noting it is only for tools served by this Pipeworx connection, ruling out other MCP servers.

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 feedback type (bug, feature/data_gap, praise) and a clear when-not-to-use exclusion for tools from other MCP servers. It also provides a rule of thumb for identifying Pipeworx tools, making usage unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds caching details (5min-1h), data source (CF analytics-engine), and privacy assurance (no PII), providing valuable behavioral context beyond annotations.

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

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

The description is well-structured with bullet points for use cases and clear sections. While informative, it is slightly verbose; could be tightened slightly without losing clarity.

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

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

The tool is simple with one optional parameter. The description fully explains what is returned (top tools, packs, call volume) and caching behavior. No output schema is needed given the clarity. Complete for the tool's complexity.

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

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

Schema coverage is 100% with a description for the 'window' parameter. The tool description adds the purpose of each window choice (hot trends vs steady-state demand), enhancing semantic understanding beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a window. It specifies the verb 'returns' and the resource 'what other AI agents are calling on Pipeworx'. This distinguishes it from siblings like 'get_trending' by focusing on AI agent usage trends.

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

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

Three explicit use cases are listed, providing clear guidance on when to use the tool. The description explains window choices (shorter for hot trends, longer for steady-state) but does not explicitly mention alternatives or when not to use it, missing some differentiation from similar tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds rich behavioral detail: logic of monotonicity violations, partition checks, Jaccard similarity filter, placeholder filter, fill check against CLOB depth. Explains response structure and 'do not trade' condition. 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?

Well-structured with logical sections (mode descriptions, semantic anchor, partition filter, fill check). Some redundancy (e.g., repeated mention of recommended mode). For a complex tool, the detail is warranted but could be slightly tighter.

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

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

No output schema exists, so description fully covers return values: opportunities array with fields, partition_check details, fill check output. Explains edge cases (placeholder filtering, low similarity, realizable edge). Complete for a complex arbitrage detection tool.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enriches understanding with examples ('fed-decision-may-2026'), accepted URL format, 'recommended' usage, and explanation of cross-event behavior. Goes well beyond schema detail.

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

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

The description clearly states the verb ('Find arbitrage opportunities') and resource ('on Polymarket'), specifies the methods (monotonicity violations + partition-sum checks), and distinguishes three distinct modes (trending_scan, event, topic). It effectively differentiates from sibling tools like polymarket_edges or 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?

Provides explicit usage guidance for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. Also advises when not to trade (realizable_edge_pp <= 0). Lacks direct comparison to alternatives but gives clear context for each mode.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value beyond these by noting that the tool is cached 1h at the KV level keyed on all knobs, explaining the output structure (by_segment, diagnostics), and detailing the behavioral traits of each model family. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections for MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT, and parameter explanations. It front-loads the purpose and key behavioral aspects. Some redundancy exists (e.g., repeating cache info), but overall it is appropriately sized for the complexity.

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

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

Given the complexity (9 parameters, detailed output without output schema), the description is remarkably complete. It explains the output structure top-level fields (by_segment, fed_candidates, _diagnostics), the caching behavior, and provides enough detail for an agent to understand what each part means. No critical missing information.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema: for example, it explains slippage_pp in context of Polymarket's zero trading fees and typical bid/ask spread, and clarifies that min_kelly filters out opportunities too small to bet sensibly. This contextual information helps the agent choose appropriate parameter values.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan', the resource 'Polymarket markets', and the specific output 'opportunities where Pipeworx data disagrees'. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on Pipeworx disagreement and providing a high-level opportunity discovery without paging through hundreds of markets.

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

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

The description explicitly states the intended use case: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also provides guidance on tradeable-edge knobs (min_liquidity, max_spread_pp, etc.) and explains how to use category_filter. However, it does not explicitly state when NOT to use this tool versus alternatives, leaving some ambiguity about when to use polymarket_arbitrage or polymarket_fill_risk instead.

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

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

Adds behavioral details beyond annotations, such as limits on history depth and the fact that decay numbers are daily closes. Annotations already indicate safety, but description provides useful constraints.

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

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

Well-structured with front-loaded purpose, response format explanation, and limitations. Some sentences are lengthy but all contribute value. Slightly verbose for optimal conciseness.

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

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

Comprehensively describes response fields (tracked, expired, snapshot_dates) and limitations. No output schema needed; description covers all expected return values and behaviors.

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

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

Schema description coverage is 100%, and description repeats parameter info with defaults and max values. No additional meaning beyond schema, but clarity is maintained.

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

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

Description clearly states the tool's purpose as edge persistence and decay telemetry, answering a specific question about edge age and trend. It distinguishes itself from sibling tool 'polymarket_edges' by focusing on time-series analysis.

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

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

Provides context such as the contrast between fresh and old edges, and limitations like 60-day TTL and snapshot gaps. Does not explicitly state when not to use, but implicit guidance is clear.

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

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

Annotations already declare safe read-only behavior, but the description adds rich context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about the dominant loss mode. No contradiction with annotations.

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

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

The description is lengthy but well-structured with clear sections (single-market vs basket) and front-loaded purpose. Every sentence adds necessary detail; minor verbosity but appropriate given the complexity of two modes and risk disclosure.

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, full schema coverage, and no output schema, the description is exceptionally complete. It covers both modes, explains all return fields (including thin_legs, forced_directional_risk), and provides usage context and risk warnings—no gaps for the 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%, yet the description adds deep meaning beyond the schema: explains how size_usd is interpreted differently for single-market vs basket, how side defaults work in basket mode ('auto from partition sum'), and clarifies the 'market' vs 'event' exclusivity requirement.

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

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

The description starts with a clear, specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It sharply distinguishes between two modes (single-market vs basket/partition) and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit instruction: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable, partial fills convert arb into directional position), giving clear when-to-use and when-not-to-use 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?

Despite rich annotations (readOnly, idempotent, non-destructive), the description adds substantial non-obvious behavior: compatibility_warning codes, gross-vs-net fee caveats, skipped-leg counters, never-pairing unknown metric_type legs, and temporal_alignment null semantics. This goes far beyond what annotations convey.

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

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

The description is long but organized into labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and front-loaded with the core purpose. Nearly every clause adds value, though it could be tightened 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?

With no output schema, the description carries the full burden of explaining return shape: leg-by-leg prices, top_spreads_pp with per-entry flags, compatibility fields, temporal_alignment null meaning, fee disclosures, and skipped counters. An agent can anticipate the response structure and decide when the output is trustworthy.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning by explaining that kalshi_event_ticker and polymarket_event_slug override the topic-mapped sides and that both modes run the identical token-overlap matcher. It also clarifies the pre-mapped topic list and custom-pairing expectations.

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

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

The description states a precise function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, and details two clear modes. This distinguishes it from siblings like polymarket_arbitrage and polymarket_edges by focusing on same-question venue pairing.

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 explains two usage modes (topic shortcuts vs explicit ticker/slug) and sets expectations by warning that most pre-mapped topics return compatibility_warning today. It provides clear context but does not explicitly exclude sibling alternatives by name.

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

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

Adds scoping details (anonymous IP, key hash, account ID) and pairing context beyond annotations that already declare read-only and idempotent behavior.

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

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

Three succinct sentences front-loaded with purpose, no filler. Every sentence is necessary.

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

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

Single optional parameter, no output schema, but description explains behavior, scoping, and relationship to siblings. Fully complete for agent decision-making.

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

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

Schema coverage 100%; description adds crucial context: omitting key lists all keys, clarifies retrieval vs listing. Fully compensates the simple 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?

Clear verb 'retrieve' and resource 'memory' with explicit differentiation from siblings 'remember' and 'forget'. States both value retrieval and key listing.

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 use cases (look up stored context) and exclusions (omit key to list all). Mentions scoping and companion tools.

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

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

Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. The description adds value by detailing return fields (source, citation_uri, raw payload) and the mark_read behavior for skipping read events.

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

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

The description is a single, well-structured paragraph of ~70 words. It is front-loaded with the purpose and efficiently lists key details 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?

The tool has no output schema, so the description compensates by describing return fields and behavior. Combined with annotations, it fully covers usage for a read-only polling tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context for 'mark_read' (flagging events as read for next call) beyond the schema definition, though other parameters are already well-described 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 verb 'Pull' and specific resource 'fired events from your subscription feed'. It distinguishes from sibling tools like 'list_subscriptions' and 'subscribe' by focusing on reading alerts.

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

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

The description implicitly indicates usage for retrieving recent alerts and mentions a REST alternative for scripts/dashboards. It does not explicitly list when to avoid it or compare to all siblings, but 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?

Beyond the annotations (readOnlyHint, etc.), the description details that it fans out in one parallel call to three sources, names each source, notes the GDELT→GNews fallback, and explains the USPTO soft-failure due to API sunset. This fully discloses behavior.

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

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

The description is dense with valuable information but is somewhat long. It could be slightly more concise, but the front-loaded query examples and clear structure earn a high score.

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

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

Despite no output schema, the description explains the return format: structured changes grouped by source, total_changes count, and citation URIs. It covers all relevant aspects of the tool's operation.

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

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

Schema coverage is 100% and the description adds substantial context: `since` accepts ISO or relative shorthand with examples, `value` accepts ticker or CIK, and `type` is explained as only supporting 'company'. It also gives a typical monitoring suggestion ('30d').

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

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

The description starts with concrete query examples ("What's new with X", "latest on Y"), then explicitly states it provides a change feed for a company, aggregating SEC filings, news, and patents. It also distinguishes itself from the sibling tool `entity_profile` 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 gives clear when-to-use signals with natural language queries and specifies when to use the alternative `entity_profile` (for static profile regardless of window). It also explains the fallback behavior between GDELT and GNews.

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

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

The description adds persistence details beyond annotations: authenticated users get persistent memory, anonymous sessions retain memory for 24 hours. Annotations already indicate idempotentHint=true, and the description does not contradict them.

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

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

The description is concise, front-loaded with the main purpose, and every sentence adds value without redundancy.

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

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

Given the simplicity of the tool (2 params, no output schema), the description covers purpose, usage, persistence behavior, and sibling relationships completely.

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

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

Schema coverage is 100% with descriptions for both 'key' and 'value'. The description further enriches by providing concrete examples ('subject_property') and clarifying return value behavior (none stored).

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 ('Save') and resource ('data') and clearly distinguishes the tool from its siblings 'recall' and 'forget' by stating the pairing.

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 ('when you discover something worth carrying forward') and provides examples. It does not mention 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?

Beyond the readOnly and idempotent annotations, the description discloses important runtime behavior: unresolved identifiers are explicitly listed under 'unresolved', ambiguous security matches return 'figi_candidates', and LEI/FIGI enrichment degrades gracefully when upstream sources are unavailable. This adds substantial behavioral context the annotations do not provide.

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

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

The description is front-loaded with user-phrase examples and a clear usage directive, but it is a very long, dense run-on passage with heavy parenthetical asides. The content is valuable, but the structure makes it harder for an agent to parse quickly than a more sectioned or smaller description would be.

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

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

For a tool with no output schema and high complexity, the description is remarkably complete: it covers accepted inputs, resolved identifiers, ownership data, ambiguity handling, unresolved fields, provenance labels, and fallback behavior. An agent has enough context to call the tool and interpret its results correctly.

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

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

The schema already documents both parameters thoroughly, but the description adds meaning beyond it by mentioning ISIN as an accepted input, explaining ticker-implied mapping for FIGI, and clarifying that the value must be the entity name only rather than the full query phrase. This is useful supplementary guidance, though the schema itself already carries much of the burden.

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 names a specific action — resolving a user-spoken name to canonical/official identifiers — and supports it with concrete examples ('ticker for…', 'CIK for…', 'LEI for…'). It also enumerates supported entity types and what each resolves to, making the tool's scope unmistakable and distinct from sibling tools that operate on already-resolved entities.

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

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

The description gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also clarifies edge cases (non-equity instruments, ISINs, ambiguous matches). It does not name specific sibling tools to use instead, but the context is clear enough for an agent to select 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, idempotentHint, openWorldHint, and non-destructive. Description adds behavioral context: it probes with ai_visibility_check, returns ranked list with score/confidence/signal density, and explains model options (workers-ai default, anthropic requires _apiKey). 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, front-loaded with main action. Information-dense but not overly concise. Could tighten slightly (e.g., reduce example use case) but overall no wasted words.

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

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

Given 4 parameters and no output schema, description covers inputs, process, output format, and use case. Missing error handling or limits (max 8 entities from schema), but sufficient for typical usage.

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

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

Schema coverage is 100%, but description adds meaning: 'first entry treated as subject', 'shared context', and specific model support details (free default vs anthropic with key). These clarify parameter usage beyond schema descriptions.

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

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

The description uses specific verbs ('compare', 'probes', 'ranks') and clearly states the resource ('AI visibility across multiple entities'). It distinguishes itself from siblings like 'ai_visibility_check' (single entity) by emphasizing side-by-side comparison, and from 'compare_entities' by specifying the AI visibility context.

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

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

Description explicitly states when to use ('competitive AI-marketing audits') and what it does (probes each entity with ai_visibility_check, ranks). It implies when not to use (for single entity check, use sibling), but lacks explicit exclusions or alternatives. Still clear and helpful.

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 critical behavioral details beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeout sources. 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?

Every sentence earns its place; the description is dense with useful information. It front-loads the main purpose and then details outcomes and caveats. Length is justified by the tool's composite nature.

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 documents the return value: summary block with specific fields, per-advisory detail, links, and list of alternative versions. Also covers partial failure behavior and latency expectations. Complete for a composite 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% (both parameters described). The description adds that scoped packages like '@types/node' are accepted and clarifies that version defaults to latest published when omitted. Although schema descriptions already cover the basics, the extra clarifications help avoid errors.

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

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

The description clearly states it is a composite check for deciding whether to add an npm package, combining deps.dev (license + advisories + version history) and bundlephobia (bundle size, dependency count, ESM/tree-shake support). It provides specific example queries like 'is X safe / popular / small' and distinguishes from sibling tools (none overlap).

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also notes ecosystem limitation: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds no additional behavioral traits such as authentication needs or empty result behavior. Does not contradict annotations.

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

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

Description is one sentence plus an example, immediately stating the core purpose. No extraneous information.

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

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

For a simple single-parameter tool with rich annotations and an output schema, the description adequately covers the functionality, return type, and usage via example.

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

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

Schema coverage is 100% with a clear description of the query parameter. The description merely restates what the parameter does without adding new semantic 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 searches for cryptocurrencies by name or symbol and returns matching coins with IDs. It distinguishes from sibling tools like get_coin (singular) and get_market_data.

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

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

The description provides an example but no explicit guidance on when to use this tool versus alternatives like get_coin or other search tools. No exclusions or context for when not to use.

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

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

Annotations already provide safety hints, but the description adds rich behavioral details: returns top-N passages with offsets, uses BGE-base-en embeddings, 500-char windows, 200K char cap with truncation flag. It significantly extends what annotations convey 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 a single, well-structured paragraph of four sentences. It starts with core purpose, then usage context, then technical details. Every sentence contributes meaningfully 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?

The description covers purpose, usage, technical internals, and pairing with another tool. However, it does not specify the exact output format (e.g., structure of passages), which would be helpful. Given that there is no output schema, a bit more detail on return format would improve completeness.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving explicit char limit for 'text' and example queries for 'query', enhancing understanding beyond the schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record', specifying the verb and resource. It differentiates from siblings by noting it is used when the record is too large for the prompt and pairs with ask_pipeworx_grounded, making its purpose distinct.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It does not state explicit when-not-to-use scenarios, but provides sufficient context for appropriate use.

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

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

Beyond annotations, the description discloses that anonymous/BYO cannot persist, SMS has a 10/day cap, webhook auto-disables after 10 failures, and returns subscription id. No contradiction with annotations.

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

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

The description is well-organized with front-loaded key info, but is somewhat lengthy due to detailed examples. However, complexity justifies 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 3 parameters (2 required), no output schema, the description covers purpose, parameter meanings, behavioral constraints, and side effects comprehensively. An agent can 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?

The description adds extensive meaning beyond the schema: explains type enum values with examples, details param structures for each type, and describes delivery channels with constraints. Schema coverage is 100%, but description enriches significantly.

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

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

The description clearly states the verb 'Create' and resource 'proactive monitoring subscription'. It lists supported event types and distinguishes from sibling tools like unsubscribe and list_subscriptions.

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

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

The description specifies when to use this tool (creating subscriptions), outlines requirements (Pipeworx OAuth), and gives examples for each type. It doesn't explicitly state when not to use, but the context is clear.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. The description adds valuable behavioral context: that it returns example questions with tool+argument shapes from the live catalog. 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 well-structured with an alias list followed by explanation, but it is somewhat verbose. Every sentence adds value, though some redundancy (e.g., 'onboarding entry point') could be trimmed.

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

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

Given no output schema, the description sufficiently explains return format (category-bucketed example questions with tool+argument shape). It also covers edge cases (no args vs topic) and provides context about the meta-tools.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema by listing valid topic values (finance, pharma, etc.) and explaining the effect of omitting vs specifying the parameter.

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

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

The description clearly states the tool's function: an onboarding entry point that returns category-bucketed example questions for understanding what Pipeworx can do. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying its role as a 'first' step.

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 when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do') and provides clear guidance on argument usage (no args for full spread, topic param to focus).

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds ownership enforcement and explains that the row is deactivated rather than deleted, making behavioral implications clear.

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 covering purpose, constraints, and outcome with no redundant information. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description fully explains what happens (deactivation) and related tool ('recent_alerts'). No gaps.

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

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

The schema already covers the single parameter 'id' with a clear description. The tool description adds no extra parameter information beyond what is in the schema, so baseline of 3 is appropriate.

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

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

The description clearly states the action (cancel), resource (subscription), and identifier (id). It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by specifying cancellation functionality.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains the effect (deactivation, not deletion) and that historical events remain accessible via 'recent_alerts'. This guides when and when not to use.

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

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

The description goes beyond annotations by defining the error semantics: "could_not_verify means the check did not happen... it is NOT evidence for or against the claim, and must not be shown as one." It also distinguishes "unsupported" and explains the fast-path vs grounded pipeline behavior. This adds substantial context beyond the readOnly/openWorld/idempotent annotations.

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

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

Though ~250 words, every sentence adds value: trigger phrases, routing logic, return payload, error distinction, and efficiency claim. It's front-loaded with the core purpose and structured with clear sections, making it comprehensive without waste.

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

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

Without an output schema, the description fully specifies the verdict enum, the inclusion of a pipeworx:// citation, reasoning, and the verification_error payload for could_not_verify. It also covers both claim categories and the fallthrough behavior, making it self-sufficient for an agent to invoke correctly.

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

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

The input schema already covers both parameters with rich descriptions (claim example, tolerance_pct range and override behavior), so the description needn't repeat them. The description does contextualize tolerance as "exact percent-delta math" for financial claims, but the schema already provides semantics. Baseline 3 applies for full schema coverage.

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

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

The description opens with concrete natural-language triggers ("Is it true that…" / "fact check" / "verify the claim that…") and states it performs "natural-language claim verification against authoritative sources," immediately distinguishing it from generic querying tools. It also explains the two routing paths (SEC EDGAR fast path vs grounded pipeline) and the verdict output, leaving no doubt about the tool's function.

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 says "Use whenever the agent needs to check whether something a user said is factually correct," giving a clear trigger condition. The description also clarifies that it replaces 4–6 sequential calls, implying it's the consolidated tool for claim verification, but it doesn't enumerate exclusions or explicitly compare against siblings like ask_pipeworx_grounded or deep_research.

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