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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: it routes across 5,724 tools, fills arguments automatically, returns a structured answer with stable citation URIs, and is described as one fast call that works on every tier. It stops short of explaining failure modes or the exact citation structure, but this is not a contradiction and goes beyond the annotations.

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

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

The description is longer than minimal but well-structured and front-loaded with the most important guidance: prefer this over web search. It contains some repetition around when to use it, yet the lists of domains, trigger phrases, examples, and alternatives all earn their place.

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

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

Given the tool has only one required parameter and no output schema, the description provides sufficient context: what to pass, when to use it, what to expect back, and which siblings to choose instead. The omission of detailed response formatting or error behavior is not material for correctly selecting and invoking the tool.

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

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

The schema already documents all parameters with 100% coverage, including aliases. The description adds value through domain guidance and example questions like 'current US unemployment rate' and 'Apple's latest 10-K', which helps the agent formulate the natural-language question parameter appropriately.

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

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

The description states a specific behavior: route natural-language questions to relevant verified sources and return structured answers with pipeworx:// citations. It also clearly distinguishes itself from ask_pipeworx_grounded and deep_research, so an agent can tell them apart without opening schemas.

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

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

The description explicitly says to prefer this tool over web search, lists trigger phrasing such as 'what is', 'look up', 'find', and 'get the latest', and gives concrete examples. It also names when to step up to alternatives: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions.

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

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

Beyond the annotations, it discloses that candidate routing improvements may be active live, that none is currently active, that the last was retired on outcome evidence, and that it falls back to nothing—it is a fully functioning router, not a degraded proxy. This is strong behavioral context.

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

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

The description is appropriately sized and front-loaded: the first sentence establishes identity and relationship to ask_pipeworx, and later sentences clarify status and usage. There is minor redundancy between 'identical' and 'currently matches ask_pipeworx exactly,' but it is not wasteful enough to penalize heavily.

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 tells an agent everything essential to invoke it correctly: same arguments as ask_pipeworx, same response shape, experimental status, and current parity with the stable router. With no output schema, the mention of the same response shape compensates well; only a brief note about the grounded alternative would round it out.

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

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

The input schema already documents all parameters at 100% coverage, including the required 'question' and all aliases. The description's mention of 'same arguments' adds no new parameter-level meaning, so the baseline 3 is appropriate.

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

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

The description is specific: it is the beta version of ask_pipeworx, a universal router exposing the same 5,724 tools, arguments, and response shape as the stable version. It clearly distinguishes itself as the experimental edge, which separates it from its sibling tools like ask_pipeworx and ask_pipeworx_grounded.

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

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

It gives explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. It does not explicitly say when not to use it or when to prefer ask_pipeworx_grounded, but the main selection criterion—preference for the newest routing—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 provide readOnly/openWorld/idempotent safety hints, and the description substantially adds behavioral detail: it returns explicit refusal structures for cases like not_in_source, no_tool_match, and data_truncated, and discloses the extra LLM call cost. It also explains success/failure output contracts, which is critical since there is no output schema.

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?

Dense but every sentence earns its place: purpose, mechanism, output contract, refusal contract, use cases, and cost comparison are all packed in without fluff. Front-loaded with the core value proposition and clearly structured around behavior and usage.

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 high-stakes read tool with no output schema. The description fully specifies return values, refusal reasons, when to use, when not to use, the alternative tool, and the latency/cost tradeoff. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add much beyond the schema: it confirms the input is a natural-language question but the schema already documents 'question' and all five aliases. No additional parameter-level semantics are needed or provided.

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

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

States a specific, distinctive purpose: a hallucination-resistant, grounded answer mode for high-stakes reads. It directly differentiates itself from sibling ask_pipeworx by explaining the extraction-only-from-tool-result behavior, and the name/title reinforce the 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?

Explicitly says when to use: whenever answers will be quoted, cited, or acted on and the agent must not invent facts, with concrete examples like financial verdicts and legal claims. It also names the alternative ask_pipeworx and the tradeoff (one extra LLM call), explicitly preferring the sibling for casual lookups.

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 the parallel decomposition into facets routed to 5,724 tools, the findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), explicit gaps[] behavior, contradictions[], hop field, citation_uri resolvability, semantic excerpting of long records, and latency expectations (15-60s, up to ~90s). No contradiction with annotations.

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

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

The description is long but every sentence earns its place: prerequisites, use cases, exclusions, internal behavior, output format, citation guarantees, and latency. It is front-loaded with the account requirement and fallback, which is the most decision-relevant fact. The density slightly reduces scannability, but not to the point of waste.

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

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

With no output schema, the description fully covers return semantics (findings packet, gaps, contradictions, hop, citation_uri), behavioral edge cases (news topics yield empty gaps), account gating, and latency. An agent has everything needed to select, invoke, and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value beyond the schema: it explains the meaning of 'question' ('Broad/multi-part is fine — decomposition is the point') and elaborates each depth enum value with facet counts, recovery hops, contradiction scans, and the paid-plan requirement for 'thorough'. This substantially exceeds schema documentation.

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

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

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources'. It explicitly contrasts with open-web search and names sibling ask_pipeworx, so an agent can distinguish this from alternatives without opening schemas.

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

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

Gives explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('For a single lookup use ask_pipeworx'; 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'), and even a prerequisite fallback ('If you are not signed in, use ask_pipeworx instead'). No ambiguity remains.

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?

Beyond the readOnly/idempotent annotations, the description discloses extensive behavioral nuance: matching is keyword/token-overlap based and never verified against a shared resolution source, Kalshi fees are not modeled so spreads are gross, temporal alignment can be unknown rather than confirmed, and unclassified legs are never paired. This is far more transparent than the annotations alone.

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 it is densely structured with clear labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and each addition maps to a real behavioral or safety nuance. A little trimming of repeated phrases like 'in EITHER mode' would improve it, but for a tool with this many edge cases and no output schema, the length is largely 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 carries the full burden of explaining return values, and it does so thoroughly: leg prices, top_spreads_pp, compatibility codes, per-entry flags, skipped counters, temporal alignment, and fee disclosure. It also covers failure and partial-match cases, so an agent has enough context to invoke the tool and interpret results correctly.

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

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

Schema covers all three parameters with descriptions and examples, so the baseline is 3. The tool description adds meaningful semantics beyond the schema by explaining that the two explicit parameters override the topic-mapped side and that both modes run the identical token-overlap matcher, which clarifies how parameters interact at runtime.

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 first line states exactly what the tool does: computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It also distinguishes itself from sibling tools by focusing on cross-venue comparison rather than same-venue arbitrage or edge tracking, and the two-mode explanation makes the functional scope explicit.

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

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

The description gives clear situational guidance: use `topic` for 10 pre-mapped shortcuts or explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also warns that pre-mapped topics frequently return compatibility warnings and are not automatically tradeable, which helps the agent set expectations, though it does not explicitly name alternative sibling tools to prefer in specific 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, 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?

Even though annotations already mark it read-only and idempotent, the description adds substantial behavior: graceful enrichment degradation, cascading across lookup endpoints, explicit `unresolved` reporting, ambiguity via `figi_candidates`, source labelling, and ISIN-to-LEI mapping. This is far beyond what the 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 main content is front-loaded with user phrasing and the core sentence is clear. The company branch is a long, run-on sequence of nested clauses that could be restructured, but nearly every detail earns its place given the tool's multi-source 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?

With no output schema, the description still explains return behavior for both types: RxCUI/ingredient/brand/citation for drugs, and CIK/ticker/LEI/FIGI plus `unresolved` and `figi_candidates` for companies. It also covers non-US issuers, non-equity instruments, and degraded enrichment, so an agent has enough guidance to select and call it.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema, especially for `value`: it warns to pass the issuer exactly as printed, never the full noun phrase, and explains that trailing security-class words fail in FIGI lookup. It also elaborates the `type` enum with source systems and identifier types.

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 multiple natural-language examples and then gives a crisp statement: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It clearly conveys the resource (entities/identifiers), the action (resolve/look up), and how it differs from downstream tools that consume IDs.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID' and documents the two supported types and accepted input forms. It does not name sibling tools or give explicit when-not-to-use exclusions, but the intended placement in a lookup workflow 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 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 read-only/idempotent, so the description adds valuable context beyond those: the could_not_verify vs. unsupported distinction, the verification_error object, and the automatic fallback pipeline. This meaningfully enriches the agent's understanding of edge cases.

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 front-loaded with usage patterns, followed by how the routing works and warnings. Some text could be sectioned for easier scanning, but every sentence carries relevant information and there is 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?

With no output schema, the description must explain the return shape, and it does: verdict list, grounded/structured value with citation, reasoning, and the error semantics for could_not_verify vs. unsupported. It also mentions the efficiency benefit (replacing 4–6 sequential calls), making it complete for a verification tool.

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

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

The input schema already has detailed descriptions for both parameters (100% coverage). The description adds extra semantics for tolerance_pct (overriding implied wording, default cap at 5) and provides realistic examples for claim, enhancing the schema rather than repeating it.

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 defines a specific verb ('validate') and resource ('natural-language claims') with explicit trigger phrases and output verdicts. It clearly distinguishes a fact-checking tool from generic lookup tools, and the example intents ("fact check", "verify the claim that…") make 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?

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the routing for company-financial vs. any other factual claim. It lacks formal when-not guidance or named alternative tools, but the context is unambiguous and operational.

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