Ooni

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: the free default model, BYO key for Anthropic with direct payment, and the return structure (per-model score, confidence, signals, raw_response). 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 tightly written with no wasted words. It front-loads the core action, then adds necessary details about models and returns, finishing with use cases. Every sentence contributes value.

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

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

Despite lacking an output schema, the description fully explains the return format. It covers all parameters, conditional requirements, and use cases. The tool's moderate complexity is well-addressed for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description goes beyond schema by explaining the default model for 'models', conditional use of '_apiKey', and how 'context' disambiguates entities. This adds meaningful guidance.

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 knowledge about an entity and scores visibility (0-100). It includes specific examples of entities and use cases (AI-marketing audits, pre-launch brand checks), distinguishing it from sibling tools like ask_pipeworx or deep_research.

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

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

The description provides clear contexts for use (brand audits, competitive monitoring) and explains when to use the optional _apiKey for Anthropic probing. However, it does not explicitly state when not to use the tool or compare it to alternatives like deep_research.

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 operational context: it routes to 4,991 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs. No contradictions found.

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

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

The description is well-structured with clear front-loading of key guidance and examples. At about 200 words, it is slightly verbose but every sentence serves a purpose. Could be tightened slightly, but the organization is excellent.

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 no output schema, the description adequately covers purpose, usage guidelines, behavioral traits, and output format (structured answer with citation URIs). It includes examples and sibling context. A small gap is lack of explicit mention of error handling or limits.

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 description adds minimal value beyond what the schema provides. It does list example questions and mentions that the question parameter accepts natural language with aliases, but this is already detailed in the schema. 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 router to authoritative structured data sources with citations, using specific verbs like 'routes the question' and 'returns the structured answer'. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explaining what they do differently.

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 this tool ('PREFER OVER WEB SEARCH', 'START HERE for most questions') and when to use alternatives ('Step up only when needed...'). Includes concrete examples and scenario-based 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 indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable behavioral context: source-preference ranking when a source is named, and that it 'falls back to nothing' (full working router). No contradictions.

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

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

The description is concise and front-loaded with the key message (beta, identical router). It includes specific details about routing improvement without unnecessary fluff. Could be slightly more structured but is 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?

Given the complexity (router to 4,991 tools) and no output schema, the description provides adequate context: what it does, how it differs, and usage direction. Could be improved by describing the response shape or example use cases, but sufficient for a beta tool.

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

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

Schema coverage is 100%, so baseline is 3. The description mentions it accepts 'same arguments' as ask_pipeworx but does not add specific parameter details beyond what the schema provides. Minimal additional value for parameters.

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 explicitly states it is a 'Beta version of ask_pipeworx: identical universal router' with specific routing improvements. It clearly distinguishes itself from sibling tools like ask_pipeworx (stable) and ask_pipeworx_grounded.

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

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

It directs users to 'Use it exactly like ask_pipeworx when you want the newest routing' and mentions that results are compared against the stable router. This provides explicit when-to-use guidance and context about the experimental nature.

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, covering safety and idempotency. The description adds behavioral detail beyond annotations: it explains the routing mechanism ('picks the right tool from 4,991 across 1314 sources, fills arguments, fetches the data') and the exact extraction logic, including potential refusal reasons ('not_in_source', 'no_tool_match', etc.). This enriches the agent's understanding of how the tool behaves at runtime.

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

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

The description is dense but well-structured: it opens with the key benefit ('hallucination-resistant'), explains the mechanism, lists output structure, specifies use cases, and ends with a trade-off. Every sentence provides necessary information without redundancy. The length is justified by the complexity of the 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?

Given the tool's complexity (grounded answering with refusal reasons, many sibling tools, no output schema), the description is remarkably complete. It covers purpose, usage guidance, behavioral details, output shape (including exemplary refusal reasons), and relationship to sibling tool 'ask_pipeworx'. The explicit output format description compensates for the lack of an output schema.

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

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

Schema coverage is 100% with all parameters described as aliases for 'question'. The description does not add further parameter semantics beyond restating that the question is in natural language. Since the schema already provides clear descriptions (including listing aliases), the description adds no significant value here. Baseline 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 is a 'hallucination-resistant answer mode for high-stakes reads'. It distinguishes itself from the sibling 'ask_pipeworx' by emphasizing that it extracts answers only from tool results and returns explicit refusals when data is insufficient. Examples of use cases (financial verdicts, legal claims) further clarify its 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?

The description explicitly advises when to use this tool: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts'. It also provides a strong exclusionary guideline by recommending to 'prefer ask_pipeworx for casual lookups'. Additionally, it mentions the cost trade-off of 'one extra LLM call', giving the agent a clear basis for selection among siblings.

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

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

The description fully discloses behavioral traits: market resolution, classification, fan-out to data sources, response shapes, resolver contract (match confidence and alternatives), parent event extractor, news fields with fallback handling, safety mechanisms (low-confidence short-circuits, closed market blocking), wide-spread warnings, and resolution-rule risk. Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description adds rich context 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 long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the core purpose. Every sentence adds value given the tool's complexity, but it could be slightly more concise without losing essential details.

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

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

Despite no output schema, the description thoroughly documents all response fields (result.market, result.analysis, result.evidence, resolver contract fields, parent_event, news fields, safety signals, resolution rules). This covers all relevant aspects for an agent to interpret results correctly, making it highly 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%, but the description adds significant meaning: the market parameter can be a slug, URL, or question text; depth is explained with quick vs thorough; include_raw describes when to use true vs false (e.g., when needing full payloads for recomputation). The description also covers response shapes that depend on parameter choices.

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 explicitly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies inputs (slug, URL, or question) and outputs (evidence packet + comparison). The naming and title align, and the description distinguishes this from sibling tools like ask_pipeworx or polymarket_edges by focusing on a single bet research with structured fan-out.

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 when-to-use examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also explains the depth parameter (quick vs thorough) and gives extensive fan-out examples for different bet types (BTC, Fed, Hormuz, Yankees, etc.), guiding the agent on how to invoke the tool effectively.

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 key behaviors beyond annotations: it details data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data with citation URIs). Annotations already indicate read-only and idempotent, and the description adds substantial context without contradiction.

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

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

The description is a single dense paragraph that efficiently covers trigger phrases, usage preference, type-specific details, sorting, and return format. Every sentence adds value, and the information is front-loaded with usage patterns.

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 tool has moderate complexity (two entity types, multiple data sources, no output schema). The description covers all essential aspects: inputs, behavior, return format (paired data + URIs), and efficiency gains. No output schema means the description must provide return semantics, which it does.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by giving concrete examples (e.g., '["AAPL","MSFT"]' for companies, '["ozempic","mounjaro"]' for drugs) and clarifying the format difference between company tickers/CIKs and drug names, which enhances understanding beyond the schema.

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

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

The description uses specific verbs like 'compare' and 'side-by-side comparison', identifies resources as companies or drugs, and explicitly distinguishes from sequential lookups by stating 'ALWAYS PREFER over sequential single-pack lookups'. It also lists trigger phrases such as 'compare X and Y', 'X vs Y', etc., making the purpose unmistakable.

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

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

The description gives explicit usage patterns (e.g., 'Compare X and Y', 'which is bigger'), states constraints (2–5 entities), and provides clear guidance to prefer this tool over sequential lookups. It also explains what happens for 'largest'/'most' queries, aligning with the tool's sorting behavior.

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 substantial context beyond annotations: account requirement, costing, timing (15-90s), decomposition into facets, parallel execution, return format (findings packet with evidence, confidence, gaps, contradictions), never invents, semantic excerpting. Annotations already declare readOnly=true and openWorld=true, and description aligns.

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

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

Description is long but front-loads critical info (account requirement, fallback). Uses parentheses and semicolons for structure, but could be more neatly formatted (e.g., bullet points). Every sentence adds value given tool complexity.

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

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

For a tool with 2 parameters and no output schema, the description fully covers prerequisites, usage, behavioral nuances, and return format. No missing information 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% (both parameters described). Description adds meaning: explains depth enum values with specific facet counts and behaviors (quick=3, standard=5+gap recovery+contradictions, thorough=8+iterative+contradictions), and clarifies that question can be broad/multi-part.

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

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

The description clearly states it performs 'grounded multi-source research across Pipeworx's 1314 STRUCTURED data sources' in one call, with specific verb ('researches'), resource (structured data), and scope (multi-source). It distinguishes from siblings by noting this is not open-web search and contrasts with ask_pipeworx for single lookups and breaking news.

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: account requirement, fallback to ask_pipeworx if not signed in, when to prefer ask_pipeworx (single lookup, breaking news). Also explains depth levels and when to use which version (standard for gap recovery, thorough for iterative leads).

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, confirming it is a safe read operation. Description adds that it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly,' which is useful behavioral detail beyond annotations.

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

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

The description is front-loaded with the core action 'Find tools by describing the data or task.' It efficiently includes usage context, domain examples, and output details. While slightly verbose with the long list of domains, each part 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 role as a discovery meta-tool among 35+ siblings, the description covers when to use, what it returns, and important behavior like no second schema lookup. It is sufficiently complete for the agent to understand its purpose 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% with clear descriptions for all 6 parameters. The description adds value by providing example queries (e.g., 'look up FDA drug approvals') and explaining the 'query' parameter accepts natural language, going beyond the schema's 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?

Clearly states verb 'Find' and resource 'tools by describing the data or task'. Lists many specific domains (SEC filings, FDA drugs, etc.), distinguishing it from sibling tools that are domain-specific like ooni_app_blocking or polymarket_arbitrage.

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

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

Explicitly instructs when to use: 'browse, search, look up, or discover what tools exist' and provides a strong directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This clearly separates it from 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?

The description adds behavioral details beyond the annotations (readOnly, idempotent, non-destructive): it fans out across multiple sources, returns specific fields, and mentions that patents lookup 'soft-fails until reactivated' due to API sunset. No contradiction with annotations.

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

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

The description is thorough but slightly lengthy. However, it is front-loaded with example queries and each sentence adds value. Minimal redundancy, clearly structured.

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

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

The description comprehensively explains what the tool returns (cik, company_name, filings, fundamentals, patents, news, LEI) and includes limitations (patents sunset). Since there is no output schema, the description fully covers the return 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%, and the description adds meaning: it clarifies that type is only 'company' currently and value is ticker or zero-padded CIK, with a note that names are not supported. This complements the schema effectively.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides concrete example queries and distinguishes from sibling tools like resolve_entity by explicitly saying to use that tool first if only a name is available.

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 usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states when not to use: 'names not supported (use resolve_entity first if you only have a name).'

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 destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and states the destructive action, complementing 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?

Two sentences efficiently convey action and usage guidance with no redundant or irrelevant content.

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

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

For a simple delete tool with one parameter and clear annotations, the description fully covers purpose, usage context, and relationships with sibling tools.

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 'key' described as 'Memory key to delete.' The description adds no additional parameter 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 'Delete a previously stored memory by key,' specifying the verb (delete) and resource (memory). It distinguishes from siblings by naming 'remember' and 'recall'.

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

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

Explicitly provides when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also suggests pairing with related tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. Description adds that the tool fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. This expands on annotations without contradiction, fully disclosing the read-only, non-destructive 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?

Three sentences: first states the core action, second explains the process, third lists use cases. No redundant information, front-loaded with the primary purpose.

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

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

Covers purpose, process, output format (standard llms.txt markdown), and use cases. Given the simple input schema and rich annotations, the description is complete enough. Minor omission: no mention of error handling or URL validation, but these are low risk for a read-only 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?

Input schema covers 100% of parameters with descriptions (url and max_links). The description does not add additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

Description uses specific verb 'Generate' and resource 'production-ready llms.txt file', clearly distinguishing from sibling tools (no other tool targets llms.txt generation). Mentions AI crawlers and standard format, leaving no ambiguity about the tool's function.

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?

Lists three explicit use cases ('getting a client's site indexed...', 'drafting llms.txt for your own project', 'auditing how an AI crawler would see a competitor'), providing clear context. Lacks explicit when-not-to-use guidance, but sibling tools are sufficiently different that this is not critical.

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 return field details but no additional behavioral context like pagination or data freshness. Given the annotations, the description's extra value is minimal.

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 zero waste. The first sentence states the core function and return fields; the second provides usage guidance. Every word earns its place.

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

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

For a simple list tool with annotations and a fully described schema, the description is complete. It explains the return format and usage context. Lack of output schema is mitigated by listing returned fields in the description.

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

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

Schema coverage is 100% with a single parameter `include_inactive` that has a clear description. The tool description adds no additional semantic meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb and resource, and mentions returned fields ('id, type, params, ...'). It differentiates from siblings like `subscribe` and `unsubscribe` by being a 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?

The description explicitly provides usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It gives clear scenarios but does not state when not to use or list alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool returns 'measurement counts and a blocking assessment', which provides useful behavioral context beyond the annotations. No contradiction.

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

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

Two sentences: the first defines purpose and lists apps, the second gives concrete examples. No unnecessary words, front-loaded with key 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?

The tool is simple with 3 parameters and no output schema. The description explains the return type as 'measurement counts and a blocking assessment', which is adequate but could be more precise about the assessment format. Completeness is good given the tool's simplicity.

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

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

Schema coverage is 100%, with each parameter having a description. The description adds no additional meaning beyond what the schema already provides, but it does reinforce the app and country examples. 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 verb 'Check' and the resource 'whether a messaging or circumvention app is blocked in a country', lists specific apps, and provides concrete examples. It distinguishes well from sibling tools like ooni_site_reachability which is for websites.

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

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

The description gives clear example queries ('is Telegram blocked in Iran', 'is Tor reachable from Russia'), implying usage context. It does not explicitly mention when not to use it or alternatives among siblings, but the examples effectively guide appropriate 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 (readOnlyHint, destructiveHint) already indicate safe read-only behavior. The description adds that the tool returns per-day OK/anomaly/confirmed-blocked counts, which is beyond the annotations. No contradictions; it provides useful output format context without repeating annotation info.

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

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

The description is a single sentence with a parenthetical example, efficiently conveying purpose and output format. Every word adds value, no redundancy. Front-loaded with the core function.

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 data retrieval tool with no output schema, the description adequately explains the return format (per-day counts) and purpose. It is complete enough for an agent to decide when to invoke and what to expect, though it lacks info on result size or pagination.

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

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

Schema coverage is 100% with clear descriptions for domain, country, and days (including default and max). The description does not add new semantic meaning beyond the schema; it reinforces the lookback window but provides no additional detail. Baseline 3 is appropriate.

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

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

The description clearly states it provides a daily time series of censorship measurements with concrete example (Twitter in Iran). It uses a specific verb ('shows') and identifies the resource (OONI measurements for a website-country pair). It distinguishes from siblings like ooni_app_blocking, ooni_measurements, and ooni_site_reachability by specifying the time-series blocking focus.

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 tracking blocking trends over time but does not explicitly state when to use this tool vs alternatives like ooni_site_reachability or ooni_measurements. No exclusions or when-not guidance is provided, but the use case is clear from the example.

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 context about 'recent' data and output fields, which is helpful but not essential given annotation coverage.

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

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

Two concise sentences; first states purpose, second provides usage 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?

Complete for a list tool with no output schema; mentions key output details and ties to sibling workflow.

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% coverage). Description only mentions 'domain and/or country' without adding new 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?

Clearly states the tool lists raw OONI measurements by domain/country with specific fields (timestamp, ASN, flags, link). Distinguishes from sibling ooni_site_reachability by suggesting post-use inspection.

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 recommends use after ooni_site_reachability. Does not detail when to avoid, but sibling context provides alternatives.

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

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

Annotations already indicate the tool is read-only, openWorld, idempotent, and non-destructive. The description adds value by detailing the output structure (counts of OK, anomalous, confirmed-blocked, failed measurements plus blocking assessment). This gives the agent a clear expectation of what the tool returns, beyond the annotations' safety profile.

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

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

The description is two sentences: first states the purpose, second elaborates on output and examples. Every sentence is informative and front-loaded. There is no redundant or extraneous text.

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

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

With no output schema, the description adequately summarizes the return values (counts and blocking assessment). It covers the required inputs and gives a concrete example. Could be more precise about the exact format or fields, but for a relatively simple tool it is sufficient.

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

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

Schema coverage is 100%, and the description does not add significant new meaning beyond what the schema provides. It reiterates the domain and country examples, and mentions URL extraction, but that is already in the schema. The description meets the baseline for high-coverage schema.

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

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

The description clearly states the tool checks whether a website is blocked or censored in a specific country using OONI data. It gives specific examples (bbc.com in China, twitter.com in Iran) and lists the measurement types returned. This distinguishes it from siblings like ooni_app_blocking, which focuses on app-level censorship.

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 checking site blocking but does not explicitly state when to use this tool versus alternatives like ooni_blocking_trend or ooni_measurements. There is no mention of when not to use it or prerequisites, only a typical use case.

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 (which provide no behavioral hints), the description discloses rate limits, quota-free usage, daily digest processing by the team, and impact on roadmap. 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?

Every sentence serves a purpose: purpose, usage conditions, formatting rules, team impact, and constraints. Front-loaded with core purpose, followed by actionable guidelines. No redundant or vague language.

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 (3 params, no output schema), the description fully covers all necessary context: what the tool does, when to use it, how to format feedback, rate limits, and what happens after submission. An agent can confidently invoke this 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?

Although schema covers 100% of parameters, the description adds context-specific guidance for each parameter, e.g., explaining enum values for type, specifying message character limit and style, and noting that context is optional but helps. This exceeds baseline expectations.

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 for sending feedback about bugs, missing features, data gaps, or praise. It explicitly lists four use cases and distinguishes from sibling tools like ask_pipeworx or discover_tools by focusing on direct communication to the Pipeworx team.

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

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

Provides explicit when-to-use scenarios (bug, feature/data_gap, praise) and what not to do (don't paste user prompt). Mentions rate limits (5 per identifier per day) and that it's free, helping agents decide when to invoke this tool over others.

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 behavior. The description adds value by explaining the data source ('CF analytics-engine'), privacy ('no PII'), and caching behavior ('Cached 5min-1h depending on window').

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 well-structured sentences that front-load the core purpose and then provide use cases. It is efficient with no wasted words, though it could be slightly more concise without the use case list.

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 explains what is returned (top tools, packs, call volume) and caching behavior, but lacks detail on the output format (e.g., whether it returns a list of objects with specific fields). For a tool without an output schema, more specificity would be helpful.

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 description for the 'window' parameter. The description enhances this by explaining the practical difference between shorter and longer windows ('what's hot right now' vs 'steady-state demand').

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 specifies the verb 'Returns' and the exact resources: 'top tools, top packs, and total call volume'. It clearly distinguishes itself from siblings like 'discover_tools' by focusing on trending data from other AI agents.

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

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

The description lists three explicit use cases and explains the effect of different window lengths. It does not explicitly mention when not to use the tool or alternative tools, but the guidance is clear and helpful.

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

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

The description goes far beyond annotations (readOnlyHint, etc.) by detailing internal logic: monotonicity checks, partition-sum, Jaccard similarity threshold, placeholder filtering, fill check vs. last-trade pricing. It also explains when results are actionable (realizable_edge_pp > 0). No contradictions with annotations.

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

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

The description is comprehensive but slightly verbose; it could be tightened slightly while preserving all key information. However, it is well-structured with clear sectioning (modes, filters, response) and front-loads the primary purpose. Every sentence 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 complexity (2 optional parameters, no output schema, but intricate behavior), the description covers all essential aspects: modes, argument semantics, internal checks, response structure, and even references another tool for custom sizing. It is self-contained and actionable.

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, but the tool description adds exceptional value: explains acceptable formats (slugs, URLs), gives concrete examples ('fed-decision-may-2026'), and details behavior for each mode including no-args default. This provides rich semantics beyond the schema.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes: no args for trending scan, event for single-event, and topic for cross-event. The verb 'find' and resource 'arbitrage opportunities' are specific and actionable.

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 mode, including recommendations (e.g., 'event (recommended for a specific market)') and examples of arguments. However, it does not directly address when to use this tool over sibling tools like polymarket_edges or polymarket_edge_tracker, leaving some ambiguity for the agent.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, setting a safe read baseline. The description goes far beyond, detailing internal model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), diagnostics, caching behavior (1h KV cache), and edge-case handling (Fed bets, empty segments). 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 long but well-structured with labeled sections and a front-loaded purpose. Every sentence carries specific technical detail. While dense, it avoids redundancy and is logically organized. A slightly more concise version could exist, but this structure aids comprehension for complex content.

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 (three model families, nine parameters, diagnostics, no output schema), the description is exceptionally complete. It explains return structure, diagnostics for empty segments, Fed bets, caching, and tradeable-edge knobs. The depth ensures an agent can infer behavior without needing an output schema.

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

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

Schema coverage is 100% with detailed descriptions. The description adds marginal value, e.g., explaining why min_kelly doesn't filter partitions and clarifying min_partition_leg_kelly. However, the schema already provides full parameter semantics, so the description's contribution is limited, meeting the baseline of 3.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It explicitly states it's built for 'what should I bet on today' and differentiates from paging hundreds of markets. The verb 'scan' and resource 'opportunities' are specific, and the sibling context includes other Polymarket tools, making this distinct.

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 frames the use case as discovering betting opportunities daily. It implies when to use (exploratory scan) but does not explicitly list alternatives or when not to use. Given the presence of siblings like polymarket_arbitrage and polymarket_edge_tracker, more explicit differentiation would be ideal, 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 declare readOnly and idempotent. The description adds significant behavioral context: snapshots written on cache-miss, decay from daily closes (not intraday), meaning of gaps. 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 detailed yet efficient, front-loading the core question and then systematically describing response fields. Every sentence adds value; could be slightly trimmed but acceptable.

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 (time-series analysis, trend computation) and lack of output schema, the description thoroughly explains response structure (tracked, expired, snapshot_dates), field meanings, and constraints (history depth, decay computation). 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 both parameters fully (100% coverage). Description adds minor extra detail (default 14, max 30 for days; default '1wk' for window) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling polymarket_edges by focusing on historical time-series and trend analysis.

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 context is given: 'a fresh wide edge and a 3-week-old wide edge are different trades'. This implies when to use the tool. Limits (60-day TTL, snapshot start) are mentioned. Does not explicitly state when not to use or name alternatives, but context with siblings is clear.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint) are consistent with the description's non-destructive, read-only nature. Description adds detail on behavior: walks the order book ladder, returns verdict and metrics, and warns about risks without contradictory statements.

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 lengthy but well-structured with clear sections for each mode and bulleted return fields. Frontal loading identifies purpose immediately. Could condense some details, but the structure aids comprehension given tool complexity.

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

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

No output schema provided, so description fully details all return fields and their interpretations for both modes. Also covers edge cases (thin legs, partial fills). Comprehensive enough for an agent to understand tool behavior without additional 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 description coverage is 100%, but the description adds value by explaining parameter interactions (e.g., required one of market or event) and mode-dependent semantics for side and size_usd. Enhances understanding beyond schema descriptions.

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

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

Clearly defines as a realizable-vs-theoretical edge check against live CLOB order-book depth, with explicit single-market and basket modes. Distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it before those tools.

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

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

Provides explicit guidance: use before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500. Explains why (theoretical overround not capturable on thin books, partial fills create directional risk). Also specifies required parameters (market or event).

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds critical behavioral details: compatibility_warning for non-equivalent bet shapes, temporal alignment checks, and leg matching logic. 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?

Well-structured with front-loaded purpose and mode explanation. Slightly verbose but each sentence adds value; uses natural bullet points and clear sections for modes, response, and safety fields.

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

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

Despite no output schema, description fully compensates by detailing response structure (leg-by-leg prices, top_spreads_pp, safety fields) and edge cases (compatibility_warning, temporal alignment). Covers all necessary contextual information for agent decision-making.

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

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

Schema coverage is 100%. Description adds context: topic list, override behavior for explicit tickers, and the two-mode usage. Enhances schema with practical meaning and interaction rules.

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 specifies 'cross-venue spread between Kalshi and Polymarket for the same resolving question' with a clear verb ('computes') and resource (spread). It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue pairs.

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 defines two modes (topic shortcuts and explicit ticker/slug), warns that most pre-mapped topics return compatibility_warning, and explains when spreads are meaningful (temporal alignment, matched pairs). Does not explicitly name alternative tools for when no arb exists, but sibling context provides that.

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, so safety is covered. Description adds scoping detail: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' This provides behavioral context beyond annotations. 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, front-loaded with the primary action. Every sentence adds value: purpose, usage context, scoping, and relationship to sibling tools. No redundancy or fluff.

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

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

For a simple tool with one optional parameter and no output schema, the description covers all needed aspects: retrieval/listing behavior, scoping, and lifecycle pairing. Annotations complement the safety profile. No gaps remain.

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

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

Schema coverage is 100% and includes a description for the single optional 'key' parameter. Description restates the schema's meaning ('omit the key argument' to list all) but does not add new information beyond what the schema provides. 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?

Clear verb+resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It distinctly describes the two modes of operation (with or without key) and distinguishes from siblings remember and forget.

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

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

Explicitly states when to use: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also mentions pairing with remember and forget for lifecycle management. Lacks explicit 'do not use when' guidance but is sufficient for typical 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds that setting mark_read:true flags returned events as read, affecting future calls. It also mentions polling is fine. 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 a single paragraph of three sentences, front-loaded with the main action. Every sentence adds value, no wasted words. 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?

Despite no output schema, the description specifies return fields (source, citation_uri, payload) and covers filtering, pagination (limit), and read-state management. For a read-only polling tool, this is complete.

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

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

Schema coverage is 100%, so baseline is 3. The description explains each parameter's purpose and behavior (e.g., type filter, limit range, since as ISO timestamp, mark_read impact, unread_only). It adds context beyond the schema, improving clarity.

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 pulls fired events from the subscription feed, specifying it returns recent alerts with source, citation_uri, and payload. It mentions filtering by type and since, but does not explicitly differentiate from sibling tools like recent_changes or 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?

The description mentions that polls work fine and provides an alternative endpoint (GET registry.pipeworx.io/alerts.json), but it offers no guidance on when to use this tool versus other siblings (e.g., recent_changes, list_subscriptions). There is no explicit context for when to choose this 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?

The description reveals significant behavioral details beyond annotations, such as fanning out to multiple data sources (SEC, GDELT/GNews, USPTO), fallback logic, and API sunset considerations. Annotations already indicate read-only and idempotent behavior, so the description adds valuable context without contradicting them.

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

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

The description is a single paragraph that efficiently packs multiple pieces of information. It front-loads with query examples, then details sources and parameter formats. While dense, every sentence serves a purpose, and there is no fluff.

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

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

Given no output schema, the description adequately describes the return structure (changes grouped by source, total_changes, URIs). It also covers parameter formats, multi-source behavior, and fallback logic. However, it omits potential limits like maximum window for 'since', which prevents a perfect score.

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%, providing baseline meaning. The description adds extra value by suggesting recommended values for the 'since' parameter ('30d' or '1m' for typical monitoring') and clarifying that 'value' accepts ticker or CIK. This enhances usability beyond the schema alone.

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

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

The description specifies the tool returns a change feed for a company with recent updates from multiple sources. It clearly distinguishes from the sibling entity_profile by stating when to use the alternative, making the purpose unambiguous.

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

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

The description provides explicit guidance on when to use this tool vs. entity_profile ('Use entity_profile instead when you want the static profile'). It also implies this tool is for recent changes via examples like 'What's new with X' and 'latest on Y'.

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 context beyond annotations: key-value scoping by identifier, persistent memory for authenticated users, 24-hour retention for anonymous sessions. 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?

Single paragraph front-loads purpose, then usage, then technical details. No wordiness; every sentence adds value.

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

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

Complete for a simple write tool: covers storage mechanism, scoping, time limits, and mentions sibling tools. No output schema needed.

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

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

Schema has 100% coverage with descriptions. Description adds usage context and examples like 'subject_property', 'target_ticker', enhancing practical 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 it saves data for reuse across conversations/sessions, with specific verb ('save') and resource ('data'). It distinguishes from sibling tools like 'recall' and 'forget'.

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

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

Explicitly tells when to use: when discovering something worth carrying forward (e.g., resolved ticker, target address, user preference). Also pairs with recall and forget.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds useful internal behavior: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This provides transparency beyond annotations.

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

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

The description is concise with two paragraphs, front-loaded with relevant examples. Every sentence earns its place, no redundant or filler content. The structure is logical and easy to scan.

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

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

Despite no output schema, the description covers return values for each entity type. Parameters are fully covered with examples. Given the complexity (two types, multiple input formats), the description is quite 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%, but the description adds significant value by explaining the meaning of each type: what it returns (e.g., ticker + CIK for company, RxCUI for drug) and examples of input formats. It also mentions auto-disambiguation and citation URIs, enriching the semantics.

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

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

The description starts with multiple example queries and clearly states it resolves names to canonical identifiers. It distinguishes itself from sibling tools by advising 'Use FIRST whenever you have a name but need an ID.' The verb 'resolve' and resource 'entity' are specific and unambiguous.

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

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

Explicitly states when to use: 'Use FIRST whenever you have a name but need an ID.' Also lists supported types and what they return. No explicit when-not-to-use, but the context is clear and the tool is intended as a first step.

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, openWorld hints. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density. 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 plus a clear use-case line. Every sentence earns its place; no redundancy. Information is front-loaded with the action and output.

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 4 parameters, no output schema, and rich annotations, the description covers the process, use case, and output shape well. Minor gap: no mention of error handling if probes fail, but overall adequate.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining that the first entity in 'entities' is treated as the subject and the rest as competitors, and clarifies that 'context' disambiguates common names.

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

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

The description clearly states the tool compares AI visibility across entities side-by-side, using ai_visibility_check and ranking by score. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying its competitive audit context.

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 a concrete use case ('competitive AI-marketing audits') and implies when to use (multi-entity comparison). It does not explicitly list when not to use or alternatives, but the sibling tools are provided separately.

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. The description adds valuable behavioral context: fan-out across two services, 5-30s delay for bundlephobia first measurement, graceful degradation with sources_failed list. 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 informative and well-structured, front-loaded with purpose. It is slightly long but every sentence adds value. Could be tightened slightly but otherwise excellent.

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

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

Without an output schema, the description fully explains the return format (summary block with fields, per-advisory detail, links, alternative versions) and covers error behavior (partial failures, timeouts). Highly complete for a complex tool.

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

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

Schema description coverage is 100% with good descriptions. The description adds context: scoped packages are accepted and version defaults to latest. This adds marginal value beyond the schema.

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

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

The description clearly states it's a composite check for npm packages, combining deps.dev and bundlephobia. The verb 'scan' and resource 'dependency' are specific. Among siblings like validate_claim or entity_profile, this tool is distinct.

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

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

Explicitly says 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also notes NPM-only in v1 and provides alternatives for other ecosystems (PyPI, Maven, etc.). Covers partial failure scenarios.

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 internal workings: BGE-base-en embeddings, 500-char overlapping windows, 200K char limit with truncation flag, and offsets for verification. Annotations already indicate safety (readOnly, idempotent), and description adds valuable behavioral details without contradiction.

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

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

Two dense sentences with front-loaded purpose, no filler. Every sentence adds context or usage guidance. Earns its 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?

Despite no output schema, the description clearly explains return values (top-N passages with offsets and scores). It covers internal mechanics, limitations, and pairing with a sibling, making it complete for a search tool.

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

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

Schema coverage is 100% and already documents all three parameters. The description adds minor value (truncation details, query examples) but largely repeats schema info. 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 performs semantic search inside a fetched record, using specific verbs and resources. It provides concrete examples (SEC 10-K, article) and differentiates from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly states when to use (record too big to prompt) and what it returns (only relevant passages). It mentions pairing with ask_pipeworx_grounded, providing clear context for agent decision-making.

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

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

Annotations indicate mutation (readOnlyHint=false). Description adds detail: returns subscription ID, persistence requirements, and SMS rate limit (10/day). 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?

Well-organized, front-loaded main purpose, but slightly lengthy. Every sentence adds value; minor redundancy in delivery description.

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 all parameters (including nested), type-specific params, delivery channels, and return value. No output schema, but return id is mentioned. Sufficient for a 3-param 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%. Description adds examples for each type and delivery constraints (e.g., phone verification, webhook signing), going 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 'Create a proactive monitoring subscription to a live-data event stream,' specifying the verb (create) and resource (subscription). It distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

Explicitly states when to use (requires Pipeworx OAuth, not for anonymous/BYO), provides supported types with examples, and mentions alternative methods like recent_alerts for the feed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral details: returns example questions drawn from live catalog, can be called with no args or filtered by topic. No contradictions; adds context beyond annotations.

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

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

Description is informative but relatively long. It front-loads with synonyms and purpose, and each sentence contributes meaning. Could be slightly more concise, but structure is good with examples and list of categories.

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

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

No output schema, but description thoroughly explains return value: 'Returns category-bucketed example questions (...) each with the exact tool + argument shape that answers it.' Also covers argument behavior and use cases. Complete for a low-complexity tool with 1 optional parameter.

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 topic parameter. Description adds value by explaining effect of no-argument call vs. providing topic, and gives concrete examples of topic values. Slight improvement over schema alone.

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

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

Description clearly states it is the onboarding entry point for new users, returns category-bucketed example questions with exact tool+argument shapes. It distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on 'what can I ask?' and providing meta-information.

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 this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to omit topic argument and how to focus with a specific topic. Provides clear when-to-use and alternatives 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?

Adds value beyond annotations: explains that the row is deactivated (not deleted) and historical events remain available via recent_alerts. Annotations indicate idempotentHint=true and destructiveHint=false, consistent with soft delete. Ownership enforcement is additional behavioral detail.

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

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

Two short, information-dense sentences. Front-loaded with the primary action, then key constraints and side effects. No wasted words.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers the main behavioral aspects. It could mention what the response looks like (e.g., success indicator), but the deactivation detail provides sufficient context for an agent.

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

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

Schema coverage is 100% with a description for the sole parameter 'id'. The description adds no new semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states the verb 'cancel' and the resource 'subscription by id'. Distinguishes from siblings like subscribe (create) and list_subscriptions (list) through the action and ownership enforcement.

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 ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. Mentions alternative tool recent_alerts for history. Could be more explicit about not using this for creating subscriptions, but sibling context makes it clear.

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

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

Annotations already provide readOnly, openWorld, idempotent hints. The description adds behavioral details: two paths (structured SEC for company financials, grounded pipeline for others), returns verdict with evidence and reasoning. 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 detailed but well-structured with trigger phrases, usage, pipeline explanation, and return format. Slightly long but every sentence adds value. Could be slightly more concise.

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

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

Despite no output schema, the description fully explains the return (verdict types, actual value with citation, reasoning). It covers the two processing paths and the tool's role, making it complete for agent invocation.

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

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

Schema coverage is 100%. The description adds meaning to tolerance_pct by explaining it overrides the implied tolerance from claim wording and its default/cap. Adds useful context beyond the schema.

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

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

The description clearly states the tool's purpose: natural-language claim verification. It provides trigger phrases and explicitly says when to use it, distinguishing it from other tools.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the two pipelines but doesn't explicitly list when not to use or compare to sibling tools. Clear but not exhaustive.

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