Doaj

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the description doesn't need to repeat safety. It adds valuable context: returns per-model objects with score, confidence, signals, raw_response, and a combined view. It also discloses cost implication for Anthropic probes. 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 concise (two sentences) with no wasted words. It front-loads the primary action and return value. The structure is clear and easy to parse.

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

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

Given that there is no output schema, the description adequately describes the return structure (per-model and combined view). It covers all key aspects: purpose, parameters, default vs. optional costs, and return format. The tool is not overly complex, and the description is fully sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant meaning beyond the schema: it specifies the default model (Workers AI Llama-3.3-70b, free), explains when `_apiKey` is needed (only for Anthropic), clarifies that models array can be omitted to use only the default, and gives an example for entity. This greatly aids the agent in parameter usage.

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: probing LLMs for knowledge about a specified entity and returning visibility scores per model. It uses specific verbs ('probe', 'score') and specifies the resource (LLMs). Although there is a sibling tool 'scan_competitor_ai_presence', the focus on scoring visibility (0-100) across multiple models distinguishes it adequately.

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 usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains when to use it and mentions default model vs. optional Anthropic (with BYO key). However, it does not explicitly state when not to use it or compare to siblings, so it's slightly below a perfect score.

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

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

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds valuable context: the routing mechanism, citation output, 'one fast call' performance, and the implication that the grounded variant is more hallucination-resistant. This goes beyond the structured annotations.

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

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

The description is longer than ideal but well-structured and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'). Each sentence contributes value, and the examples are useful. Minor verbosity prevents a perfect score.

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

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

For a complex router tool with no output schema, the description adequately explains what it returns (structured answer with citation URIs), how it works, when to use it, and how to choose alternatives. It is self-contained and provides enough context for an agent to invoke it correctly.

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

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

The schema already fully documents the six parameters as aliases for a natural-language question (100% coverage). The description enhances this by providing concrete examples and specifying the types of questions the tool can handle, adding practical meaning beyond the schema.

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

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

The description clearly states the tool's function: it routes questions to one of 5,529 verified source tools and returns structured answers with citations. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives for specific use cases.

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

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

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH'), trigger phrases, examples, and clearly explains when to step up to alternatives ('Step up only when needed'). It also notes that breaking-news is already covered by this tool, preempting a potential 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses that the tool is an experimental beta with candidate routing improvements, that no candidate is currently active, and that results are compared with the stable router. It also clarifies that it is not a fallback but a fully functional router, adding meaningful context about its current behavior and release state.

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

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

The description is four sentences and front-loaded with the key point ('Beta version of ask_pipeworx'). Each sentence adds useful information, though the length is slightly greater than necessary for a tool that otherwise points to another tool for full details.

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

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

For a beta experimental router with no output schema, the description covers the current status, functional equivalence to ask_pipeworx, usage intent, and the evaluation context. It is complete enough for an agent to decide whether to use it, though it relies on the sibling tool for the full operational details.

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 six parameters fully documented as aliases for 'question' and described as a natural-language request. The description references 'same arguments' and the same 5,529 tools, but it does not add semantic detail beyond what the schema already provides, so the baseline 3 applies.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router that handles natural-language questions and routes to one of 5,529 tools. It distinguishes itself from the stable sibling ask_pipeworx via the beta label and the stated 'candidate routing improvements' context, though it lacks a standalone verb beyond 'Ask' in the name.

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

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

The description explicitly provides usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative (stable ask_pipeworx) and clarifies the experimental purpose, while also preempting confusion by stating 'Falls back to nothing — this IS a full working router.'

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?

Provides extensive behavioral detail beyond annotations: describes the internal process (routing, fetching, extracting only from tool result), the return structure with fields like evidence and refusal_reason, and the explicit refusal reasons. Annotations already declare read-only and idempotent, and the description complements this by explaining the extra LLM call and refusal behavior. 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 information-dense yet every sentence earns its place. It starts with the core value proposition ('Hallucination-resistant answer mode for high-stakes reads'), then succinctly covers behavior, return format, refusal modes, usage context, and cost trade-off. No fluff or redundant repetition of schema/annotations.

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 (routing across 5,529 sources, extraction, refusal handling) and the absence of an output schema, the description is remarkably complete. It explains the purpose, usage context, return contract, failure modes, and relationship to the sibling tool. There is no significant missing information for an agent to invoke it correctly.

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

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

Schema description coverage is 100% — all 6 parameters are aliases for the natural language question, with clear descriptions. The tool description adds context about how the question is used (routing, extraction) but doesn't provide additional parameter-level semantics beyond what the schema already states. This meets the baseline for high coverage but doesn't exceed it.

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

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

The description clearly states a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It immediately distinguishes itself from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but adding the extraction and refusal behavior, and later explicitly mentions the cost difference versus ask_pipeworx. This makes the tool's unique role within the sibling set very clear.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and provides a direct alternative: 'prefer ask_pipeworx for casual lookups.' It also notes the extra LLM call cost as a trade-off, giving complete guidance on when to choose this tool vs. the 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=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral detail: market resolution, classification, fan-out, response shapes, resolver contract, parent event extraction, news fields, safety checks, market closed handling, wide spread handling, cancellation rule risk. No contradiction; description expands on the read-only, safe nature.

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

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

The description is very long (over 500 words) and covers many details, examples, and edge cases. While well-structured with sections, it could be more concise. Every sentence adds value, but the length may overwhelm an agent.

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

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

Given the tool's complexity (3 parameters, no output schema), the description is highly complete. It explains return shapes, resolver contract, edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. Covers safety and blocking mechanisms. No output schema needed given the detailed behavioral and return 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%, but description adds meaning beyond enum labels. For 'depth', it explains 'quick = 2-3 evidence sources, thorough = full fan-out. Default thorough.' For 'include_raw', it clarifies the trade-off (response size vs. detail). For 'market', it allows slug, URL, or question text. These additions help the agent understand 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?

Clearly states it researches Polymarket bets by pulling Pipeworx data. The verb 'Research' and resource 'Polymarket bet' are specific. It distinguishes from sibling tools like ask_pipeworx (general data query) and polymarket_arbitrage by focusing on single bet evaluation with evidence gathering.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides classifiers and examples. Does not explicitly state when not to use or name alternatives, but the context is clear and sufficient for an agent to understand appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral details: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, returns sorted results with citation URIs, and replaces 8-15 sequential lookups. 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 front-loaded with trigger phrases and contains dense, useful information. While somewhat long, almost every sentence adds value. Could be slightly more concise but not wasteful.

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 the description explains the return format (paired data + citation URIs, sorted by primary metric). For a comparison tool with 2 params, this is sufficient for an agent to understand what to expect.

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% (type and values described). The description adds meaning by explaining what data is pulled for each type (company vs drug), constraints (2-5 items), and examples. This goes beyond the schema, justifying above baseline 3.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, provides trigger phrases (e.g., 'compare X and Y', 'X vs Y'), and distinguishes itself from sequential single-pack lookups, which are sibling tools.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' giving clear guidance on when to use. It lacks explicit when-not-to-use instructions but the context is sufficient.

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

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

Annotations already cover readOnly/idempotent hints; description adds sign-in requirement, depth tiers, parallelism, gaps[] never invented, hop fields, citation_uri resolvability, contradictions[], latency expectations, and semantic excerpting. 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?

Dense but long single paragraph; every sentence adds value, though structure could benefit from bullets. For the complexity, it's compact and front-loaded with critical prerequisite (account).

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

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

Covers prerequisites, use cases, alternatives, behavior, return format, performance, edge cases. No output schema, so the description's explanation of findings packet, gaps[], contradictions[], and citation fields is essential and fully provided.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds depth-tier behavioral meaning (gap recovery, lead-chasing, contradiction scan) and question guidance, going beyond the schema's enum descriptions.

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

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

Specific verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' with explicit contrast to 'NOT open-web search' and sibling distinction from ask_pipeworx. Clearly states what it does and how it differs from alternatives.

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

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

Explicit when-to-use and when-not-to-use: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and account requirement with alternative. Provides clear context and exclusions.

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

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

Annotations declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the tool returns curated results with full schemas and examples, ready to call without a second lookup. This expands on the static annotations and provides useful behavioral context.

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

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

The description is front-loaded with the core action, followed by domain examples and output description. While it lists many domains, every sentence adds value. It is well-structured and efficient, though slightly verbose.

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

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

Given the complexity (6 parameters, 100% schema coverage, no output schema), the description adequately explains what the tool returns (names, descriptions, schemas with examples, ready to call). It provides sufficient context for an agent to understand the tool's functionality and output.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by mentioning that the query accepts aliases (task, q, description, search) and providing examples of natural language descriptions (e.g., 'look up FDA drug approvals'). This helps the agent understand parameter semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains that it returns top-N relevant tools with names, descriptions, and full input schemas, ready to call. This distinguishes it from siblings like search_articles, which search data, not tools.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context for when to use it. However, it does not explicitly state when not to use it or mention alternatives, though the sibling list implies specific tools for specific tasks.

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 idempotent, read-only, open-world, non-destructive hints. The description adds valuable context beyond these hints: it details that the tool fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), explains the patent data situation (sunset May 2025, soft-fails), and specifies return fields (e.g., recent_filings up to 5 with 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 fairly long but well-structured with examples, bullet points, and explicit guidance. Every sentence adds value, though some details (e.g., patent sunset) could be more concise. It is front-loaded with the primary purpose and usage, making it easy to scan.

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

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

Given the complexity of the tool (multiple sources, varied return fields, limitations), the description is highly complete. It explains the inputs, outputs, data sources, and known limitations (patent sunset, name unsupported). No output schema is present, so the description adequately covers return 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 meaning beyond the schema: it explains that 'type' is currently only 'company', that 'value' accepts ticker or zero-padded CIK but not names, and provides concrete examples. This extra context is helpful but not exhaustive (e.g., does not specify CIK zero-padding length or case sensitivity).

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example queries, lists the data sources and returned fields, and distinguishes itself from chaining single-pack lookups. The verb 'profile' combined with the resource 'entity' is specific and action-oriented.

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 tells when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides guidance on when not to use it ('names not supported — use resolve_entity first if you only have a name') and suggests an alternative tool. This gives clear context for decision-making.

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 destructiveHint=true and readOnlyHint=false, so the description's mention of 'delete' is consistent but adds little new behavioral context. It adds some context about data sensitivity but no additional behavioral details beyond the annotations.

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

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

The description is concise: two sentences with no wasted words. The first sentence front-loads the action, and the second provides usage context. Every sentence is purposeful.

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 one-parameter delete tool with no output schema, the description covers purpose, usage conditions, and relationships to sibling tools. It is complete and sufficient for an AI agent.

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

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

The description mentions 'by key', which aligns with the single required parameter 'key'. However, the schema already describes the key as 'Memory key to delete' (100% coverage), so the description adds no extra parameter 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 action ('Delete') and the resource ('previously stored memory by key'). It distinguishes from sibling tools 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?

The description provides explicit use cases: 'when context is stale, the task is done, or you want to clear sensitive data'. It also recommends pairing with 'remember and recall', giving clear guidance on 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?

The description discloses the fetching, extraction, and emission steps, adding behavioral context beyond the annotations (readOnly, idempotent, non-destructive). It does not mention potential failure cases but is adequate.

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 purpose and is concise (5 sentences). Every sentence adds value with no wasted words.

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

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

Given the moderate complexity, no output schema, and complete schema coverage, the description fully explains the tool's action and output, making it complete for agent usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning by explaining the process and the output format, providing context that complements the schema.

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

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

The description uses the specific verb 'Generate' with the resource 'llms.txt file' and the context 'for any URL', clearly stating the tool's function. It distinguishes from siblings by focusing on creating a specific file type, unlike ai_visibility_check which might check 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?

The description lists three specific use cases: getting a client's site indexed, drafting for own project, or auditing competitors. While it doesn't explicitly say when not to use, 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?

The description adds no behavioral context beyond what annotations already provide. Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description does not contradict these, but it also does not elaborate on traits like rate limits or data freshness. With strong annotations, a score of 3 is appropriate.

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 no wasted words. It is front-loaded and efficient, conveying the entire purpose in 6 words.

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

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

For a simple tool with one parameter, an output schema, and comprehensive annotations, the description is adequate. It could briefly mention the output format, but the output schema already covers that. Overall, it is complete enough for an agent to use correctly.

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

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

Schema coverage is 100% with a single parameter 'id' described as 'DOAJ article id'. The description does not add additional meaning beyond what the schema provides. Baseline 3 is correct.

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 'Fetch an article by DOAJ id.' It uses a specific verb ('Fetch') and resource ('article'), and the distinct parameter (DOAJ id) helps differentiate it from sibling tools like 'get_journal' and 'search_articles'.

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 is provided on when to use this tool versus alternatives like 'search_articles' or 'get_journal'. The description does not mention any prerequisites, exclusions, or contextual hints.

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 confirms it is a read operation, consistent with annotations (readOnlyHint, idempotentHint). However, it adds no additional behavioral context beyond what annotations already provide, such as behavior on missing IDs or rate limits.

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

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

The description is a single, concise sentence with no extraneous information. It is entirely 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 fetch-by-id tool with annotations covering safety and an output schema, the description is complete. No additional details are necessary.

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

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

Schema description coverage is 100% for the single parameter 'id', which is already documented in the schema. The description does not add further meaning or usage examples 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 'Fetch a journal by DOAJ id' clearly states the action (fetch), the resource (journal), and the unique identifier (DOAJ id). This effectively distinguishes it from siblings like 'get_article' and 'search_journals'.

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 using this tool when you have a DOAJ id, but it does not explicitly state when to use it over alternatives like 'search_journals' or 'get_article'. No exclusion criteria or context is provided.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false. The description adds return schema details and the scope (active subscriptions, optional include_inactive), providing 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 concise sentences: first states purpose and output, second provides usage guidance. 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?

For a simple list tool with one optional parameter and no output schema, the description sufficiently covers purpose, return data, and usage 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 the single parameter having a clear description. The description reinforces the parameter's effect (active vs including inactive) but does not add new 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 states the tool lists the caller's active subscriptions and specifies the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Explicitly states when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implies 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?

Despite all annotations being false, the description discloses rate limiting (5 per identifier per day), the claim_token follow-up mechanism, and that reports are free and don't count against quota. It also explains that calling with just a claim_token reads a previous report, which is essential behavior an agent wouldn't infer from 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, with each sentence serving a distinct purpose (scope, use cases, exclusions, follow-up, limits). It is longer than minimal, but every sentence earns its place, and the front-loaded purpose makes it easy to scan.

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

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

For a tool with no output schema and uninformative annotations, the description is remarkably complete: it covers submission scenarios, context structure, claim_token lifecycle, rate limits, and cost. No critical guidance is missing for an agent to invoke it correctly.

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

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

The input schema already describes every parameter (100% coverage), so the baseline is 3. The description adds practical advice beyond the schema, such as not pasting the end-user's prompt and passing claim_token with no other arguments, which elevates it above baseline.

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

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

The description clearly states the tool's purpose: to tell the Pipeworx team what is broken, missing, or needs to exist. It explicitly scopes to tools served by this Pipeworx connection, distinguishing it from sibling research/query tools like ask_pipeworx or discover_tools.

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

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

It provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data...'), and what NOT to do ('if the tool came from a different MCP server... file it with that server instead'). This directly names an alternative behavior, making it a model example of usage 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 readOnly and idempotent hints. The description adds context: no PII, derived from CF analytics-engine, cached 5min-1h. It doesn't contradict annotations and provides useful behavioral details beyond 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?

Two short paragraphs with no redundant information. The core functionality is stated first, followed by use cases. Every sentence adds value.

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

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

Given the simple schema (one optional param, no output schema) and rich annotations, the description is complete. It explains the return data, data source, caching, and privacy, covering all necessary context for an agent to use the tool correctly.

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

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

The single optional parameter 'window' has a full enum and description. The description adds semantic guidance: shorter windows surface what's hot, longer show steady-state demand, which goes beyond the simple enum values.

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

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

The description clearly states it returns trending data (top tools, top packs, total call volume) over a configurable window. It distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on aggregate popularity metrics rather than answering questions or general discovery.

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

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

Three explicit use cases are provided (discovering hot data sources, confirming canonical choice, aligning use case). While it doesn't explicitly state when not to use, the use cases give clear context for appropriate invocation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds extensive behavioral detail: scanning logic, semantic anchor (Jaccard similarity ≥0.30), partition filter, fill check against live CLOB depth, and response structure with conditional components.

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 long but well-structured with clear sections (summary, modes, semantic anchor, partition filter, response, fill check). It front-loads key information. While verbose, each sentence adds necessary context for an arbitrage tool with complex logic.

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

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

Despite no output schema, the description fully explains the response format (opportunities array with fields, partition_check object in event mode, fill check output). It covers all necessary details for correct invocation and interpretation, given tool complexity.

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

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

Both parameters (event, topic) have schema descriptions, but the tool description adds significant meaning: event accepts slug or full URL; topic is a seed question that triggers cross-event search with similarity checks and partition filtering, ensuring proper usage.

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

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

Description clearly states the verb 'Find' and resource 'arbitrage opportunities on Polymarket', specifying the method (monotonicity violations + partition-sum checks). It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection with two distinct modes (event, topic).

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

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

Explicitly states when to call with no args (trending_scan), pass `event` for per-event partition_check, or `topic` for cross-event scan. Provides guidance on post-processing (fill_check) and 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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description reinforces these with details on caching (1h at KV level), non-destructive scanning, and open-world outputs. It adds granular behavior like edge calculation, slippage subtraction, segment breakdowns, and diagnostic feedback, far exceeding annotation coverage.

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 overly verbose, containing extensive technical details on model families, Kelly formulas, and caching internals. While informative, it lacks conciseness and could be streamlined. The front-loading of purpose is good, but the density of jargon reduces quick comprehension.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment segments, diagnostics, Fed bets exclusion) and all relevant edge-case behaviors. It covers why segments might be empty, caching behavior, and knob interactions, making the tool fully understandable for correct invocation.

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

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

Schema coverage is 100% with each parameter having a clear description. The description does not add significant new meaning to parameters beyond what the schema provides, though it contextualizes their use in the edge-finding pipeline. Baseline 3 is appropriate as the schema already handles parameter semantics adequately.

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 and returns opportunities where Pipeworx data disagrees with market price. It specifies a concrete action and resource, and the detailed model breakdown makes its purpose distinct from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 opens with 'Built for "what should I bet on today"', providing direct usage context. It explains that the tool discovers opportunities without paging and includes tradeable-edge knobs. While it doesn't explicitly list when NOT to use or name alternatives, the context is clear enough for selection among siblings.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds valuable behavioral context: data sources (snapshots), decay details, limitations (TTL, gaps), and response structure. No contradiction with annotations.

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

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

Description is well-structured, front-loaded with purpose, then response details. Every sentence adds value, though slightly verbose. Could be tightened slightly but still 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?

No output schema exists, so description fully compensates by detailing the response objects (tracked, expired, snapshot_dates) and their fields. Limitations are also covered. Complete for a tool of this complexity.

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

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

Schema coverage is 100%, so description doesn't need to add much for parameters. It restates defaults and max (with minor difference from schema clamp) but doesn't add new semantics beyond 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?

Description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answers a specific question, and distinguishes between fresh and old edges. It also lists response fields, making purpose very clear and distinct from 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?

Explains when to use (to check edge persistence and decay) with a trade example. Mentions limitations like history depth and decay computation. Lacks explicit when-not-to-use or alternative tools, but context is strong.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is clear. The description adds valuable behavioral context: it walks the order book ladder, returns fill quality metrics, and warns about incomplete fills and directional risk. However, the description could be more concise in listing return fields.

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

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

The description is fairly long but well-structured with labeled sections (REQUIRES, SINGLE-MARKET, BASKET). Every sentence adds value, though some repetition could be trimmed (e.g., repeating return fields in both modes). It is front-loaded with the core requirement (market or event) and then expands.

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

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

Given the tool's complexity (two modes, multiple return fields, usage advice) and the absence of an output schema, the description is remarkably complete. It details all return fields for both modes, explains the meaning of verdict, thin_legs, and forced_directional_risk, and provides real-world context about losses. No gaps identified.

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

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

Input schema has 100% coverage, so baseline is 3. The description adds meaning beyond schema: it explains the dual mode (market vs event), default side logic, and how size_usd is interpreted differently for buys vs sells and basket vs single-market. This extra context helps the agent understand parameter behavior 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?

The description clearly identifies the tool as a risk check for Polymarket fills, distinguishing between single-market and basket modes. It specifies exactly what returns are provided (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, which it advises using before acting on their signals.

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

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, idempotent. The description adds extensive behavioral context: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped_cross counters), and warnings about mismatches. 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 dense but well-structured with clear sections. Every sentence adds value, though it could be slightly more concise. Front-loads 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?

Covers most aspects: modes, output fields, safety warnings. However, does not specify default behavior when no parameters are provided (all optional but two modes). Missing output schema but compensated by description of key fields.

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

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

Schema coverage 100%, and description adds substantial meaning: lists all 10 topic shortcuts, provides examples for explicit parameters, and explains override behavior. This goes well beyond the schema.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket. It specifies two modes and explains the response content. Although it does not explicitly differentiate from siblings, the purpose is very 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 explains when to use the tool (comparing prices across venues) and provides context on when output is meaningful via safety fields. It warns about limitations (rare tradeable spreads) but does not explicitly mention alternative tools for single-venue analysis.

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, and the description reinforces this by specifying 'Retrieve' and 'list all saved keys'. It adds behavioral details like scoping to identifier and the ability to list keys, which align with annotations. No contradiction.

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

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

The description is composed of three concise sentences. The first sentence states the primary purpose and behavior, the second provides usage context with examples, and the third covers scoping and related tools. 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 nature of the tool, the description covers all necessary aspects: retrieval behavior, listing behavior, scoping, and pairing with related tools. The annotations and input schema are rich, so the description is sufficiently complete.

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

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

Schema coverage is 100% with only one optional parameter. The description adds meaning beyond the schema by explaining the effect of omitting the key (list all keys) and providing examples of what the key could represent (e.g., user_research_topic). This adds valuable context.

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

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

The description uses a specific verb 'Retrieve' and identifies the resource as 'a value previously saved via remember' or 'all saved keys' when omitting the key argument. It clearly distinguishes from sibling tools like 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?

The description explicitly states when to use the tool: to look up context stored earlier (e.g., user's target ticker, address, research notes) without re-deriving. It also hints at alternatives by mentioning pairing with remember (to save) and forget (to delete), providing clear context for usage.

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 behavior of mark_read parameter, return fields (source, citation_uri, payload), and that it returns most recent alerts. Annotations already indicate read-only, idempotent, non-destructive, and description adds 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 sentences, each concise and valuable: purpose, fields, filtering/mark_read, and alternative endpoint. 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?

Covers return fields, parameters, usage patterns, and alternative access. No output schema, but description sufficiently describes return structure. All required information for agent to invoke correctly is present.

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

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

Adds meaningful context to all parameters beyond schema: examples for type (sec_8k), ISO timestamp for since, explanation of mark_read effect, and unread_only implication. Schema coverage is 100% but description enriches understanding.

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

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

Description clearly states verb 'Pull', resource 'fired events from your subscription feed', and specifies returned fields. Distinguishes from siblings like list_subscriptions and recent_changes by focusing on alert events.

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

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

Explicitly mentions polling works fine and provides an alternative REST endpoint for scripts/dashboards. However, does not explicitly state when not to use or compare to sibling tools.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds rich behavioral details: fan-out to multiple sources, fallback behavior (GDELT→GNews), soft-fail for USPTO, and return structure (grouped changes with URIs). No contradiction.

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

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

The description is front-loaded with query examples and is well-organized, but it is slightly long. Every sentence adds value, but could be tightened. Still above average.

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

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

Given the absence of an output schema, the description compensates by detailing return structure (grouped changes, total count, with URIs). It also explains fallback and error handling. Sufficient for an agent to use correctly, though a max limit on changes might be useful.

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 value by explaining relative date shorthand for 'since', clarifying that 'value' can be a ticker or CIK, and noting that 'type' only supports 'company'. These extras justify 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?

The description clearly states the tool's purpose: a change feed for a company within a specified window, fanning out to multiple sources. It uses specific verbs like 'fans out' and provides example queries. It explicitly distinguishes from sibling tool 'entity_profile' by suggesting that tool for static profiles.

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

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

The description provides explicit usage guidance, including example queries, accepted parameter formats (e.g., '7d', '30d'), and a fallback mechanism. It also tells when to use a different tool ('Use entity_profile instead'), offering clear context 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 provide idempotentHint=true and destructiveHint=false. Description adds scope by identifier, persistence for authenticated users, 24-hour retention for anonymous, which goes beyond annotations.

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

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

Single well-structured paragraph, front-loaded with main purpose. 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 no output schema, the description sufficiently explains behavior, persistence, and pairing with recall/forget, providing complete context 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 covers 100% with descriptions. Description adds helpful examples for key and value types (e.g., subject_property, target_ticker), adding value beyond schema.

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

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

The description clearly states the tool saves data for reuse across conversations or sessions, with specific examples (ticker, address, preference). It distinguishes itself from siblings 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 discovering something worth carrying forward. Pairs with recall and forget, providing clear usage context.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, but the description adds critical non-obvious behaviors: identifiers are labeled with their source, unresolved identifiers are listed under 'unresolved' rather than omitted, and enrichment 'degrades gracefully' when GLEIF/OpenFIGI is unavailable (EDGAR IDs still return). These details significantly enhance transparency 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 longer than average but well-organized: it opens with natural-language example queries, then a directive, then structured 'SUPPORTED TYPES' with detailed descriptions. Every sentence contributes information about sources, outputs, or failure handling. While not maximal conciseness, the density is justified by 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?

With no output schema, the description carries the full burden of explaining expected returns—and it succeeds. It names all key output fields (CIK, ticker, LEI, FIGI, RxCUI, ingredient, brand), mentions ownership data, and covers edge cases (unresolved identifiers, degraded enrichment). This provides a complete mental model for the agent.

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

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

Schema coverage is 100%, but the description adds substantial meaning: it explains that 'company' accepts ticker, CIK, or name; gives example values ('AAPL', '0000320193', 'ozempic'); and describes what each type returns (cross-source identity spine for companies, RxCUI for drugs). This exceeds the schema's minimal descriptions and helps the agent choose and format parameters correctly.

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

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

The description clearly states the tool's primary function: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete examples ('What's the ticker for…') and enumerates supported types (company, drug) with specific outputs (CIK, ticker, LEI, FIGI, RxCUI). This establishes a distinct verb+resource+scope, differentiating it from sibling tools that consume such identifiers.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID' and notes that it 'replaces 2-3 manual lookups,' providing clear context for when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use it (e.g., when an ID is already known), so it lacks full when-not/alternative specificity.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with metrics. No contradictions; sufficiently transparent.

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

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

Two concise sentences front-load the purpose, followed by a brief use-case example. No extraneous words; every sentence earns its place.

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

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

Given no output schema, the description adequately explains return structure (ranked list with score, confidence, signal density). Parameters fully documented in schema. Suitable for the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add significant new meaning beyond the schema; it repeats the subject treatment from schema. Minimal added value.

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

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

Description states exactly what the tool does: compare AI visibility across multiple entities using ai_visibility_check, rank results, and highlight leaders/laggards. It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (different comparison).

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

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

Explicitly states the use case for competitive AI-marketing audits with an example question. While it doesn't explicitly list when not to use or mention alternatives, the context provided is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint and non-destructive nature. The description adds behavioral details like partial failures, timeouts (5-30s), and sources_failed field. 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 information-dense. It is front-loaded with the key purpose. Could be slightly more concise, but the length is justified by the composite nature.

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

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

No output schema, but the description lists return fields and explains partial failures. Covers essentials for an agent to use the tool correctly.

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

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

Schema coverage is 100%. The description adds meaning: explains scoped packages for 'package' and default 'latest' for 'version'. Provides 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 it is a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying the npm ecosystem and mentioning alternative uses for other ecosystems.

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: 'Use whenever an agent asks 'is X safe / popular / small''. Also mentions when not to use (other ecosystems) and gives alternatives (deps.dev:version directly).

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

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

Annotations already indicate it is read-only and idempotent. The description adds behavioral context by specifying the Lucene query syntax support and the article source (peer-reviewed open-access), which goes beyond the annotations.

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

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

The description is two sentences, each serving a distinct purpose: stating the tool's function and specifying query syntax. It is front-loaded with the core purpose and contains no redundant information.

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

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

Given the presence of an output schema and comprehensive annotations, the description adequately covers the tool's purpose and query capabilities. It could be improved by mentioning result limitations or pagination behavior, but these are covered by the schema.

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

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

With 100% schema coverage, the schema already describes each parameter. The description adds value by providing concrete examples of Lucene-style queries ('title:climate', 'abstract:"machine learning"'), enhancing understanding of the 'query' parameter beyond its schema description.

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

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

The description clearly identifies the tool as searching peer-reviewed open-access articles, with explicit support for Lucene-style field queries. This verb+resource combination is specific and distinguishes it from sibling tools like search_journals or deep_research.

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

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

The description states what the tool does but provides no guidance on when to use it versus sibling tools (e.g., deep_research, search_journals). There is no mention of appropriate contexts or exclusions.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds value by explaining the 'curated index of vetted, peer-reviewed' nature and the return fields. No contradiction, and it enriches the behavioral context beyond the annotation flags.

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, no fluff, front-loaded with the tool's identity (DOAJ) and purpose. Every sentence carries useful information: the index type, search syntax, returned fields, and the questions it answers.

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 a complete schema, output schema present, and annotations, the description covers the core functionality and expected results. It explains what is returned and what use cases it supports, making it sufficiently complete for an agent to invoke correctly.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds the crucial note that queries can be free-text or Lucene-style, which enriches the query parameter semantics beyond the schema. This justifies a slight premium over the baseline 3.

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

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

The description clearly states the tool searches the DOAJ curated index of open-access journals, distinguishing it from siblings like search_articles or get_journal. It specifies the resource (journals) and the action (search), plus the exact kind of data returned.

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 what questions the tool answers (which journals publish in a field, who publishes them, charges), giving clear usage context. It doesn't explicitly name alternatives or exclusions, but the context is sufficient for an agent to decide when to use it.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. Description adds significant behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation flag. No contradiction with annotations.

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

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

Description is a focused 6-sentence paragraph. Front-loads core purpose: 'Semantic search INSIDE a fetched record.' Each sentence adds value with no redundancy. Efficiently covers key aspects.

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

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

Given no output schema, description fully explains return values (passages, character offsets, similarity scores). Covers constraints (200K chars, truncation), embedding details, and relationship to sibling tool. Complete for a tool of moderate complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds usage context (e.g., 'Pass the text you already pulled') but does not provide new technical detail beyond what schema already states for each parameter. Marginally adds value.

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

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

Title 'Search Within a Source' and description clearly state it performs semantic search inside a fetched record. It specifies inputs (text, query) and outputs (top-N passages with offsets and similarity scores). Distinguishes from siblings by pairing with ask_pipeworx_grounded. Specific verb+resource.

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt.' Describes it saves context and returns relevant passages. Mentions pairing with ask_pipeworx_grounded as an alternative workflow. Lacks explicit 'when not to use' 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 annotations (e.g., idempotentHint=true), the description discloses behavioral traits: subscription persistence requires OAuth, SMS cap, webhook auto-disable after 10 failures, single-return-signing-secret. 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: purpose first, then types, then delivery details. Every sentence adds value, though it could be slightly more concise by grouping examples. No fluff.

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

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

Given the tool's complexity (5 subscription types, 3 delivery channels, varied constraints), the description covers all critical aspects: type-specific parameters, delivery options with limits, authentication requirements, and webhook signing details. No gaps identified.

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 with concrete examples (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE') and constraints (e.g., delivery.webhook host restrictions, secret return-once). This goes beyond schema basics.

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' and returns the subscription ID. It lists supported event types and delivery channels, distinguishing it clearly from sibling tools like list_subscriptions or recent_alerts.

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

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

The description provides strong usage context: requires a Pipeworx OAuth account, explains type-specific parameters, delivery channel constraints (e.g., SMS must be verified, 10/day cap), and webhook auto-disable. It lacks explicit when-not-to-use guidance but implicitly covers alternatives through sibling tool names.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: the tool returns example questions drawn from a live catalog, with the exact tool and argument shape, and that calling without arguments gives a full spread while passing a topic focuses the results. This goes beyond what annotations provide.

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

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

The description is concise and front-loaded with the purpose. Every sentence adds value: the first sentence states the tool's function and use cases, the second describes the output, and the third gives usage instructions. No redundant or 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 complexity of the tool (returning example questions with tool shapes) and the richness of sibling tools, the description is complete. It explains the output structure, how to call it, and when to use it. The output schema is missing, but the description sufficiently describes the return value. Annotations cover behavioral aspects. Minor room for improvement: could mention that the examples are live and not static.

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 describes the 'topic' parameter. The description adds meaning by listing example values (finance, pharma, etc.) and explaining the effect of omitting it (cross-category spread), which helps an agent understand how to use the parameter correctly.

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

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

The description clearly states the tool returns category-bucketed example questions to help users understand what Pipeworx can do. It specifies the verb 'returns' and identifies it as the onboarding entry point, distinguishing it from sibling tools like 'ask_pipeworx' or '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?

The description explicitly advises to use this tool first when the user does not yet know what Pipeworx can do, or to learn how to call meta-tools. It also describes how to use the optional 'topic' parameter. However, it does not explicitly state when not to use it or list alternatives, but the guidance is clear for its intended purpose.

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

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

Annotations provide idempotentHint=true and destructiveHint=false. The description adds crucial context: the row is deactivated (not deleted), historical events persist via recent_alerts, and ownership is enforced. 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?

Two sentences, no filler. First sentence states core action, second adds essential constraints. 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?

For a simple one-parameter tool with no output schema, the description covers the purpose, constraints, and side effects (soft delete, impact on historical data). It references related tool 'recent_alerts' for continuity.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description does not add additional meaning to the parameter itself beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id' using a specific verb and resource. It distinguishes from sibling tools like 'subscribe' (create) and 'list_subscriptions' by focusing on cancellation and soft deactivation.

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: to cancel one's own subscription. It mentions ownership enforcement and that historical events remain available, but does not explicitly state when not to use or name alternatives. Given sibling context, it's sufficiently 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?

The description adds substantial behavioral context beyond the annotations. Annotations only declare readOnly/openWorld/idempotent/non-destructive. The description discloses the return verdicts, the two routing paths, the meaning of could_not_verify (including verification_error details) versus unsupported, and the 'must not be shown as evidence' caveat. This is rich, decision-relevant transparency.

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

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

The description is long but front-loaded with the core purpose and includes valuable examples, routing details, and error semantics. Every section earns its place for a tool with this complexity. It is not overly verbose or redundant, though a slightly tighter structure could improve scannability.

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

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

With no output schema, the description thoroughly explains return values (verdicts, actual value, citation, reasoning), error semantics (could_not_verify, unsupported), and usage scenarios. It also covers the two major claim classes. For a tool of this complexity, the description provides complete guidance 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 description coverage is 100%, so the schema fully documents both parameters including tolerance semantics. The description itself does not add further parameter-level detail beyond the schema (e.g., it mentions 'exact percent-delta math' but not specifically for tolerance). Baseline 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 a specific verb and resource: 'natural-language claim verification against authoritative sources'. It also includes trigger phrases and explicitly differentiates itself from generic fact-checking by describing two distinct pipelines (SEC EDGAR fast path vs grounded pipeline) and by noting it replaces 4-6 sequential calls. This distinguishes it from sibling tools like ask_pipeworx or deep_research.

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

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

The description provides an explicit 'when to use' statement: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives nuanced guidance on interpreting results (could_not_verify vs unsupported). However, it does not name alternative tools or state when NOT to use this tool in favor of a sibling, so it falls short of the highest bar.

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