Numbers

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

Discloses default model is free, Anthropic requires separate API key with pass-through, and return format (per-model and combined view). Annotations already indicate read-only, idempotent, non-destructive; description adds cost implications and data flow details 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?

Three sentences covering purpose, parameter usage, and use cases. No extraneous information. Front-loaded with the core function. Each sentence adds value.

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

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

With 4 parameters and no output schema, the description fully explains all parameters and the return structure (per-model score, confidence, signals, raw_response + combined view). It also addresses the cost model for Anthropic. 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?

All 4 parameters have descriptions in the schema (100% coverage). The tool description adds meaningful context: default model, free usage, API key pass-through, and disambiguation purpose for 'context'. This goes beyond the 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?

Clearly states the action (probe LLMs), resource (business/brand/product/topic), and output (visibility score 0-100). Distinguishes from sibling tools by focusing on visibility scoring rather than general Q&A or scanning. Includes specific use cases (AI-marketing audits, pre-launch checks, competitive monitoring).

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

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

Provides context on when to use (brand audits, competitive monitoring) and how to set parameters (default model, BYO key for Anthropic, context disambiguation). Does not explicitly contrast with sibling tools like 'ask_pipeworx' or 'scan_competitor_ai_presence', but the description itself gives sufficient guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a strong safety profile. The description adds valuable behavioral context: it routes to 5,563 tools, returns structured data with pipeworx:// citation URIs, is one fast call, and works on every tier. No contradictions with annotations.

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

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

The description is dense but well-structured. It front-loads the critical preference directive, then explains the tool's mechanism, followed by usage guidance and alternatives. Every sentence adds value, though it could be slightly more concise without losing clarity.

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

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

Given the tool's complexity (5,563 tools, 1,462 sources), the description is thorough. It covers purpose, usage, alternatives, and output format (structured answer with citation URIs). It lacks details on rate limits or error handling, but the annotations and examples compensate. No output schema exists, but the description sufficiently describes the return value.

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

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

Schema description coverage is 100% with all 6 parameters documented as aliases for 'question'. The description adds meaning by explaining the parameter is a natural language question and provides examples of valid queries, which goes beyond the schema's bare alias 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?

The description clearly states the tool's purpose: it routes a question to the appropriate tool among thousands of verified sources, fills arguments, and returns structured answers with citation URIs. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by specifying when to use each.

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

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

Explicit guidance: 'PREFER OVER WEB SEARCH' and 'START HERE for most questions'. It provides specific conditions for using alternatives (grounded for hallucination-resistant single answer, deep_research for broad/multi-part questions) and gives numerous example queries to illustrate appropriate use cases.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant context: the experimental nature, candidate routing improvements, current status (no active candidate so matches stable), and that it is a full working router with same response shape. 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 well-structured sentences: first introduces the beta identity, second explains current equivalence to stable, third gives usage guidance. No wasted words, front-loaded with purpose.

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

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

For a complex beta router without output schema, the description covers purpose, behavior, usage context, and relationship to stable. It references same response shape as ask_pipeworx. Minor gap: no explicit mention of response format details, but this is mitigated by the reference to identical shape.

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

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

Schema description coverage is 100% (all 6 parameters described). The description does not add parameter details beyond 'natural language question', which is already in the schema. Baseline 3 is appropriate since schema covers parameter semantics.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router answering questions via 5,563 tools. It distinguishes from siblings by explicitly noting it is identical but with experimental routing improvements, and currently matches the stable version.

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

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

The description explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router, providing clear guidance on when to choose this tool versus the stable alternative.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false, so the agent knows it's a safe, idempotent read. The description goes well beyond annotations by detailing the refusal mechanism, the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}), and the five specific refusal reasons. This is exceptionally transparent for a high-stakes 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?

The description is exceptionally concise with zero wasted words. Each sentence serves a distinct purpose: defining the mode, explaining routing, stating the extraction behavior, detailing the return shape, and giving usage guidance. It front-loads the critical concept ('hallucination-resistant') and then efficiently structures supporting detail. This is a model of conciseness.

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

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

Given the tool's complexity (6 aliases for one parameter, no output schema, a critical refusal mechanism), the description is remarkably complete. It explains the return shape in detail, covers edge cases (refusals), and provides both usage contexts and costs. The only minor gap is that it does not explicitly mention pagination or truncation behavior for large results, but 'data_truncated' refusal reason implies this is handled. Still, it achieves high completeness for a single-parameter 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 is well-documented with 100% coverage, showing 6 aliases for the 'question' parameter. The description adds value beyond the schema by explaining what to ask for ('Your question in natural language') and how it will be processed. Baseline of 3 is elevated to 4 because the description contextualizes how the question is used (routed and extracted from) without being redundant.

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

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

The description clearly states the tool's purpose: providing a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only the tool result. It distinguishes itself from the sibling 'ask_pipeworx' by specifying the exact added behavior (extraction with evidence). The concrete use cases (financial verdicts, legal claims, medical lookups, public statements) further clarify its specific role.

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

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

The description explicitly says 'Use whenever an answer will be quoted, cited, or acted on', which is a clear when-to-use directive. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups', and explains the trade-off ('Costs one extra LLM call'). This perfectly guides an agent to select between this and its sibling.

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?

Extremely detailed beyond annotations: describes low-confidence resolution short-circuit, closed/dead market handling, wide-spread illiquidity note, cancellation rule parsing, fan-out examples, resolver contract with confidence levels, parent event extraction, news fallback mechanisms, and safety checks. Annotations already indicate readOnly and idempotent; the description adds critical edge-case behaviors.

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?

Long but well-structured: front-loaded with core purpose, then organized into clear sections (input, usage, classifiers, fan-out, response shape, resolver, parent event, news, safety). Every sentence adds value; could be more concise but 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?

Comprehensive coverage given the tool's complexity: input flexibility, classification, fan-out logic, response structure, resolver confidence handling, parent event extraction, news fallback, safety mechanisms, and market state handling. No output schema exists, but the description fully compensates.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context on parameter usage: explains 'quick' vs 'thorough' depth, 'include_raw' purpose, and input formats (slug, URL, question text). This enriches the schema definitions slightly, justifying a 4.

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

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

Clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types and contrasts with similar tools like polymarket_edges, polymarket_arbitrage, etc., by focusing on general research. Sibling differentiation is implicit but effective.

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

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

Explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Provides context but does not explicitly mention when not to use or compare with siblings; however, the examples and structure guide the agent adequately.

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 the tool is read-only, open-world, and idempotent. The description adds significant behavioral details: it reveals data sources (SEC EDGAR/XBRL with off-calendar fiscal year handling, FAERS), mentions result sorting by primary metric, and specifies that it returns paired data with citation URIs. 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 well-structured, starting with common query examples, then stating the core function, followed by details on data sources and output. It is somewhat verbose but each sentence provides valuable information. Front-loading with examples aids quick understanding.

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

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

Without an output schema, the description explains that it returns 'paired data + pipeworx:// citation URIs per entity,' which is sufficient for an agent to understand the return format. It also covers input constraints (2-5 entities) and data sources. Could mention if there are limits on the number of metrics returned, but overall complete for the tool's purpose.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches these by explaining what data is pulled for each entity type (e.g., revenue, net income for companies; adverse-event counts for drugs) and provides examples of valid inputs (e.g., tickers, drug names). This adds meaningful context 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 that the tool performs side-by-side comparisons of 2–5 companies or drugs, citing specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs) and examples of queries it handles (e.g., 'Compare X and Y', 'X vs Y'). It effectively distinguishes itself from sibling tools like 'entity_profile' by emphasizing its multi-entity parallel nature.

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 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear directive for when to use this tool versus making multiple calls to single-entity lookups. It also guides the user on the 'type' parameter for choosing between company and drug comparisons.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds value by disclosing that the operation is keyless and offline, and that it works on integers. These behavioral traits are not present in the annotations and help the agent understand autonomy and data flow.

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 followed by an inline example. It is front-loaded with the core action and constraints (numeral bases 2-36, keyless, offline). Every word serves a purpose, and the example is illustrative without redundancy.

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

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

The example clearly shows the output format (a string), compensating for the lack of an output schema. However, it does not mention error handling (e.g., invalid input, out-of-range bases) or explicitly state that the output is a string. Given the tool's simplicity, the description is mostly complete but could be slightly more explicit about return value type.

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 all three parameters with descriptions and examples. The description does not add additional semantic detail beyond the schema, but the example usage reinforces the parameter relationships. Given 100% schema coverage, a 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 it converts integers between bases 2-36 with a concrete example. The verb 'convert' and resource 'integer between numeral bases' make the purpose unambiguous, and the example reinforces the operation. It distinguishes from sibling tools like 'from_roman' and 'to_roman' by specifying the base range.

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

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

The description mentions 'keyless, offline', which indicates no authentication or network required, but it does not explicitly state when to use this tool versus alternatives like 'number_to_words' or Roman numeral converters. The usage context is implied but not directly addressed.

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

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

The description goes far beyond annotations by detailing account requirements, paid plan tier, parallel execution, findings packet structure (evidence, confidence, source, gaps, contradictions), hop field, citation URI, semantic excerpts, and expected latency. No annotation contradictions; readOnlyHint aligns with the research-only nature described.

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 thorough but not concise; it includes many operational details (e.g., hop field, citation URI, latency ranges) that could be split or organized more compactly. Front-loads the essential account requirement and fallback tool, which is good, but overall length reduces clarity. Still, every sentence adds value for a complex tool.

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

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

Despite lacking an output schema, the description fully covers the return format (findings with fields, gaps, contradictions), depth behaviors, iteration logic, and edge cases (empty gaps for non-catalog topics). It equips the agent to decide, invoke, and interpret results correctly for all intended use cases.

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 significant value by explaining the depth enum's behavioral impact (parallel facets, gap recovery, contradiction scan) and by clarifying the question parameter accepts broad/multi-part queries. The description provides actionable context the schema alone does not.

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 'grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and distinguishes it from siblings like ask_pipeworx (single lookup) and from open-web search. Specific examples of use cases and non-use cases reinforce the purpose.

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

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

Explicit guidance on when to use (broad/multi-part questions over structured data) and when not (single lookup, breaking current news) with named alternatives (ask_pipeworx). Examples like 'compare X and Y's regulatory + financial exposure' make the context clear.

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

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

Annotations already declare readOnlyHint and idempotentHint; description adds that results include full schemas and are 'ready to call directly, no second schema lookup needed,' which is useful behavioral info beyond safety.

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 purpose, list of domains, return value, and usage guidance. It is informative but could be slightly more concise without losing value.

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

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

Given no output schema, the description fully explains the return format (top-N tools with names, descriptions, schemas). It covers all necessary aspects for a discovery tool with clear guidance.

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

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

Schema coverage is 100%, so each parameter is described. The description adds mentions of aliases and examples, but this is not a significant addition beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds tools by describing data or task, lists many domains, and distinguishes it from siblings by indicating it's for browsing/discovery before selecting a specific 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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer),' providing clear when-to-use guidance and implying when not to use it.

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

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

The description details the tool's behavior: parallel call, fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), lists returned fields (cik, recent_filings, fundamentals, patents, news, LEI), and notes the USPTO patent source sunset May 2025 with soft-fail. Annotations (readOnlyHint, idempotentHint) are consistent; 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 comprehensive but slightly lengthy; it front-loads with user queries and then details returns. While every sentence adds value, the structure could be more organized (e.g., bulleted list of returned items) for quicker parsing.

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

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

Given the tool's complexity (multi-source, no output schema), the description covers all key aspects: input constraints, return structure, limitations (patent sunset, name unsupported), and appropriate use. It compensates for the lack of output schema with detailed return descriptions.

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

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

Input schema covers both parameters with descriptions, achieving 100% coverage. The description adds value by providing concrete examples (ticker 'AAPL', CIK '0000320193') and clarifying that names are not supported, though it largely restates 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 states the tool provides a full cross-source profile of US public companies, with explicit examples of user queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from sibling 'resolve_entity' by noting that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and advises using resolve_entity if only a name is available. It provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; description adds context about clearing sensitive data but does not expand beyond that.

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

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

Two concise sentences, front-loaded with main purpose, 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?

Sufficiently complete for a simple tool with one required parameter, no output schema; covers purpose and usage guidance.

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 no extra meaning beyond what the schema already provides for the 'key' parameter.

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

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

Clearly states verb 'delete' and resource 'memory by key', distinguishing from siblings like 'remember' and 'recall'.

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

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

Provides explicit usage contexts: stale context, task done, clear sensitive data. But lacks explicit when-not-to-use or 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 indicate read-only, idempotent, non-destructive behavior. The description adds that the tool 'rejects malformed numerals', which is a behavioral trait beyond annotations.

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

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

Single sentence that is concise and front-loaded with the core action. No unnecessary words.

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

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

Given the simple parameter and the presence of annotations, the description covers the main function and validation. Lacks details on return value or error handling, but acceptable for a low-complexity tool.

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

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

Schema coverage is 100% with clear parameter description. The description does not add additional meaning beyond what the schema already provides.

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

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

The description clearly states the tool converts a Roman numeral to an integer and mentions rejection of malformed numerals. However, it does not explicitly distinguish from the sibling tool 'to_roman'.

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

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

No guidance on when to use this tool versus alternatives. No mention of context, prerequisites, or when not to use.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description goes beyond by explaining the process: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This covers behavioral traits without contradicting annotations.

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

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

The description is two sentences: first sentence states the core function and output format, second lists use cases. Every sentence adds value, no fluff, and critical information is front-loaded (generates llms.txt, for AI crawlers).

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 explicitly states the return value ('single text blob ready to drop at site-root/llms.txt') and mentions the standard format. For a simple tool with two parameters and clear annotations, 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% with descriptions for both url and max_links. The description adds no additional meaning beyond the schema; it only mentions extraction of 'title/description/key links,' which is implied by the url parameter. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool generates an llms.txt file, specifies the verb 'generate' and the resource, and lists concrete use cases (e.g., getting a client's site indexed, drafting for own project, auditing competitors). This distinguishes it from sibling tools like scan_competitor_ai_presence, which focus on auditing rather than generating.

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 scenarios ('Useful for: getting a client's site indexed...') but does not discuss when not to use the tool or mention alternatives. It gives clear context but lacks exclusions or comparisons to related tools like ai_visibility_check.

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 destructiveHint=false, so the safety profile is clear. The description adds the list of returned fields, which supplements behavioral understanding without contradicting annotations.

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

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

The description is two sentences, front-loading the core action and followed by usage guidance. Every sentence adds value without fluff, making it highly 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?

For a simple list tool with one optional parameter, strong annotations, and no output schema, the description covers purpose, output fields, and usage scenario completely.

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

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

Schema coverage is 100% and the description for the only parameter ('include_inactive') exactly matches the schema description. The description adds no new meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states it lists the caller's active subscriptions, specifying returned fields. While the purpose is clear, it does not explicitly differentiate from sibling tools like subscribe or unsubscribe, but the verb and resource are distinct enough.

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: to review subscriptions before adding more or to find an id to cancel. It doesn't mention when not to use or alternatives, but the given context is helpful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, fully covering the safety and idempotence profile. The description adds no additional behavioral traits (e.g., supported range, handling of negatives, large numbers). Contributes minimal value beyond annotations.

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

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

The description is a single sentence with an immediate purpose statement and an illustrative example. No extraneous words or fluff. Perfectly front-loaded 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?

For a simple tool with one parameter and good annotations, the description covers the core functionality with an example. Minor gaps: does not specify numeric range, behavior for zero or negative numbers, or output format for edge cases. Still, it is largely complete given the tool's simplicity. Missing output schema is acceptable as the return value is implicit from the example.

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

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

Schema coverage is 100% with a single parameter 'number' described as 'An integer.' The description adds an example but no further semantic detail or formatting constraints. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's function: 'Spell an integer in English words'. The example differentiates it from siblings like to_roman and convert_base by showing the English word output. It is specific and unambiguous.

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

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

The description implies the tool is for converting numbers to words but does not explicitly state when to use it versus alternatives (e.g., to_roman, convert_base). No when-not guidance is provided. Usage is inferred from the example, but explicit guidance is missing.

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

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

Despite having no annotations, the description discloses key behavioral details: filing without an account returns a claim_token for later status checks, rate-limited to 5 per identifier per day, and free. This adds significant value beyond the 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?

The description is longer than average but front-loaded with purpose and usage. Every sentence contributes relevant information, though it could be slightly more concise.

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

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

Given no output schema and a relatively complex feedback workflow, the description covers return behavior, rate limits, scoping to Pipeworx tools, and how to follow up with claim_token. This is complete and self-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?

The input schema already covers all parameters (100% coverage), but the description adds important context: how to phrase feedback in terms of Pipeworx tools/packs, and the purpose of claim_token for retrieving previous reports. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling tools like ask_pipeworx by focusing on reporting issues with Pipeworx tools specifically.

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 conditions: 'Use when a tool returns wrong/stale data...' and when not to use: 'if the tool came from a different MCP server... file it with that server instead.' This is excellent guidance with clear exclusions and alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds further behavioral context: data is derived from Cloudflare analytics, no PII, only aggregated counts, and caching intervals (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?

Description is concise (4 sentences) with front-loaded key information. Every sentence adds value: purpose, use cases, data source, caching. No redundancy.

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

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

Given the single optional parameter and no output schema, the description adequately covers what is returned (top tools, packs, call volume) and the time windows. Could mention if the list is ordered but not required.

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

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

Schema coverage is 100% with a description for the only parameter 'window'. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose.

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 'returns' and the resource: top tools, top packs, and total call volume over a configurable time window. It distinguishes from sibling tools by focusing on trending/popularity data, which is unique among the listed siblings.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming popular canonical tool, and aligning use case with demand). However, it does not exclusions or alternatives when not to use, but the context is clear enough for selection.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: fill checks against live CLOB depth, semantic filters (Jaccard similarity, placeholder fraction), and conditions under which signals should be ignored. 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 thorough and well-structured, with clear sections for modes and additional details (semantic anchor, partition filter, fill check). It front-loads the core purpose. While somewhat verbose, every sentence serves a purpose given the tool's complexity.

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

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

Despite no output schema, the description fully explains the return structure (opportunities[] fields, partition_check details) and edge cases (realizable_edge_pp ≤ 0, placeholder filtering). Covers all necessary context for a complex tool with 2 optional parameters.

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 substantial meaning: explains that event accepts slugs or full URLs, topic accepts seed questions, and the behavior with no args (trending scan). It also explains what each parameter triggers in terms of internal checks.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between two explicit modes (trending scan with no args, event for specific market, topic for cross-event), making its purpose specific and distinct from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description provides explicit when-to-use guidance: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. It also explains when not to trade (realizable_edge_pp ≤ 0) and mentions an alternative tool (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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: caching at KV level, detailed model families and their formulas, response structure (by_segment, fed_candidates, diagnostics), and special handling of Fed bets. 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 quite lengthy but well-structured, with clear sections and definitions. Every sentence adds value, but there is some verbosity (e.g., detailed formula explanations). It remains front-loaded with the core purpose.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and caching behavior. It covers all parameter semantics and use cases, making it complete for an agent to effectively invoke 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%, but the description adds significant meaning beyond the schema. It explains default values, the role of each knob (e.g., min_kelly as half-Kelly fraction, min_partition_leg_kelly applying to per-leg Kelly), and practical context like 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade.'

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and distinguishes it from sibling tools by detailing its specific models and segments (e.g., crypto_price, news_momentum, partition_overround). It uses a specific verb ('scan... and return') and resource ('top Polymarket markets').

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

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

The description explicitly states when to use the tool ('what should I bet on today' discovery) and describes various filtering knobs (min_liquidity, max_spread_pp, etc.). However, it does not explicitly state when not to use it or provide alternatives, though the sibling tools list implies separation of concerns.

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 readOnly, openWorld, and idempotent. The description adds behavioral details like snapshot TTL, decay computation from daily closes, and data gaps. 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 comprehensive but could be slightly more concise. It is well-structured with a clear opening, detailed response fields, and limitations.

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

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

No output schema exists, so the description fully explains the response structure (tracked, expired, snapshot_dates) and limitations (TTL, decay computation). This is highly 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?

Schema descriptions cover 100% of parameters. The description adds context for 'days' (default 14, max 30) and 'window' (snapshot family, default '1wk'), enhancing the schema's meaning.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry, answering how long an edge has existed and if it is shrinking. It distinguishes from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description implicitly tells when to use the tool by explaining the value of distinguishing fresh vs. old edges. However, it does not explicitly mention when not to use or list alternative tools.

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

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

Discloses detailed behavior: walks ladder, returns fills, slippage, verdict, and per-leg details. Warns about forced directional risk. Annotations (readOnlyHint, idempotentHint) align with read-only nature, 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?

Structured with bold headings for modes and usage, front-loaded with purpose. Slightly verbose but justified given complexity; no wasted sentences.

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 fully documents return values for both modes. Covers parameters, usage, risks, and edge cases (thin_legs, forced directional risk). 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?

Schema coverage is 100%, but the description adds context (e.g., size_usd as settlement notional for basket, default side auto-detection). Adds value 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 clearly states it checks realizable-vs-theoretical edge against live order book depth, with specific single-market and basket modes. Distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on fill risk/feasibility.

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 before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', and warns about partial basket fills converting arbs into unhedged positions. Provides clear when-to-use and risks.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds detailed behavioral traits: two modes, response fields, safety conditions for compatibility_warning, temporal_alignment, skipped counters, and the caveat about pre-mapped topics. 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 thorough and well-structured, front-loading key information. It is slightly verbose but every sentence adds value for a complex tool. Could be slightly more concise but appropriate for the complexity.

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

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

Given no output schema, the description covers return fields (spread, compatibility_warning, temporal_alignment, skipped counters) comprehensively. It covers safety fields and conditions, making the tool self-contained for an agent. Input schema includes examples.

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

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

Schema coverage is 100% with descriptions. The tool description adds meaning beyond schema by explaining modes (topic vs explicit), the list of topic shortcuts, and the override behavior for explicit tickers. It provides context that schema alone does not.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from siblings like polymarket_arbitrage by specifying cross-venue comparison. Two modes and response structure are explicitly described.

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

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

The description explains when to use (for cross-venue spreads) and warns that pre-mapped topics may not be tradeable, providing clear guidance. It does not name alternatives explicitly but context from sibling tools suggests intra-venue 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, idempotentHint, destructiveHint. Description adds scoping to identifier and pairing with remember/forget, which provides useful context beyond annotations.

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

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

Two sentences with no waste. Front-loaded with action, efficiently conveys purpose and guidelines.

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?

Description is complete for the tool's simplicity. No output schema needed as return type is implied (value or list). Could mention data type of stored values but not critical.

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 schema's property description already explains omitting key lists all keys. Description adds no additional semantic 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?

Clearly states it retrieves a saved value or lists all keys. Distinguishes from sibling tools 'remember' and 'forget'.

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

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

Explicitly says when to use (look up stored context) and not to re-derive from scratch. Mentions pairing with remember/forget and scope.

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 readOnlyHint=true, but the description reveals that mark_read:true can flag events as read, modifying state. This creates a contradiction. The description does disclose return fields and optional side-effects, but the contradictory annotation reduces clarity.

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 main purpose and efficiently covers parameters in four sentences. There is no fluff, and every sentence adds value. Minor improvement could be more structured formatting.

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 return fields (source, citation_uri, payload) and covers parameter behavior. It also mentions polling and an alternative access method. It lacks pagination details and error handling, but overall is sufficient for the agent.

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

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

The schema covers all 5 parameters, and the description adds value by providing examples (e.g., type='sec_8k'), explaining the effect of mark_read, and clarifying the behavior of since. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states it pulls fired events from a subscription feed, specifies return fields, and mentions filtering options. It distinguishes from siblings like list_subscriptions by focusing on events rather than subscriptions. However, it doesn't explicitly differentiate from other possible alert-related 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 mentions that polling works fine and provides an alternative GET endpoint, giving some usage context. However, it doesn't specify when not to use this tool or compare it directly to siblings, leaving some ambiguity for the agent.

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

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

Discloses multi-source fan-out, fallback behavior (GDELT→GNews), soft-fail for USPTO, and return format. Annotations already indicate safety, and description adds valuable context 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?

Well-structured with example queries up front, then source details, parameter guidance, and sibling differentiation. 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?

Given the tool's complexity (multiple sources, fallback, soft-fail) and no output schema, the description fully covers behavior, parameters, and use cases. Agent can confidently select and invoke.

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

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

Schema coverage is 100%, and description adds context for 'since' with examples, clarifies 'value' accepts ticker or CIK, and notes 'type' limited to company. Provides recommended default for 'since'.

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 it's a change feed for a company in a time window, listing specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and example queries. Distinguishes from sibling entity_profile.

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

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

Explicitly says when to use this tool (latest changes) and when to use alternative (entity_profile for static profile). Provides example query patterns and date format recommendations.

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 include idempotentHint: true and destructiveHint: false. The description adds critical context: scoped by identifier, 24-hour retention for anonymous sessions, and persistent for authenticated users.

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

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

Four sentences with no fluff. Purpose is front-loaded, and each sentence adds value: purpose, usage context, storage details, and sibling references.

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 write tool with full schema annotations, the description covers scope, persistence, and relationships with recall/forget. No output schema is needed.

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

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

Schema coverage is 100% for both parameters. The description adds examples of value types ('findings, addresses, preferences, notes'), providing extra context 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 'Save data' and the resource 'data the agent will need to reuse later', with specific examples (resolved ticker, target address). It distinguishes from sibling tools by naming recall and forget.

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

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

Explicitly says when to use ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). Also notes session vs persistent memory.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses significant behavioral traits: it cascades through multiple lookup endpoints, degrades gracefully when external services are unavailable, labels identifiers with provenance, and explicitly reports unresolved identifiers. This is rich, useful context that annotations do not provide.

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

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

The description is lengthy but well-structured, starting with the core purpose and examples, then detailing supported types, sources, and edge cases. Every sentence provides value, though it could be slightly tightened. The examples and structured breakdown make it acceptable for the complexity.

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

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

Given no output schema, the description compensates by explaining the return format (identifiers labeled with source, unresolved explicitly listed) and covers fallback behavior, supported inputs, and internal cascade. It provides a complete picture for an agent to invoke the tool confidently.

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 has good descriptions, but the description adds substantial meaning: examples of accepted values, the fact that ISIN maps to the legal entity via GLEIF, and the mention of specific sources (SEC EDGAR, GLEIF, OpenFIGI). This enriches the parameter semantics beyond the schema's basic descriptions.

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

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

The description clearly states the tool's function: resolving user-spoken names to canonical/official identifiers. It provides concrete example queries and distinguishes the tool from siblings by instructing to use it 'FIRST whenever you have a name but need an ID.' This is a precise verb+resource+scope definition.

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

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

Explicit usage guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types (company, drug) and input formats (ticker, CIK, ISIN, brand/generic name), covering when to apply the tool. It does not explicitly list exclusions, but the directive is strong enough to guide correct selection.

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

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

Beyond annotations (readOnly=true, idempotent=true), the description reveals it internally calls ai_visibility_check for each entity and returns score, confidence, signal density. This adds behavioral detail without contradicting annotations.

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

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

Three sentences: core action, internal mechanism, use case + output. Every sentence adds value. No redundancy, perfectly 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?

Lacks an output schema but describes output format (ranked list with score, confidence, signal density). Covers multiple probes, ranking, and competitive context. Minor omission: no mention of error handling or dependency on ai_visibility_check, but overall sufficient for a composite tool.

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

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

Schema coverage is 100%, so baseline 3. Description adds minimal value: mentions 'first entity treated as subject' and 'optional shared context', but schema already describes both. No additional parameter semantics beyond what schema provides.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, probes each with ai_visibility_check, and returns a ranked list. Distinguishes from sibling ai_visibility_check (single entity) by explicitly mentioning it uses it and compares.

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 a concrete use case ('competitive AI-marketing audits') and an example question. Implies when to use (multiple entities) but does not explicitly state when not to use or list alternatives besides the implied single-entity sibling.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral context: it fans out across deps.dev and bundlephobia, bundlephobia's first measurement can take 5-30s, and partial failures report sources_failed. 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 dense but informative, front-loading the core purpose. It could be slightly shorter, but each sentence adds value given the tool's complexity. Only minor excess like 'Composite' at start.

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 comprehensively lists return fields (summary block with specific metrics, per-advisory detail, links, alternative versions). It also covers performance caveats and partial failure behavior, making it nearly 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?

Schema coverage is 100% with clear descriptions for both parameters (package name and optional version). The description adds minor value by restating that the default version is latest and scoped packages are accepted, but doesn't significantly enhance parameter 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 it performs a composite check for adding an npm package, covering license, advisories, version history, bundle size, dependency count, and ESM/tree-shake support. The verb 'scan' and resource 'dependency' are specific, and it naturally distinguishes itself from siblings like scan_competitor_ai_presence.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also specifies NPM-only scope in v1, and describes graceful degradation with partial failures, which guides when to use 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable details: max input size (200K chars), truncation warning, embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), and output features (character offsets, 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 compact paragraph that front-loads the core purpose, then efficiently adds usage context, pairing suggestion, and 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?

Despite lacking an output schema, the description fully covers return values (top N passages with offsets and scores), constraints (200K char limit, truncation flag), and use cases. All three parameters are explained comprehensively. The tool's moderate complexity is well addressed.

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

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

Schema coverage is 100% with all three parameters described. The description adds concrete examples for 'query' (e.g., 'supply-chain risk'), specifies default for 'limit' (5), and clarifies the max length for 'text'. This goes 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 performs semantic search inside a fetched record, provides concrete examples (SEC 10-K body, article), and explains the input-output behavior. It indirectly distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

The description explicitly says 'use when the record is too big to cram into the prompt' and notes it saves context. It also suggests pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or list alternatives beyond the sibling pairing.

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 write operation (readOnlyHint=false) with idempotentHint=true and openWorldHint=true. The description adds behavioral context: requires OAuth, delivery channels (feed always on, optional email/sms/webhook with constraints like 10 SMS/day limit, webhook auto-disable after 10 failures, signing secret returned once). 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 relatively long but front-loaded with the core purpose. Every sentence adds value, though some technical details (e.g., webhook HMAC signing) could be abbreviated. Still, it remains clear and well-structured.

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

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

Given the tool's complexity (3 params including nested objects, no output schema) and the presence of sibling management tools, this description provides complete context: subscription creation, types, delivery, OAuth requirement, and constraints. No missing critical information.

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

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

Schema coverage is 100% so baseline is 3. The description adds significant value by explaining each enum option for type, providing detailed examples for params per type, and clarifying delivery fields including verification and caps. This goes well beyond the schema's minimal descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes this from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description explains when to use the tool (for proactive monitoring), requires Pipeworx OAuth account, and lists supported subscription types with parameter examples. It does not explicitly state when not to use it or name alternatives, 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 cover read-only, open-world, idempotent, non-destructive traits. Description adds valuable context about return content (category-bucketed with exact tool+argument shape) and behavior with/without topic. No contradictions.

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

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

Description is informative and well-structured, front-loading the primary purpose. Slightly verbose but every sentence adds value; could be tightened slightly without loss.

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 one optional parameter and no output schema, the description thoroughly explains tool output format, coverage, and usage scenarios, making it complete for agent understanding.

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

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

Schema coverage is 100% for the one parameter, but description adds extra meaning by listing possible topic values ('finance, pharma, ...'), explaining effect of omission, and clarifying output customization.

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

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

Clearly states the tool returns category-bucketed example questions for onboarding, listing specific categories and distinguishing it as the first-use entry point for learning about Pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions learning how to call meta-tools like ask_pipeworx, providing clear when-to-use guidance and 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds the range constraint but no additional behavioral disclosure (e.g., no mention of error handling or output format). Description does not contradict annotations.

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

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

A single, front-loaded sentence that efficiently communicates the core purpose without unnecessary words. Every word earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema, clear name), the description is sufficiently complete. It covers the input range and purpose. The output type (Roman numeral string) is implied by the tool name and description.

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

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

Schema coverage is 100% with a clear parameter description. The description repeats the range from the schema but adds no new semantics beyond what the schema already provides.

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

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

The description clearly states the verb 'Convert' and the resource 'integer to Roman numerals' with a specific range '1-3999'. It distinguishes itself from the sibling tool 'from_roman', which does the opposite conversion.

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 when to use (converting to Roman) but lacks explicit guidance on when not to use or mention of the alternative sibling 'from_roman'. Usage context is implied through purpose clarity.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), description adds that row is deactivated (not deleted) and historical events remain, providing critical 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?

Three concise sentences with no waste: action, ownership constraint, and side effects all efficiently communicated.

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

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

For a simple tool with one parameter and no output schema, description fully covers action, constraint, and outcome, making it complete.

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

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

Schema coverage is 100% with parameter description 'Subscription id (uuid) returned by subscribe.' Description adds minimal extra meaning beyond confirming 'by id'.

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 'Cancel a subscription by id' with specific verb and resource, distinguishing 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?

Ownership enforcement is explicitly stated ('you can only cancel your own subscriptions'), clarifying when to use. No explicit alternatives mentioned, 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?

Beyond the annotations (read-only, open-world, idempotent), the description adds critical behavioral context: the distinction between 'could_not_verify' (a pipeline failure that is NOT evidence) and 'unsupported' (no source covers it), the two routing paths, and the return format. This significantly enriches the agent's understanding of expected behavior. No contradiction with annotations.

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

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

The description is dense and front-loaded with call patterns, but it is somewhat long and includes some repetition (e.g., explaining the grounded pipeline multiple times). It could be slightly more structured, but every sentence carries meaningful information for this complex tool, so it earns a high score.

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

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

Given the tool's complexity (two routing paths, five verdict types, error cases), the description is remarkably complete. It explains return values (verdict, value, citation, reasoning), clarifies the meanings of the most ambiguous verdicts ('could_not_verify' and 'unsupported'), and states when the tool should be used. With no output schema provided, this description carries the full burden and does so well.

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 both parameters (claim, tolerance_pct), so the baseline is 3. The description adds some context about percent-delta math and hallucination detection tolerance, but mostly reinforces schema details rather than introducing new parameter semantics. It does not compensate for any gaps, but none are needed.

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 a specific verb+resource: 'validate_claim' with natural-language claim verification, and provides clear examples of user intents ('Is it true that…', 'fact check'). It differentiates itself by explaining its claim-verification output (verdict) and the routing of financial vs non-financial claims, which sets it apart from the broader research tools in its sibling list.

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

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

Explicit usage guidance is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies sub-routing for company-financial claims via SEC EDGAR and any other claim via a grounded pipeline, plus notes that it replaces 4–6 sequential calls. This is clear when-to-use direction.

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