Chainlist

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: default model details, cost implications of using Anthropic (BYO key), and the return structure (score, confidence, signals, raw_response). No contradictions.

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

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

The description is three sentences, front-loaded with the core action and output. Every sentence provides necessary information without redundancy.

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

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

For a tool with 4 parameters and no output schema, the description covers core functionality, use cases, and output format. It lacks explicit mention of idempotency or read-only nature, but annotations fill that gap. Minor omission: no mention of score range or signal types.

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

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

With 100% schema coverage, baseline is 3, but the description provides additional meaning: default model for 'models', explanation of '_apiKey' as BYO Anthropic key, and clarification that 'context' disambiguates entities. This exceeds schema info.

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 specifies the action ('probe one or more LLMs'), the target entity (business/brand/product/topic), and the output (visibility score 0-100 per model). It distinguishes from siblings by focusing on AI visibility scoring rather than general search or Q&A.

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 ('AI-marketing audits, pre-launch brand checks, competitive monitoring'). While it does not explicitly exclude alternatives or mention sibling distinctions, the context is sufficient for usage decisions.

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

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

Annotations already cover read-only, open-world, and idempotent behavior. The description adds valuable behavioral context: it routes to sub-tools, fills arguments, returns structured answers with stable citation URIs, works on every tier, and handles live news. No contradictions with annotations.

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

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

The description is long but every sentence earns its place: guidance, examples, alternatives, and operational details. It is front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured with clear transitions to step-up tools.

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

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

Given the tool's broad scope, the description is remarkably complete. It covers use cases, domain areas, example queries, routing behavior, return format (citation URIs), and when to escalate to siblings. No output schema exists, but the description fully compensates.

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

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

Input schema has 100% coverage: all six parameters are aliases for 'question' and the schema provides clear descriptions and examples. The description reinforces the natural-language usage with examples, but adds no new parameter-level 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 uses a specific verb ('ask') and resource ('Pipeworx') and clearly states the tool's scope: routing factual questions to 5,521 tools across 1,452 sources. It distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE', establishing when to use the tool. It also names concrete alternatives ('ask_pipeworx_grounded' for hallucination-resistant answers, 'deep_research' for fan-out) and provides 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?

Beyond annotations, the description discloses that candidate routing improvements may be active live, currently none are active, and it matches ask_pipeworx exactly. It also clarifies it falls back to nothing rather than being a wrapper, adding useful behavioral context beyond the read-only and idempotent hints.

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

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

The description is four sentences, front-loaded with the core purpose ('Beta version of ask_pipeworx: identical universal router'). Each sentence contributes essential context: current candidate status, usage instruction, and fallback clarification. No waste or redundancy.

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

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

The description covers purpose, current behavior, usage guidance, and relationship to the stable router. It mentions 'same response shape,' compensating for the lack of an output schema. It doesn't provide examples or detailed return structure, but for a router explicitly equivalent to ask_pipeworx, it's sufficiently complete.

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

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

The schema has 100% coverage for all 6 parameters, each described as an alias for 'question'. The tool description only references 'same arguments' without adding semantic detail. Since the schema fully documents the parameters, baseline 3 is appropriate.

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

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

Description clearly identifies it as a beta version of ask_pipeworx, a universal router covering 5,521 tools with identical arguments and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements, making the purpose specific and well-differentiated.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. It also clarifies the current state (no active candidate) and that it's a full working router. However, it does not explicitly say when not to use it (e.g., if stability is preferred), leaving a minor gap.

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 behavioral traits beyond annotations: returns refusal_reason on failure, evidence as verbatim quote, confidence, source, and costs an extra LLM call. It also notes using ONLY tool result content. Annotations only state readOnly, openWorld, idempotent; 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 longer than average but well-structured: purpose first, then process, return format, use cases, cost trade-off. Each sentence adds unique value, no repetition, front-loaded with primary purpose. Minor over-specificity of refusal reasons but earned.

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 lack of output schema, the description fully explains return values and refusal modes, usage context, and cost trade-off compared to ask_pipeworx. For an agent to decide and invoke correctly, this is complete given the schema and annotations.

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

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

Schema has 6 parameters, all aliases for question, with 100% description coverage. The tool description adds no parameter-specific details beyond what the schema already says ('question in natural language'). Baseline 3 applies because schema does the heavy lifting and no extra meaning is added.

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

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

The description states a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads' and explains the process of routing, fetching, and extracting answers with verbatim evidence. It distinguishes itself from sibling ask_pipeworx by noting the same routing but adding extraction and explicit refusal, making its purpose unique.

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

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

The description explicitly says when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups.' This clearly contrasts with alternative and aids selector decision.

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 annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds extensive behavioral details: fan-out logic with source examples, response shape (market, analysis, evidence), resolver contract (market_match_confidence, alternatives), parent event extraction, news fallback handling, safety short-circuits, wide spread warnings, and cancellation rule parsing. This far exceeds what annotations provide.

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

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

The description is comprehensive but overly verbose, spanning multiple paragraphs with detailed examples and edge cases. While well-structured with logical sections, a more concise version could retain key information while reducing token count. The front-loading of the purpose is good, but the length may hinder quick parsing by agents.

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 the lack of an output schema, the description thoroughly covers all return values, including market details, analysis fields, evidence structure, resolver contract, parent event info, news fields, and safety mechanisms. It addresses edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules, making the tool's behavior completely predictable.

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?

Even though schema description coverage is 100%, the description adds significant value. For the 'market' parameter, it explains accepted formats (slug, URL, question text). For 'depth', it defines 'quick' and 'thorough' with specific behaviors. For 'include_raw', it clarifies default behavior, response size implications, and when to toggle. This enrichment helps agents choose correct 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and the action (research via data pull). It provides concrete use cases ('should I bet on X', 'what does the data say about Y'), making it distinct from sibling tools like 'polymarket_edges' or 'deep_research'.

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

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

The description directly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context. However, it does not explicitly mention when not to use it or recommend alternatives, such as 'polymarket_edges' for edge-specific queries, which would 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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), fiscal year handling, result sorting by primary metric, and inclusion of citation URIs. This exceeds 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 packed with information but slightly dense. It is front-loaded with example queries and ends with key output details. Every sentence adds value, though readability could be improved with line breaks.

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

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

Given no output schema, the description explains returns: 'paired data + pipeworx:// citation URIs per entity' and sorting behavior. It covers complexity of comparing multiple entities across two types with specific data fields, making it complete for an agent.

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

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

Input schema covers 100% of parameters with descriptions. The description adds meaning by explaining what data each type pulls (e.g., 'latest 10-K revenue + net income' for company) and providing examples (tickers vs drug names). This adds value beyond schema.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from sequential lookups by explicitly saying 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description provides explicit usage guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and gives example phrasings. It covers when to use but does not explicitly state when not to use or provide alternatives, though 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses significant behavioral traits: no invented answers ('never invented'), explicit gaps[] for unanswered facets, contradictions[] scan, citation_uri only when actually resolvable, semantic excerpting, and performance expectations. It also clarifies the tool is NOT open-web search. 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 dense and lengthy, but every section earns its place given the tool's complexity. It is structured with logical progression: account requirements, core purpose, alternatives, depth semantics, return packet details, and performance. Slightly above minimum because of the density, but the length is justified.

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

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

With no output schema, the description fully specifies the return packet: verbatim evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[], hop field, and citation_uri semantics. It also covers error/recovery behavior and latency, making the tool's behavior fully comprehensible in context.

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

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

Schema coverage is 100%, giving a baseline of 3. The description adds value by explaining the meaning of depth levels in terms of hop behavior and gap recovery, and by noting that questions can be broad/multi-part since decomposition is the point. This enriches the schema's terse enum descriptions.

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

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

The description uses a specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources... in ONE call' and explains the internal mechanism of decomposition and parallel routing. It clearly distinguishes itself from siblings, explicitly naming ask_pipeworx for single lookups and for breaking/current-news topics.

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

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

Provides explicit when-to-use and when-not-to-use guidance: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and notes account requirements with the fallback 'use ask_pipeworx instead — it works on every tier'. Also explains depth-level choices and expected latency.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to restate safety. It adds valuable context: results include 'full input schemas (with curated examples)' and are 'ready to call directly, no second schema lookup needed.' No contradictions with annotations.

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

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

Description is front-loaded with purpose and each sentence adds value. Could be slightly more concise, but it is efficient and well-structured 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?

For a discovery tool with no output schema, the description explains the return format (top-N tools with schemas and examples) and usage context (call first). Fully covers what an agent needs to know.

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

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

Schema coverage is 100% with all parameters described, so baseline is 3. The description adds that 'query' accepts natural language and lists aliases, but this is already in the schema. Marginal additional 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 states 'Find tools by describing the data or task' and gives extensive examples of topics (SEC filings, FDA drugs, etc.). It distinguishes from sibling tools by positioning itself as the discovery tool to call first, not a specific data retrieval tool.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This guides both when to use and when not to (when you already know the 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses behavioral traits: the tool fans across multiple sources, returns specific fields, includes a soft-fail for patents, and a fallback for news. It also states that only 'company' type is supported, and names are not allowed. This adds significant value beyond the annotation hints.

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

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

The description is fairly long but front-loaded with example queries and structured into bullet points. Every sentence serves a purpose, explaining sources and return fields. It could be slightly shortened while retaining clarity, but overall it is well-organized and 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?

There is no output schema, so the description must explain return values. It does so comprehensively, listing CIK, company_name, recent_filings with URIs, fundamentals, patents, news, and LEI. It also covers the patents sunset and news fallback, providing the agent with sufficient understanding of what the tool 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?

With 100% schema coverage, the schema already documents both parameters. The description adds value by providing examples ('AAPL' or '0000320193') and reiterating that names are not supported, directing the agent to resolve_entity. This extra context helps the agent use the parameters correctly.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous example queries and details the scope, making the action and resource explicit. While it does not explicitly differentiate from sibling tools like compare_entities, the guidance to prefer this over chaining single-pack lookups provides a clear use case distinction.

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

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

The description gives clear context on when to use the tool: for holistic company profiles. It advises using resolve_entity first if only a name is available, and implies it is not for specific single filings. However, it does not explicitly state when not to use it (e.g., for non-US companies), which prevents a perfect score.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds specific behavioral context about https_only filtering, which is beyond what annotations convey. No contradictions.

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

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

The description is two sentences, front-loaded with the main purpose, and contains no redundant information. Every part contributes value.

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

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

Given low complexity, rich annotations, and existence of output schema, the description provides sufficient context. It does not explain return format, but output schema covers that.

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

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

Schema coverage is 50% (only https_only has description). The description explains https_only effect ('filters out ws:// + http:// only'), adding meaning. However, chain_id_or_short_name lacks explicit detail, though examples help. Partially compensates.

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: 'Return RPC endpoints for a chain.' It is specific and distinguishes from siblings like get_chain or list_chains by focusing on RPC endpoints.

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

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

The description gives a clear context for the https_only parameter, but does not explicitly state when to use this tool versus alternatives or provide exclusions. It implies usage for RPC needs but lacks direct comparison.

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 mark destructiveHint=true, and description adds context about clearing sensitive data. No contradiction, but description adds value beyond annotations.

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

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

Two sentences: first states purpose, second gives usage guidelines. No wasted words, front-loaded.

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

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

For a simple delete tool with one parameter and good annotations, the description is complete and sufficient.

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

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

Only one parameter 'key' with schema description 'Memory key to delete'. Schema coverage is 100%, so description adds little beyond schema.

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

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

The description clearly states the verb (delete) and resource (memory), and distinguishes from sibling tools 'remember' and 'recall' by pairing them.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also notes pairing with remember and recall.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so agent knows it's safe. Description adds that it fetches the page, extracts title/description/key links, and emits standard format. No contradictions. Adequate disclosure for a read-only generation tool.

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

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

Three sentences, front-loaded with action, followed by usage examples. Every sentence adds value, no fluff.

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

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

For a simple tool with 2 parameters and high schema coverage, the description covers purpose, output format, and use cases. Missing error handling or limitations but not critical for completeness given annotations.

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

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

Schema description coverage is 100%. The description adds an example for 'url' ('e.g. https://example.com or a specific landing page'), but otherwise repeats schema info. Baseline 3 is appropriate since little extra meaning is added.

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+resource: 'generate a production-ready llms.txt file for any URL.' Specifies format, use cases, and output. Distinguishes from siblings by listing specific applications (client indexing, own project, competitor audit).

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 three useful scenarios for when to use the tool. Does not mention when not to use or compare to alternatives, but the context is sufficiently clear for an agent to decide.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds that it fetches a single chain, which is consistent. No behavioral traits beyond annotations are missing.

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

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

Single sentence, no wasted words, front-loaded with purpose and parameter details. Highly concise.

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

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

For a simple fetch tool with 1 param and output schema, the description covers essential purpose. Missing note about not-found behavior, but overall adequate.

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

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

Schema coverage is 100%, but description adds value by explaining parameter can be number string or shortName, with concrete examples. Adds clarity beyond schema 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?

Clearly states verb 'Fetch', resource 'single chain', and identification method via chainId or shortName with examples. Distinguishes from sibling 'list_chains' and 'find_rpc'.

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?

Implied usage: use when you have a chain identifier and want a single chain. No explicit when-not or alternatives mentioned, but context with sibling tools provides implicit distinction.

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 minimal behavioral context beyond 'browse or filter', which is consistent but doesn't disclose additional traits.

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

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

The description is a single sentence that front-loads the purpose and contains no wasted words. It is maximally concise.

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

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

Given the low complexity, full annotation coverage, full schema coverage, and presence of an output schema, the description sufficiently informs an agent about the tool's purpose and safe 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 description coverage is 100%, and the description does not add meaning beyond what the schema already provides for the three parameters. 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 a specific verb ('Browse or filter') and a clear resource ('the EVM chain registry'), clearly distinguishing it from sibling tools like 'get_chain' which targets a single chain.

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

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

The description implies usage for browsing or filtering chains but provides no explicit guidance on when to prefer this tool over alternatives like 'get_chain' or other listing 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=true, destructiveHint=false, and idempotentHint=true. The description adds value by specifying the returned fields (id, type, params, created_at, last_fired_at, fire_count) and mentioning 'active subscriptions' with the include_inactive parameter, going 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 two sentences, front-loading the core purpose and return fields, followed by usage guidance. Every sentence adds value and is concise.

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

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

Given no output schema, the description adequately lists return fields. It covers purpose, usage, and parameter. It is complete for a simple list tool, though it omits details like pagination or error handling, which are minor 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, and the input schema already provides a description. The description does not add extra meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. The title 'List Subscriptions' reinforces this, and it distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool and what to do with the results.

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 rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token follow-up mechanism, and that it is free (doesn't count against quota). Annotations are all false, so there is no contradiction. However, it does not explicitly state that filing feedback creates a stored record, though the token mechanism implies persistence. This is a minor gap.

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 and front-loaded with the primary purpose. Each sentence adds actionable information: usage scenarios, scope limitations, message guidance, token follow-up, rate limit, and cost. It could be slightly more compact, but the density of useful content justifies its length.

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

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

Given no output schema, the description explains the return behavior via claim_token and the status-reading workflow. It covers all four parameters, the context object, type enum meaning, and operational constraints (rate limit, quota). It leaves no critical gaps for an agent to infer behavior.

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

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

The schema already provides 100% description coverage for all parameters. The description adds meaningful guidance for the message parameter: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also explains the claim_token usage in detail ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"}) to read whether it was fixed'), which goes beyond the schema description.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses an action verb with a specific resource (Pipeworx team) and explicitly enumerates feedback types ('bug', 'feature/data_gap', 'praise'), distinguishing it from siblings like ask_pipeworx or other 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?

The description provides explicit when-to-use criteria: 'Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well.' It also states a clear exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This gives the agent unambiguous decision rules.

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 safety (readOnlyHint, idempotentHint, destructiveHint=false). Description adds value by disclosing data provenance (CF analytics-engine), privacy (no PII), and caching (5min-1h). No contradictions.

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

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

The description is concise (~60 words), front-loaded with the core function, then use cases, then technical details. Every sentence adds value with no redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description fully covers purpose, usage, parameter behavior, data source, caching, and privacy. No gaps.

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

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

Schema coverage is 100% with a well-described enum parameter. The description reinforces window semantics but doesn't add new parameter-level information 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 trending tools, packs, and call volume over a window. It distinguishes from siblings like 'discover_tools' by focusing on recent activity rather than general 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?

Three explicit use cases are provided (hot sources, canonical choice, alignment). Window selection guidance is given ('shorter windows surface what's hot now; longer show steady-state'). No explicit 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 read-only and idempotent, but the description adds important behavioral details: fill check against CLOB depth, semantic anchor for cross-event pairs, partition filter for placeholder slugs, and conditions when signals should not be traded. 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 fairly long but well-organized: first the general purpose, then three modes, then sub-details. It is front-loaded with the core functionality. Some redundancy (e.g., repeated mention of partition_check) but overall efficient 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?

Despite lacking an output schema, the description thoroughly explains the response structure (opportunities array with gap_pp, suggested_trade, etc.) and covers edge cases like fill check, similarity filter, and placeholder handling. Very complete for a complex tool.

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

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

Both parameters (event, topic) are described in the schema with full coverage, but the description adds significant context: event slug format, topic as seed question, semantic anchor (≥0.30 Jaccard similarity), and partition filter logic. This goes well beyond the schema definitions.

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

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

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

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

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

Explicit guidance on when to use each mode: 'Call with NO args for a trending_scan... pass event for... partition_check, or topic for cross-event scan.' It explains what to avoid (e.g., 'do not trade it' when realizable_edge <= 0) and references polymarket_fill_risk for custom sizing.

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 confirm read-only, open-world, idempotent, and non-destructive behavior. The description adds extensive context: caching policy ('Cached 1h at the KV level'), model families (crypto_price, news_momentum, etc.), diagnostic counters (funnel, category_counts), and exclusion of Fed bets. No contradictions with annotations.

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

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

The description is comprehensive but verbose, spanning multiple detailed paragraphs. It front-loads the purpose but could be more concise without losing essential information. Every sentence adds value, but overall length pushes it toward 'adequate' rather than 'concise'.

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

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

Despite no output schema, the description thoroughly explains the return structure (by_segment, diagnostics) and the reasoning behind each model family. It covers edge cases (Fed bets, empty segments), making it complete for an agent to understand behavior and interpret results.

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

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

Schema coverage is 100% with detailed parameter descriptions, so baseline is 3. The tool description adds value by explaining how parameters like min_liquidity, max_spread_pp, and min_partition_leg_kelly act as tradeable-edge filters, providing usage context 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 opens with a specific verb ('Scan top Polymarket markets') and resource ('opportunities where Pipeworx data disagrees with market price'), clearly stating the tool's purpose. It further contextualizes as 'what should I bet on today' and distinguishes it from sibling tools like polymarket_arbitrage by focusing on Pipeworx disagreement rather than pure arbitrage.

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

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

The description states it's built for daily opportunity discovery and explains tradeable-edge knobs (min_liquidity, max_spread_pp) and Fed bet exclusion. However, it does not explicitly contrast with similar siblings (e.g., polymarket_arbitrage, polymarket_edge_tracker) or specify when NOT to use it, leaving some ambiguity.

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

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

The description discloses extensive behavioral traits beyond annotations: data source (daily snapshots), response structure (tracked, expired, snapshot_dates), meaning of trend fields, and that snapshots are written on cache-miss causing gaps. Annotations already declare readOnlyHint=true and idempotentHint=true, and the description reinforces this 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 well-structured with a clear purpose sentence, usage context, and detailed response format. It is fairly long but each sentence adds value. Minor redundancy (e.g., 'default 14' mentioned twice) prevents a perfect score.

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

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

The description compensates for the lack of output schema by detailing the response fields (tracked, expired, snapshot_dates) and their meaning. It also covers limitations. While thorough, it lacks explicit data types or a concrete example, so a perfect score is not warranted.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minor context (e.g., default values and allowed values) but largely repeats the schema. The slight inconsistency in 'max 30' vs schema's 'clamp 2-30' is a minor detraction. Overall, baseline 3 is appropriate as description adds little beyond schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question about edge duration and trend, and distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence rather than current edges.

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

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

The description provides explicit guidance on when to use the tool, e.g., 'a fresh wide edge and a 3-week-old wide edge are different trades' and explains limitations like history depth bounded by 60-day TTL and decay from daily closes. It implicitly suggests when not to use (for current edges use polymarket_edges), but does not name alternatives explicitly.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds detailed behavioral context: it walks the ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, per-leg fill detail, thin_legs, and forced_directional_risk. This goes well 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 clear headers (SINGLE-MARKET and BASKET) and bullet-like return field listings. It is somewhat lengthy but every sentence adds valuable information. Could be slightly more concise.

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

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

Despite no output schema, the description thoroughly covers both modes, listing all return fields and edge cases (thin_legs, forced_directional_risk). It also warns about the dominant loss mode (partial arb fills becoming directional). Complete for an agent to understand tool behavior.

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

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

Schema description coverage is 100%, baseline 3. The description adds significant meaning: explains how size_usd is interpreted differently per mode (spend vs target proceeds vs settlement notional), provides default values and clamping, and clarifies the auto-detection of side for baskets. This exceeds baseline.

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

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

The description clearly states it performs a realizable-vs-theoretical edge check against live order-book depth, distinguishing between single-market and basket modes. It implicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by directing usage before those 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?

Explicitly tells when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about when not to rely on theoretical overround on thin books and explains risks of partial basket fills.

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 goes far beyond by detailing two modes, response structure (leg-by-leg prices, matched spread[], top_spreads_pp), safety fields with specific cases (compatibility_warning with two subcases), temporal_alignment with month alignment, and skipped type/subtype counters. No contradiction with annotations. Rich behavioral context for agent decision-making.

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 ~300 words, well-structured with clear sections (purpose, modes, response, safety fields, temporal, skipped counters, caution). Every sentence adds value; no fluff. Could be slightly more concise (e.g., the caution sentence is long), but front-loads key information and organizes details logically. Overall efficient 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?

No output schema, so description carries full burden. It fully describes response including raw probabilities, matched spread, top_spreads_pp, compatibility_warning with two cases, temporal_alignment with aligned boolean, skipped type/subtype counters. Also explains pitfalls (shapes not equivalent, temporal mismatch). Given the tool's complexity (two venues, multiple modes, safety checks), the description is comprehensive and leaves no critical gap.

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

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

Schema description coverage is 100% with each parameter having a description. The description adds value by explaining the interaction between parameters: topic auto-fetches matching events on both venues, while explicit tickers override. It also notes that pre-mapped topics often return compatibility_warning. Provides examples in schema. Enough extra semantic context to exceed baseline 3.

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

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

Description states it computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question' with two modes (topic shortcuts and explicit tickers). The verb 'spread' and resource 'cross-venue' are specific. Among siblings it clearly differs from polymarket_arbitrage (intra-venue) and polymarket_edges (edge detection). No 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?

Explicitly describes when to use each mode (topic for pre-mapped shortcuts, explicit for custom pairings) and warns that 'real cross-venue spreads are rarer than the macro-shortcut list suggests' and that pre-mapped ≠ tradeable. Does not explicitly name alternatives or say when not to use this tool versus siblings, but context is clear from the description and sibling names. Could be improved by directly contrasting with polymarket_arbitrage.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scope (per-identifier) and dual behavior (single key vs. list all). No contradictions.

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

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

Three focused sentences. Front-loaded with core function. No wasted words. Clear and efficient.

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

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

Complete for a simple retrieval tool with one optional param and no output schema. Explains purpose, usage, scope, and sibling relationships.

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% with one optional parameter. Description explains 'key' meaning and omission behavior, matching schema description and adding usage context.

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

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

Clearly states it retrieves or lists saved values with specific verb ('retrieve', 'list') and resource ('value previously saved via remember'). Distinguishes from siblings 'remember' and 'forget' via explicit 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?

Explicitly says when to use: to look up stored context without re-deriving. Mentions pairing with remember/forget. No explicit when-not guidance, but context is clear.

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

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

Annotations already declare safe, idempotent, read-only. Description adds critical behavior: mark_read changes state for subsequent calls, and polling is fine. 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?

Succinct: 4 sentences covering purpose, returned fields, filtering, mark_read, and alternative endpoint. Every sentence adds value, no redundancy.

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

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

No output schema, but description lists returned fields (source, citation_uri, raw payload). Covers usage, parameters, and behavioral aspects. Could mention limit behavior more explicitly, but sufficient for agent selection.

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 all 5 parameters with descriptions. Description adds examples (e.g., 'sec_8k'), clarifies mark_read behavior, and explains since as ISO timestamp, enhancing understanding beyond schema.

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

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

Clearly states 'Pull fired events from your subscription feed' with specific verb and resource. Distinguishes from siblings like subscribe, list_subscriptions, and the alternative endpoint for scripts.

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 filtering guidance (type, since) and the mark_read effect. Mentions alternative GET endpoint for scripts/dashboards, but lacks explicit when-not-to-use vs 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 declare read-only, idempotent, non-destructive. The description adds extensive behavioral context: parallel fan-out to multiple sources, fallback mechanisms, soft-fail for USPTO, and return structure with citation URIs. No contradiction.

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

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

The description is well-structured: starts with natural language examples, then core function, then source details, parameter explanation, return format, and alternative tool. Every sentence is informative without being verbose.

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

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

Despite no output schema, the description covers return structure (changes[], total_changes, citation URIs), all parameters, edge cases (fallback, soft-fail), and distinguishes from related tools. Complete for a complex multi-source tool.

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

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

Schema coverage is 100%, and the description adds meaning: explains 'since' accepts ISO dates or relative shorthand (e.g., '7d', '3m'), shows examples, and clarifies that 'value' can be ticker or CIK. The 'type' parameter is limited to 'company'.

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

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

The description clearly states the tool provides a change feed for a company in a specified time window, with explicit examples. It distinguishes itself from the sibling 'entity_profile' by directing users to that tool 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?

Provides explicit when-to-use context via example queries and states when to use an alternative ('entity_profile'). Also explains fallback behavior (GDELT to GNews) and parameter syntax.

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 idempotentHint=true and other hints, but the description adds valuable behavioral details: scoping by user identifier, persistence differences (24-hour vs permanent), and pairing with recall/forget. 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 two sentences plus a short concluding sentence. Every sentence adds value with zero waste. Front-loaded with the core action.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers storage behavior, scoping, persistence, and partner tools. No gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3. The description mentions key-value pair and gives examples in the description, but does not add significant meaning beyond the schema's property descriptions.

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

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

The description starts with a clear verb and resource: 'Save data the agent will need to reuse later.' It explicitly distinguishes from sibling tools by mentioning 'Pair with recall to retrieve later, forget to delete.' This provides strong differentiation.

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 concrete use cases ('discover something worth carrying forward' with examples like 'resolved ticker, target address') and explicitly references sibling tools for retrieval/deletion. It lacks explicit 'when not to use' but provides sufficient context.

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

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

Beyond the readOnly/idempotent annotations, the description discloses rich behavioral traits: each call cascades through multiple lookup endpoints internally, auto-disambiguates input, and returns specific citation URIs (pipeworx://edgar/company/{cik}, pipeworx://rxnorm/concept/{rxcui}). This adds significant context about how the tool behaves and what it returns.

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 slightly long but well-organized, leading with user-facing examples, followed by a clear 'Use FIRST' directive, then structured 'SUPPORTED TYPES' details. Each sentence provides value, but the internal-cascade and manual-lookup replacement note could be optional. Still, it is front-loaded and easy to scan.

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 explains return values for both entity types, including field names, source systems, and citation formats. It also covers input variations and the multi-step lookup behavior, making the tool self-contained for an agent to invoke correctly. The efficiency note (replaces 2-3 manual lookups) adds practical context.

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

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

Schema already describes parameters at 100% coverage, but the description adds substantial meaning: it details what each enum value returns (e.g., company includes ticker, 10-digit CIK, company_name from SEC EDGAR), specifies accepted input formats for value (ticker, CIK, name; brand or generic), and mentions auto-disambiguation. This exceeds the schema's descriptions.

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

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

Description clearly states the tool resolves names to canonical identifiers, with explicit examples ('What's the ticker for…'), supported types (company, drug), and specific return values (ticker, CIK, RxCUI). It distinguishes from siblings by noting 'other tools require as input' and instructing 'Use FIRST' when a name but no ID is needed.

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 timing direction: 'Use FIRST whenever you have a name but need an ID.' It also implies alternatives by noting other tools require these identifiers, but it does not explicitly name when-not-to-use or list alternative tool names. Clear context without exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. No contradictions with annotations.

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

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

The description is three sentences: purpose, mechanism, and use-case with return details. It is front-loaded with the core action, efficient with 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?

With no output schema, the description adequately describes the return structure (ranked list with score, confidence, signal density). It covers the tool's purpose, parameters, behavior, and usage context, making it self-contained for an agent to decide correctly.

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

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

Schema description coverage is 100%, but the description adds crucial semantics: 'First entry treated as the 'subject' for narrative; rest are competitors', and explains context disambiguates common names. This adds value beyond the schema alone.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probes each with ai_visibility_check, ranks by score, and identifies most/least recognized. It provides a use-case example ('does Claude know about us as well as our competitors?'), effectively distinguishing it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description explicitly states the tool is useful for competitive AI-marketing audits and gives a concrete scenario. It implies single-entity checks should use ai_visibility_check but does not list alternative tools or explicit when-not-to-use conditions. The guidance is clear but not exhaustive.

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 discloses that the tool fans out across two external services, that bundlephobia's first measurement can take 5-30s, and that partial failures degrade gracefully with a sources_failed list. This adds context beyond the annotations (readOnly, idempotent) about potential latency and error handling.

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

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

The description is dense but well-organized: purpose first, then usage, then output details, then edge cases. Every sentence adds value, though it could be slightly more concise. Still, 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?

Given no output schema, the description thoroughly explains return structure (summary block, per-advisory detail, links, recent versions) and handles partial failures. The tool complexity is high (composite, external services), and the description covers all necessary context.

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

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

Schema coverage is 100% (both parameters described). The description adds context that package is an npm package name (scoped accepted) and that version defaults to latest, which is already in schema. However, it also explains how parameters are used in the composite check, slightly improving understanding.

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

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

The description clearly states the tool's composite nature: checking npm package safety and size via deps.dev and bundlephobia in one call. It distinguishes itself from siblings by specifying the npm ecosystem and the exact data sources, 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?

Explicit usage guidance: 'Use whenever an agent asks ...' and explains the scope (NPM only, other ecosystems via deps.dev). Also notes partial failures and timing for bundlephobia first measurement, helping the agent decide when to call this tool vs. alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: embedding model (BGE-base-en), window size (500-char overlapping), character cap (200K chars with truncation and flag), and return format (passages with offsets and similarity scores). No contradictions.

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

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

The description is a single dense paragraph that front-loads the core purpose, then efficiently covers usage, technical details, and limitations. Every sentence serves a purpose; there is no redundancy or fluff. The structure is logical and easy to parse.

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 explains the return format (passages with offsets and similarity scores) and operational details (embedding model, windowing, char cap, truncation). It also contextualizes the tool within the sibling toolset. For a tool of this complexity, the description is remarkably 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 baseline is 3. The description restates parameter purposes but does not add significant new semantic detail beyond the schema descriptions. For example, 'text' is described as 'The document text to search inside (max ~200K chars)' which matches the schema. The description does not introduce new parameter constraints or enrich 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 verb+resource: 'Semantic search INSIDE a fetched record.' It distinguishes from siblings by explicitly mentioning ask_pipeworx_grounded as a complement, and specifies that it returns top-N passages with offsets, 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 explicitly states when to use: 'Use when the record is too big to cram into the prompt — search_within saves context...' It also provides usage guidance by pairing with ask_pipeworx_grounded and explains the benefit of offsets for verification. No exclusion criteria are needed, and the 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?

Description elaborates beyond annotations: it confirms creation (non-readonly), requires OAuth account, details delivery channel limits (10/day SMS, webhook auto-disable after 10 failures), and notes that webhook signing secret is returned only once. No contradictions with annotations.

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

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

Description is relatively long but well-organized with clear sections. Every sentence provides useful information; however, slight redundancy (e.g., SMS cap mentioned twice) 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, description states return value (subscription id). It covers all parameters, prerequisites (OAuth), and delivery nuances. Complete for a subscription creation tool.

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

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

Schema coverage is 100%, but description adds extensive value: examples for type-specific params, detailed delivery constraints (verified phone, SMS cap, webhook HMAC signing). This significantly aids parameter selection 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This exactly matches the tool name and action. It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Description provides explicit context for when to use (proactive monitoring, requires OAuth account) and includes examples for each subscription type. It does not explicitly exclude alternatives, but 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?

Annotations already indicate safe read-only behavior; the description adds context about being the first step and detailing the output structure, which 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 front-loaded with the key purpose, and every sentence adds value; it could be slightly more concise but is well-structured and not overly verbose.

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

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

The description fully explains the tool's purpose, when to use it, and what the output contains (category-bucketed example questions with tool+argument shape), which is sufficient given the simple input schema and no output schema.

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

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

Schema coverage is 100% and the description restates the parameter's purpose and examples; the description adds 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 clearly states it is the onboarding entry point for a new agent, returns category-bucketed example questions with tool+argument shape, and distinguishes from siblings by recommending it be used first.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do' and explains both no-argument and topic-focused calls, but doesn't explicitly mention when not to use it.

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

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

Annotations indicate non-destructive mutation; description confirms row is deactivated (not deleted) and history preserved. Adds meaningful behavioral context beyond structured fields.

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

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

Two efficient sentences, no redundancy, front-loaded with the core action and key constraints.

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 parameter fully described; outcome clearly stated; no output schema needed. Complete for this 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 value by clarifying that id comes from 'subscribe' tool, aiding agent in proper invocation.

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

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

Clearly states 'Cancel a subscription by id' – a specific verb and resource. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement (only own subscriptions) and behavioral effect (deactivation not deletion). No direct when-not-to-use, but ownership constraint covers many cases.

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

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

Annotations already declare readOnly, openWorld, idempotent, not destructive. Description adds significant behavioral detail: use of structured SEC EDGAR + XBRL for financial claims, grounded pipeline for others, exact percent-delta math, output includes verdict types, actual value with citation, and reasoning. No contradiction with annotations.

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

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

Description is informative and front-loaded with key phrases in quotes. Every sentence adds value, though slightly verbose for the amount of info. Could be tightened but still effective.

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

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

Despite no output schema, description fully explains return values (verdict types, actual value with citation, reasoning). Covers the dual processing logic and replaces multiple steps. Complete for an AI agent to understand input, behavior, and output.

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

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

Schema description coverage is 100%, so schema already documents parameters. Description adds minor context (tolerance_pct overrides implied tolerance, example values) but does not significantly improve parameter understanding beyond schema.

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

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

Description clearly states tool does natural-language claim verification, with specific examples and distinguishing between company-financial claims and other factual claims. It includes trigger phrases and explains the dual pipeline, making the purpose unmistakable.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Provides examples of claim types. Lacks explicit when-not-to-use or comparisons to siblings, but 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.