Dwds

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds key behavioral details: default model is free, Anthropic requires BYO key (direct payment), and returns per-model results plus a combined view. 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 plus a list of use cases) and front-loaded with the main action. It efficiently communicates essential information without clutter, though could be slightly tighter.

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

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

Given no output schema, the description adequately explains the return format (per-model object with score, confidence, signals, raw_response) and the combined view. With 100% schema coverage on parameters and clear usage guidance, the description is fully complete for correct tool 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?

All parameters have schema descriptions (100% coverage), but the description adds value by explaining the relationship between 'models' and '_apiKey' (only needed if Anthropic is in models), and clarifies the purpose of 'context' for disambiguation. Schema alone is good, but description enhances understanding.

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

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

The description clearly states the tool probes LLMs for visibility and scores it (0-100). It specifies the verb 'probe' and resource 'business/brand/product/topic', and distinguishes itself from siblings by focusing on AI visibility audits rather than general Q&A or research.

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

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

The description explicitly states when to use the default model (free Workers AI) and when to provide an API key for Anthropic. It mentions use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', providing clear context without explicitly excluding alternatives.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: it routes across many sources, fills arguments, returns stable citation URIs, works on every tier, and handles breaking news routing. 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 longer than typical but front-loaded with the key preference instruction and a compact list of covered domains. Every sentence adds decision-relevant detail, 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?

Without an output schema, the description still tells the agent what to expect (structured answer with citation URIs), how to escalate to alternatives, and provides diverse examples. For a tool with 6 parameters and a large routing responsibility, this description is remarkably complete.

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

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

Schema coverage is 100% and clearly describes 'question' plus five aliases. The description goes beyond schema by providing semantic examples ('current US unemployment rate', 'Apple's latest 10-K') and noting that questions can be phrased as 'what is', 'look up', 'find', etc., which helps the agent formulate queries.

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 role: routing questions to the right data source among 5,529 tools and returning structured answers with pipeworx:// citations. It uses specific verbs like 'routes', 'fills arguments', and 'returns', and explicitly distinguishes itself from ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance, instructing to prefer this over web search, calling it the 'default entry point', and providing escalation criteria for ask_pipeworx_grounded (hallucination-resistant single answers) and deep_research (broad/multi-part questions). Concrete examples further clarify 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?

The description discloses important behavior beyond the annotations: it is a beta version with 'candidate routing improvements enabled live whenever one is under test,' and currently no candidate is active, so it matches ask_pipeworx exactly. It also warns that results are compared against the stable router, indicating potential nondeterminism. This adds meaningful context without contradicting the provided readOnlyHint, openWorldHint, idempotentHint, and destructiveHint annotations.

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

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

The description is three sentences long, each serving a distinct purpose: defining the tool, clarifying its current state, and providing usage guidance. It is front-loaded with the core definition and contains no filler or redundancy, making it highly efficient.

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

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

The description is reasonably complete considering the tool's simplicity (one required string parameter) and the presence of robust annotations. It explains the tool's purpose, usage, and experimental behavior. The absence of an output schema is partially addressed by referencing 'same response shape' as ask_pipeworx, but it does not describe the response format in detail. For a router of this scope, the description covers essential context without major gaps.

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

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

The input schema has 100% coverage with descriptions for all six parameters, including the 'question' field and its five aliases. The description adds no additional parameter information beyond noting 'same arguments' as ask_pipeworx, so it does not enhance or clarify parameter semantics beyond what the schema already provides. Given full schema coverage, the 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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It explicitly states 'this IS a full working router, just the experimental edge,' leaving no ambiguity about its function. It also differentiates itself from the stable ask_pipeworx sibling by noting it is the experimental version with candidate routing improvements.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It names the alternative tool (ask_pipeworx) and gives a clear context for selection. However, it does not explicitly state when NOT to use it, such as in production or when stable behavior is required, so it falls short of a 5.

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

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

Despite annotations already indicating readOnly, openWorld, idempotent, and non-destructive, the description adds substantial behavioral detail: it only extracts from tool output, returns an explicit refusal with specific reasons, and costs an extra LLM call. This goes well beyond annotations and is critical for high-stakes use.

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

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

The description is dense but well-organized: purpose, behavior, return format, usage guidance, and trade-off are all included in a compact paragraph. It's long but every sentence adds value; slightly more structural separation could improve scannability, but it's far from 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 tool's complexity (routing over 5,529 tools, extraction, refusal cases) and lack of an output schema, the description provides comprehensive details on return values (answer, evidence, confidence, source, refusal reasons) and use cases. It is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% and the parameters are all aliases for the same natural-language 'question' field. The description doesn't add parameter-specific semantics beyond saying the question is routed to tools, but that's minimal. Since schema already documents all parameters, a baseline 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' that extracts answers using only tool results. It distinguishes from ask_pipeworx by explicitly contrasting its behavior ('Same routing as ask_pipeworx' but with extraction and refusal) and naming the sibling in the cost 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?

Provides explicit guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and 'prefer ask_pipeworx for casual lookups.' This clearly states when to use and when to avoid, naming the alternative tool.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description goes far beyond annotations, detailing resolution, classification, fan-out paths, response shapes, safety blockers, edge cases (e.g., low-confidence, closed markets), and cancellation rules. 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 extremely long and dense, covering many details without clear structure or prioritization. While comprehensive, it lacks conciseness and front-loading, making it harder for an agent to quickly 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 the complexity and lack of output schema, the description is highly complete. It covers input formats, classifiers, fan-out examples, response fields, resolver behavior, parent events, news fields, safety, and cancellation rules, leaving no major gaps.

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

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

Schema covers all 3 parameters with descriptions. The tool description adds value by providing examples, default behavior, and context for the parameters beyond the schema, justifying a score 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 researches Polymarket bets by pulling Pipeworx data in one call. It specifies input types (slug, URL, question text) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on comprehensive 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?

Explicitly states use cases like 'should I bet on X' and 'what does the data say about Y'. Does not explicitly mention when not to use or alternatives, but the extensive detail implies its comprehensive role relative to specialized 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it handles off-calendar fiscal years, returns sorted results, and includes citation URIs. It does not contradict any annotations.

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

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

The description is a single, dense paragraph that front-loads common usage examples. Every sentence adds value, with no fluff or repetition.

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 2 params, no output schema, and rich annotations, the description provides a clear picture of what data is returned and how results are ordered. It could mention resource limits or error handling, but is sufficiently complete for effective use.

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

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

Schema coverage is 100%, and the description enriches both parameters: 'type' is explained with detailed data sources (SEC EDGAR for company, FAERS for drug), and 'values' includes examples and constraints (2–5 items, tickers/CIKs or drug names). This adds significant value beyond the schema.

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

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

The description uses specific verbs like 'compare', 'rank', and 'head to head', and explicitly states it performs side-by-side comparisons of 2–5 companies or drugs in one parallel call. It clearly distinguishes from sibling tools like 'entity_profile' by specifying the multi-entity scope.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. It explains what data is retrieved for each type (company vs. drug), but does not explicitly state when not to use the tool or mention 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?

Discloses that the tool returns a notice rather than actual corpus data, and explains the API removal. Annotations already indicate read-only/idempotent behavior, but the description adds context about the retired status and the fact that the tool does not perform its original function.

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

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

A single sentence that front-loads 'RETIRED' and packs essential information: reason, notice behavior, and alternatives. No filler.

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

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

For a retired tool, the description is fully complete: it explains the status, why it is retired, what it returns, and directs users to concrete alternatives. The existence of an output schema further reduces the need to describe return values.

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 has one parameter 'query' with no description, and the tool description does not explain what the query parameter does or whether it is ignored. With 0% schema coverage in the description, the parameter remains completely undocumented.

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 is retired and returns a notice with alternatives. It names specific alternatives (dwds_frequency, snippet, dwds.de) which distinguishes it from siblings and clarifies its non-functional purpose.

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

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

Explicitly says 'RETIRED' and provides alternative tools and resources: 'use dwds_frequency for how-common data, snippet for dictionary info, or search corpora at dwds.de.' This tells the agent exactly when not to use this tool and what to use instead.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true; the description adds essential behavior beyond that: account/paid-tier requirements, never-invented gaps[], contradictions[] for standard/thorough, fetchable citation_uri only when available, semantic excerpting, and expected latency (15-90s). Nothing in the description contradicts 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?

Every sentence is information-dense and earns its place, but the description is a ~300-word single paragraph with no bullet points or section breaks. It is front-loaded with account requirements and core differentiation, yet the wall-of-text format makes it harder for an agent to scan quickly.

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 and lack of an output schema, the description thoroughly covers prerequisites (account, tier), result packet structure (verbatim evidence, confidence, source, fetched_at, citations), edge behaviors (gaps[], contradictions[], semantic excerpting), and performance expectations. No important context appears missing.

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 already explains both parameters, including the depth enum's exact facet counts and hop behaviors. The description largely restates the schema's param descriptions and adds only peripheral context (latency, paid plan for thorough), so it adds minimal semantic value beyond structured fields.

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

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

The description opens with a crisp statement: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources ... in ONE call' and explicitly differentiates itself from open-web search and from ask_pipeworx. It provides concrete use-cases ('compare X and Y's regulatory + financial exposure') and names the exact result format, making the tool's scope 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 gives explicit exclusions: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also details when to choose each depth level ('standard' re-angles gaps, 'thorough' chases leads), providing clear decision guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly'. 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?

Four sentences, front-loaded with purpose and usage. Every sentence adds value: purpose, domain list, return details, and guidance. No filler.

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

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

Given there is no output schema, the description compensates by explaining the return structure. It covers how to call, what to expect, and when to use. Slightly more detail on aliases could have been included, but overall complete enough for effective use.

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

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

Schema description coverage is 100% with 6 parameters all described. The description does not add extra meaning beyond what the schema already provides (e.g., it mentions 'query' but does not elaborate on aliases or limit behavior). Baseline 3 is appropriate.

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

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

The description clearly states that the tool finds tools by describing a data or task, lists numerous domains, and explains what is returned. It differentiates itself by advising to 'call this FIRST when you have many tools available', which distinguishes it from sibling search/discovery 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?

Explicit guidance on when to use: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools'. Does not explicitly state when not to use or mention alternatives, but the context is clear enough.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it returns absolute hit count and per-million frequency from the DWDS reference corpus, which is useful context. No contradictions or missing behavioral traits.

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

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

The description is extremely concise, with two sentences and a brief example. The most important information (outputs and purpose) is front-loaded. Every word earns its place.

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

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

Given the tool's simplicity and the absence of an output schema, the description fully explains what the tool returns (hit count and per-million frequency). No additional context is necessary for an agent to use it correctly.

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

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

The input schema has 100% coverage with a clear description of the 'query' parameter. The description adds an example and clarifies it accepts a German word or lemma, but this does not provide significant additional 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 that the tool computes how common a German word is, providing absolute hit count and per-million frequency. It also includes example questions and a usage example, making the purpose unambiguous and distinct from siblings like corpus_concordance or kwic.

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

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

The description implicitly tells when to use the tool (to answer frequency questions) but does not explicitly state when not to use it or mention alternatives. However, given the clarity of purpose, it is adequate.

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. The description adds that patents rely on USPTO PatentsView API which soft-fails until May 2025, and explains the parallel fan-out across sources. 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 front-loaded with examples and structured into a list of outputs. It is somewhat long but each sentence adds value. Could be slightly more concise, but overall well-organized.

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

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

No output schema, so description must explain return values. It does so thoroughly, listing CIK, company name, filings with URIs, fundamentals fields, patents, news, LEI. The required parameters and their format are also explained. Covers the tool's complexity well.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: clarifies that 'value' can be ticker or zero-padded CIK (not names), and 'type' is only 'company' currently. This provides useful context for correct 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 provides a full cross-source profile of a US public company in one parallel call, with specific examples like 'Tell me about X' and lists exact return fields. It distinguishes itself from chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and specifies that names are not supported, directing to use resolve_entity first.

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?

Consistent with annotations (destructiveHint=true). Adds context about why to delete (stale, done, sensitive data). However, does not mention idempotency (idempotentHint=true) or error behavior if key not found, which leaves minor gaps.

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 with no waste. Purpose is front-loaded, guidelines follow immediately. Efficient and clear.

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?

Adequately covers purpose and usage context given no output schema. Lacks mention of what happens if key is missing or that deletion is permanent, but annotations compensate for destructive nature.

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

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

Only one parameter with full schema coverage. The description adds no additional meaning beyond the schema's 'Memory key to delete'. Baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Delete', the resource 'memory', and the method 'by key'. It distinguishes itself from siblings like 'remember' and 'recall' by indicating it is the deletion operation.

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 specific contexts for use: stale context, task completion, clearing sensitive data. Implicitly indicates when to use but does not explicitly state when not to use, though the pairing with 'remember' and 'recall' suggests alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This goes beyond annotations without contradiction.

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

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

The description is concise: two short paragraphs, first covering purpose and process, second listing use cases. No superfluous words, front-loaded with essential 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 only two parameters, no output schema, and rich annotations, the description covers key behavioral aspects and output format. It could mention error handling for invalid URLs, but overall it is sufficient for an agent to understand and invoke 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 description coverage is 100%, so baseline is 3. The description adds context about output format and extraction process but does not add semantic meaning beyond what the schema already provides for parameters (url, max_links). No extra parameter-level detail is given.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt'. It also distinguishes itself from siblings by focusing on AI crawler indexing, with explicit use cases for clients, own projects, or competitors.

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: getting a client's site indexed, drafting for own project, or auditing a competitor's AI visibility. However, it does not explicitly mention when not to use or compare to sibling tools like 'scan_competitor_ai_presence', leaving some room for ambiguity.

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

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

With annotations already indicating readOnlyHint=true and idempotentHint=true, the description adds valuable context about the tool's retired status and that it returns a notice rather than performing actual searches. There is no contradiction; the described behavior aligns with the read-only annotation.

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 front-loaded sentence beginning with 'RETIRED,' which immediately signals the tool's status. Every part of the sentence carries essential information: retirement, the reason, the return type, and alternatives. 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?

Despite having an output schema, the description provides all necessary context for a retired tool: the fact that it returns a notice and which alternatives to use. The tool is simple and the description fully covers its behavioral scope, making it complete 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 description coverage is 0%, and the description does not explain the 'query' parameter. It implies the query is irrelevant by stating 'Returns a notice,' but does not explicitly say the parameter is ignored. Given a low coverage baseline, the description should have compensated but did not.

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

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

The description clearly states that the tool is RETIRED and returns a notice about the removal of DWDS's public KWIC API. It distinguishes itself from siblings by explicitly naming alternatives: dwds_frequency, snippet, or dwds.de. This is a specific verb+resource with clear scope.

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 the tool is RETIRED and directs users to use dwds_frequency, snippet, or dwds.de for corpus search. This provides clear when-not-to-use guidance and names alternative tools, going beyond basic 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, safe. Description adds value by listing exact return fields and default behavior (active only, with optional include_inactive). No contradictions.

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

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

Two sentences, front-loaded with purpose, then 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, listing return fields is sufficient. Description provides all necessary behavioral 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 description for include_inactive. Description adds meaning by stating 'active subscriptions' implicitly clarifying the default. Adds slight nuance over schema.

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

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

Clearly states 'List the caller's active subscriptions,' specifies return fields, and differentiates from sibling tools subscribe/unsubscribe by implying it's the read-only listing tool.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear use cases. Does not exclude alternative tools, but context is sufficient.

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

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

Annotations provide no safety hints (all false), so the description carries full transparency burden. It discloses rate limiting (5 per identifier per day), quota behavior (free, doesn't count against tool-call quota), the claim_token workflow for retrieving status updates, and the policy of not pasting end-user prompts. No contradiction with annotations.

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

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

The description is long (~180 words) but every sentence earns its place: purpose, scope boundary, claim_token flow, rate limit, and pragmatic advice ('don't paste the end-user's prompt'). It is front-loaded with the primary purpose and structured logically, with no redundancy or filler.

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

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

Despite having no output schema, the description explains what happens on filing (returns a claim_token when no account) and how to later retrieve 'whether it was fixed and what changed'. Combined with rate limits, scope restrictions, and message guidance, it fully equips an agent to use this tool correctly for all feedback types.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra context beyond the schema: it explains the claim_token round-trip usage with an example call (pipeworx_feedback({claim_token:'pwfb_…'})), and ties the type enum values to specific scenarios. This enriches understanding enough to warrant 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 opens with a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') and immediately distinguishes itself from siblings by limiting usage to Pipeworx-served tools and enumerating feedback categories (bug, feature/data_gap, praise). This clearly differentiates it from the research/query-focused 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?

Explicitly states when to use ('Use when a tool returns wrong/stale data...'), when not to use ('if the tool came from a different MCP server... file it with that server instead'), and provides a disambiguation rule ('Pipeworx tool names are the ones this connection lists'). This is model-quality usage guidance with clear alternatives.

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

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

Annotations already signal read-only, idempotent, and non-destructive behavior. The description adds valuable context: data source (CF analytics-engine), privacy (no PII), caching window (5min-1h), and data structure (pack, tool, count). 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 efficient sentences: first states output and window, second lists use cases, third adds provenance and caching. Every sentence adds value. No wasted text, well front-loaded.

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

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

For a simple read tool with one optional parameter and no output schema, this description covers purpose, usage, behavior, and data details comprehensively. No missing information to confuse 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?

The only parameter (window) has 100% schema coverage and description. The tool description repeats the window options without adding new meaning beyond the schema's enum description. As per guidelines, baseline 3 is appropriate.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' for a window, which is a specific verb+resource combination. It distinguishes itself from sibling tools by focusing on trending data, and is not a tautology.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, checking alignment). It provides context but does not mention when not to use or alternative tools, which would earn a 5.

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

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

The description goes well beyond annotations (readOnlyHint, idempotentHint) by detailing behavioral traits: monotonicity checks, partition-sum checks, semantic similarity filters, partition placeholder filtering, fill check against live CLOB depth. It explains when signals are not actionable. No contradiction with annotations.

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

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

The description is detailed but remains focused and front-loaded with the main purpose. Every sentence adds value, covering modes, filters, and output. Slightly verbose but justified by complexity. Could be structured with bullet points but clear as is.

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

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

Given no output schema, the description fully explains the response structure (opportunities[], partition_check, fill check) and edge cases (low similarity, partition filter, fill check). It also points to polymarket_fill_risk for custom sizing, making it self-contained for agent decision.

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 descriptions are complemented by extensive additional context: examples of event slugs and seed questions, explanations of each mode's purpose, and recommendations. This adds significant meaning beyond the schema, especially given 100% schema description coverage.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It specifies two modes (trending scan, event-specific, cross-event) and distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk. The verb 'Find' and resource 'arbitrage opportunities' are precise.

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

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

The description provides explicit guidance on when to use each argument: 'Call with NO args for a trending_scan... pass event... or topic'. It recommends event mode for specific markets and explains cross-event mode catches patterns single-event misses. Lacks direct comparison to sibling tools but within the tool it 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 substantial behavioral context beyond annotations: cached 1h, response structure (by_segment, fed_candidates, diagnostics), edge net of slippage, Kelly cap, model details, and tradeable-edge filters. 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 lengthy but well-structured with clear sections. It front-loads the purpose and then goes into detail. Every sentence adds value, though some condensation could improve conciseness.

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

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

Without an output schema, the description thoroughly explains the response structure (by_segment, fed_candidates, diagnostics) and covers all relevant aspects: model families, knobs, caching, and why segments might be empty.

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

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

Schema description coverage is 100% (baseline 3). The description adds significant extra meaning, e.g., explaining min_partition_leg_kelly's role vs min_kelly, and providing use cases for slippage_pp. It exceeds baseline.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifying it is built for 'what should I bet on today'. It distinguishes from sibling tools by detailing three model families and segments.

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 clear context on when to use the tool for discovering opportunities, including usage of knobs and diagnostics for empty segments. It implicitly distinguishes from other tools but does not explicitly name alternatives or state when not to use.

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

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

Annotations already declare read-only, idempotent, non-destructive. Description adds useful context: history bounded by 60-day TTL, data comes from cache-miss snapshots, decay computed from daily closes not intraday. 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 front-loaded with the core question, then provides structured response details and limitations. Every sentence adds value, though the technical density might be high. Appropriate length for the tool's complexity.

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

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

Despite no output schema, description thoroughly explains the response structure (tracked, expired, snapshot_dates) with fields and meanings. Limitations are explicitly stated. For a telemetry tool with two optional params, this is complete and covers all necessary context.

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

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

Schema covers both parameters fully (100% coverage). Description restates defaults and ranges but does not add new semantic information beyond what schema provides. The output structure explanation is valuable but not part of 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?

Description clearly states the tool provides edge persistence and decay telemetry, answering 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling tools like polymarket_edges by emphasizing temporal context. The verb is specific and the resource is well-defined.

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

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

Description implicitly specifies when to use (to distinguish fresh vs old edges) but does not explicitly state when not to use or mention alternatives like polymarket_edges. Some guidance is present in the context about daily closes vs intraday, but lacking explicit exclusion criteria.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent. The description adds valuable behavioral details: walks the ladder, returns fill prices, slippage, verdicts, and for baskets: theoretical vs realizable sums, capture ratio, thin legs, directional risk. No contradiction.

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

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

The description is well-organized: opening purpose statement, then mode-specific sections with bullet-like details, and a clear usage guideline. Every sentence adds value without redundancy.

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

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

Despite lacking an output schema, the description thoroughly explains all return values for both modes, warns about risks, and works well with annotations. The tool is fully understandable and usable from the description alone.

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

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

Schema descriptions cover all 4 parameters (100%). The description adds context: explains side default behavior in basket mode, size_usd interpretation differences (spend vs. proceeds vs. settlement notional). This goes beyond what the schema provides.

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

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

The description clearly states it checks realizable vs theoretical edge against live order book depth. It distinguishes two modes (single-market and basket) with specific parameter requirements and return fields. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It warns about risks of partial basket fills converting an arb into an unhedged directional position, providing clear when-to-use context.

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

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

Annotations declare readOnly and idempotent, and the description adds rich behavioral details: two modes, response structure, safety fields (compatibility_warning, temporal_alignment, skipped counters), and edge cases like non-equivalent bet shapes. This far exceeds annotation requirements.

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 detailed and well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is longer than average but every sentence adds value for a complex tool. Minor redundancy could be trimmed, but it remains effective.

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

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

With no output schema, the description fully explains the response structure (leg-by-leg prices, matched spreads, safety fields). It covers all relevant scenarios, edge cases, and limitations, making it complete for an agent to understand behavior.

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

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

Schema coverage is 100% with descriptions for each parameter, and the description adds significant context: the exact list of pre-mapped topics for 'topic', example formats for 'kalshi_event_ticker' and 'polymarket_event_slug', and the interaction between modes. 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 it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools by focusing on arbitrage across two prediction markets, with specific modes and safety warnings.

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 two modes (topic shortcuts or explicit tickers) and warns that real spreads are rare and pre-mapped topics may not be tradeable. It provides clear context but does not explicitly state when to avoid using this tool in favor of alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, with 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 adding essential information without redundancies. Front-loaded with the core action.

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

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

For a tool with one optional parameter and no output schema, the description fully covers purpose, scope, and usage context, complemented by thorough annotations.

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

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

Schema coverage is 100%, and the description adds clear semantics: retrieving a value or listing all keys when omitted, which goes beyond the schema's property description.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when key is omitted. It distinguishes itself 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 gives explicit use cases (look up context stored earlier) and mentions scoping. It could be more explicit about when not to use, but it effectively guides 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=true, idempotentHint=true, etc. The description adds valuable behavioral context: the mark_read flag that affects subsequent calls, the returned fields (source, citation_uri, payload), and that polling is fine. No contradictions.

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

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

The description is a single paragraph of about 5 sentences, front-loaded with the main purpose. It is clear but could be slightly more structured (e.g., bullet points for parameters). However, it is not verbose and each sentence adds value.

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

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

Given no output schema, the description explains return values and behavior (mark_read, polling). It also mentions an alternative endpoint. It lacks details on pagination or error conditions, but overall it is sufficient for a read-only tool with rich annotations.

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

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

Schema coverage is 100%, but the description explains parameter usage beyond the schema: examples for type (e.g., 'sec_8k'), ISO timestamp for since, and the effect of mark_read (flags as read for next calls). This adds clear 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 that the tool pulls fired events from a subscription feed, listing return fields and filtering options. It is well-distinguished from sibling tools like 'subscribe' and 'list_subscriptions' which manage subscriptions rather than fetch 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?

The description indicates when to use the tool (to fetch recent alerts) and provides an alternative access method (GET endpoint for scripts/dashboards). However, it does not explicitly state when not to use it or differentiate from closely related tools like 'list_subscriptions'.

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, destructiveHint. Description adds context: fans out to multiple sources, GDELT preferred over GNews, PatentsView soft-fail, returns structured data with citation URIs. No contradictions.

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

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

Description is front-loaded with example queries, uses concise sentences, and every sentence adds value. Slightly lengthy (~150 words) but efficiently packs necessary detail without 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 no output schema, description adequately explains return structure (changes[] grouped by source, total_changes, pipeworx:// URIs). Missing details like pagination or error handling but sufficient for typical use.

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 provides 100% coverage. Description adds valuable nuance: 'since' examples ('7d', '30d', '3m', '1y') and suggested default '30d', explains 'value' accepts ticker or CIK. Adds meaning beyond schema.

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

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

Description uses specific verbs ('change feed', 'fans out') and resources ('SEC EDGAR, GDELT, GNews, USPTO') and directly distinguishes from sibling 'entity_profile'. Example queries in description immediately clarify use case.

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

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

Explicitly provides when-to-use examples ('what's new with X', 'latest on Y') and when-not-to ('use entity_profile instead for static profile'). Also hints at fallback behavior and soft-fail for USPTO.

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

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

Adds important persistence details (24-hour limit for anonymous, persistent for authenticated) beyond annotations like idempotentHint. No contradictions, but doesn't describe all edge cases (e.g., key conflict behavior).

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

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

Succinct, front-loaded with purpose, then usage, then technical details. No filler or repetition.

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 purpose, usage, persistence, and sibling context. Lacks explicit mention of return value/output, but as a write-only tool without output schema, this is acceptable. No critical gaps.

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

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

Schema covers 100% of parameters with descriptions. The tool description reiterates 'key-value pair' and 'scoped by identifier', adding minimal extra meaning beyond schema examples.

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 and sessions, with specific examples like 'resolved ticker' and 'user preference'. It distinguishes itself from siblings (recall/forget) by explaining it's the write counterpart.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and pairs with recall/forget, but does not provide explicit when-not-to-use scenarios or compare with alternative tools beyond those mentioned.

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, but the description adds substantial behavioral context: it explains graceful degradation when GLEIF/OpenFIGI is unavailable, that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, that each call cascades through internal endpoints, and that identifiers are labelled with their source. No contradiction with annotations.

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

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

The description is a single dense paragraph but front-loaded with realistic user queries and a crisp purpose statement. Every sentence adds value—graceful degradation, source labeling, supported types, and endpoint cascading are all useful. It is longer than the ideal two-sentence description, but the complexity of the tool justifies the extra detail.

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 burden of explaining what results to expect. It does so for both types, mentions the 'unresolved' field, the source labels, and the citation link for drugs. It does not describe the exact JSON structure or error handling, but given the tool's scope, this is adequate and complete for an agent to select and 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 coverage is 100%, so the schema already documents both parameters. However, the description enriches both: it details the 'company' type's cross-source identity spine (CIK, ticker, LEI, FIGI, ownership) and the 'drug' type's RxCUI/ingredient/brand with citations. It also clarifies input formats via examples (AAPL, 0000320193, 'ozempic'). This goes beyond the schema's simple descriptions.

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

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

The description uses a specific verb+resource: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It lists numerous real-world example queries (ticker, CIK, LEI, RxCUI) and explicitly states 'Use FIRST whenever you have a name but need an ID,' which clearly distinguishes it from sibling tools like 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 provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and gives concrete examples of triggering phrases. It also explains that it replaces 2-3 manual lookups. However, it does not mention alternative tools or when not to use it, so it stops short of a full 5.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful behavioral context: how it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, signal density. This supplements the annotations without contradiction.

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

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

Three sentences with high information density: first sentence states core purpose, second explains the process, third provides a concrete use case and output details. No redundant or vague phrasing.

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 partially describes the output format (ranked list with score, confidence, signal density per entity). It covers the input parameters well and gives enough context for an agent to decide to use this tool. A full output schema would make it 5.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds significant value: it explains the ordering of entities ('First entry treated as the 'subject''), clarifies model options (workers-ai default, anthropic requires API key), and describes the context parameter purpose. 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 that the tool compares AI visibility across entities by probing with ai_visibility_check, ranks by score, and surfaces most/least recognized. It includes a concrete use case ('does Claude know about us as well as our competitors?') and distinguishes itself from sibling tools like ai_visibility_check (single probe) and compare_entities (generic comparison).

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

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

The description explicitly says it is 'useful for competitive AI-marketing audits,' providing clear usage context. It implies when to use it (comparing multiple entities) and hints at alternatives by mentioning ai_visibility_check as a building block, but lacks explicit when-not-to-use guidance.

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

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

Discloses that it fans out across deps.dev and bundlephobia, mentions partial failures degrade gracefully, and notes that bundlephobia's first measurement may take 5-30 seconds. This adds significant context beyond the annotations (which already indicate read-only, idempotent, open-world).

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

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

The description is well-structured, starting with the main purpose, then use cases, limitations, and error handling. It is slightly long but every sentence provides value, and it is front-loaded with key capabilities.

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 enumerates the return fields (summary block with is_latest, license, etc., per-advisory detail, links, alternative versions list). It also covers error handling and timing. This provides a complete picture for an agent to use the tool.

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

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

The input schema already covers both parameters (package, version) with descriptions. The description does not add additional parameter semantics beyond what is in the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: a composite check for npm packages, aggregating license, security, size, and tree-shaking info. It specifies the verb 'scan' and resource 'npm package', and distinguishes from other ecosystems by noting that PyPI/Maven/Cargo/Go fall under a different endpoint.

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: whenever an agent asks about safety, popularity, size, or cost of adding a package. Also clarifies that it is NPM only in v1 and directs to deps.dev for other ecosystems, providing a clear exclusion.

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 beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and every passage includes offset for verification.

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 tightly packed sentences: core purpose, usage context, pairing guidance, and technical details. Every sentence adds distinct 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?

Covers algorithm, limitations, output features (offsets, scores), pairing, and truncation behavior. No output schema, but description sufficiently explains return content.

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

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

Schema has 100% coverage with descriptions, but the description adds extra context: default and range (1-20) for limit, example queries, and hints at return format (passages with offsets and scores).

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 semantic search inside a fetched record, using examples like SEC 10-K or articles, and distinguishes it from siblings like ask_pipeworx_grounded by specifying pairing usage.

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 record is too large for prompt) and when not to (saves context), and mentions pairing with ask_pipeworx_grounded for grounding over passages, differentiating from that 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 read-only and idempotent behavior. The description adds value by specifying the return content (part of speech, lemma, link), providing behavioral context beyond what annotations offer. No contradictions.

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

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

The description is a single sentence plus an example—concise, front-loaded, with no extraneous information. Every word serves a 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?

Given the tool's simplicity, annotations, and output schema, the description fully covers the needed context. It explains the purpose, example usage, and what the return includes.

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 for 'query'. The description provides an example ('Haus'), adding slight value beyond the schema, but does not significantly enhance parameter 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 the tool provides a 'Dictionary entry summary for a German word from DWDS.de' with specific components (part of speech, lemma, link). This distinguishes it from sibling tools like 'dwds_frequency' or 'corpus_concordance'.

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

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

The description implies usage for getting a quick summary and provides an example, but lacks explicit guidance on when to use versus alternatives or when not to use. No direct comparison with 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 (`readOnlyHint: false`, `destructiveHint: false`) are consistent with the described mutation behavior. The description adds extensive behavioral details: returns subscription ID, auth requirements, SMS daily cap, phone verification requirement, webhook HMAC signing, and auto-disabling after failures. This far exceeds what annotations provide.

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

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

The description is packed with information in a single paragraph, front-loading the core purpose. However, it could benefit from bullet points or section breaks for easier scanning. Every sentence adds value, but readability is slightly reduced due to density.

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 states the return value ('subscription id') and covers all key behaviors: auth, type-specific params, delivery channel details, limits, and failure handling. For a complex tool with multiple types and delivery options, this is comprehensive.

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 rich semantic context: examples for each subscription type (`sec_8k` with items codes, `polymarket_edge` with topics), delivery channel constraints (phone verification, daily cap, webhook signing), and explicit parameter patterns. This significantly aids parameter selection beyond schema definitions.

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

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

The description clearly states the tool's verb ('Create') and resource ('proactive monitoring subscription'), and distinguishes it from sibling tools like `list_subscriptions` and `unsubscribe`. It specifies the types of subscriptions and delivery channels, leaving no ambiguity about what the tool does.

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 context by stating 'Requires a Pipeworx OAuth account' and explains when to use each subscription type. It also mentions the always-on feed alternative ('pull via recent_alerts'), though it does not explicitly list when-not-to-use or contrast with all alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations, such as that it returns example questions from a live catalog and the tool+argument shapes. 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 somewhat lengthy but front-loads common queries and clearly explains purpose, usage, and output. Every sentence adds value, though it could be slightly more compressed.

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

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

Given one optional parameter and no output schema, the description is complete enough for an AI agent. It explains the return format (category-bucketed example questions with tool/argument shapes) and when to call it.

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

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

Schema coverage is 100% for the single optional topic parameter. The description adds meaning beyond the schema by listing the exact focus values (finance, pharma, etc.) and explaining the effect of omitting topic versus providing one.

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

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

The description clearly states the tool's purpose: it's an onboarding entry point that returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings like ask_pipeworx or compare_entities by explicitly mentioning it's for discovering what the agent can do.

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

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

The description explicitly says to use this 'FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also provides context on alternatives by listing the tools it helps learn about.

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, description reveals that the row is deactivated, not deleted, and historical events remain accessible via recent_alerts. 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?

Two sentences, front-loaded with purpose, no superfluous information.

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

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

For a simple cancel tool with one parameter, the description fully explains the effect and side effects. No output schema needed given the 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 a single parameter described as 'Subscription id (uuid) returned by subscribe.' The description adds no further 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 'Cancel a subscription by id', using a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement, indicating when to use (own subscriptions) and when not. Does not provide alternative tools 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, the description discloses critical behavior: could_not_verify means the check did not happen and carries verification_error{stage,detail}, and unsupported means no source was found. It warns against treating could_not_verify as evidence, which is essential for correct agent use. The readOnlyHint, openWorldHint, and idempotentHint annotations are fully consistent with the description.

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

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

The description is long but well-structured: it opens with natural-language examples, states the use case, explains the two execution paths, summarizes the return value, and provides important caveats. While it could be slightly trimmed, each sentence contributes necessary context for a complex tool.

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

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

Since there is no output schema, the description fully explains the return envelope: verdict types, actual value with pipeworx:// citation, and reasoning. It also addresses failure modes (could_not_verify vs unsupported), which is crucial for interpreting results. The description leaves no major knowledge gaps for an agent deciding whether and how to invoke the tool.

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

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

Schema coverage is 100% for both parameters, and the description adds no additional meaning beyond what the schema already provides. The examples for 'claim' and the tolerance guidance for 'tolerance_pct' are embedded in the schema descriptions, so the tool description does not compensate further.

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 natural-language claim verification against authoritative sources, with concrete query examples and a verdict taxonomy. It distinguishes itself from sibling tools by focusing on fact-checking with a structured vs grounded pipeline, rather than general research or search.

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 it: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates between company-financial claims and other factual claims, and explains the two execution paths. It does not name alternative tools for other kinds of requests, but the context is clear enough.

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