Epo Ops

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

The description adds significant behavioral context beyond the annotations: it notes the default model (Workers AI Llama-3.3-70b, free), explains that passing `_apiKey` charges the user directly via Anthropic, and details the return structure (per-model {score, confidence, signals, raw_response} + combined view). 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 three sentences, front-loaded with the core action, then details, and use cases. Every sentence provides essential information without redundancy.

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

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

The description covers all aspects: functionality, parameters (with examples), return values, and use cases. Despite no output schema, the return structure is clearly described. No gaps given the tool's complexity and rich annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model for 'models', the BYO key model for '_apiKey', and the disambiguation purpose of 'context'. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It specifies a specific verb (probe, score) and resource (LLMs), distinguishing it from sibling tools like 'scan_competitor_ai_presence' which likely focuses on scanning rather than scoring.

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 contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not specify when NOT to use this tool or compare it to alternative tools among siblings, such as 'scan_competitor_ai_presence' or 'ask_pipeworx'.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds valuable behavioral context: routing across 5,344 tools, returning structured answers with citation URIs, being 'one fast call', and working on every tier. There is no contradiction with annotations.

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

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

The description is long but every sentence earns its place: primary directive, domains covered, examples, escalation paths, and breaking-news behavior. It is front-loaded with the most critical instruction ('PREFER OVER WEB SEARCH') and remains focused without redundancy.

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

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

Despite no output schema, the description specifies the return type ('structured answer with stable pipeworx:// citation URIs'). It covers when to use, when not to use, alternatives, and examples, giving an agent all necessary context to select and invoke the tool correctly. The tool's complexity is well-matched by the description's thoroughness.

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 aliases are documented. The description supplements this by providing a wide range of example queries ('current US unemployment rate', 'Apple's latest 10-K') that clarify the expected natural-language input. While the schema already gives examples, the description reinforces appropriate usage patterns.

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

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

The description clearly states the tool's function: 'Routes the question to the right one of 5,344 tools... fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It uses specific verbs and distinguishes itself from siblings by positioning as the default entry point and referencing ask_pipeworx_grounded and deep_research.

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

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

Explicitly instructs 'PREFER OVER WEB SEARCH' and lists trigger phrases like 'what is', 'look up', 'find', 'get the latest'. It provides clear alternatives with specific conditions: use ask_pipeworx_grounded for hallucination-resistant answers and deep_research for broad multi-part questions. Also mentions handling for breaking-news topics.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses the experimental nature, the live candidate routing improvements, the current state of no active candidate, and that it 'Falls back to nothing' — emphasizing it is a full working router. This adds valuable context about behavior and intent.

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 and front-loaded with the key identity of the tool, then provides essential context in a compact form. Every sentence contributes: what it is, current state, usage instruction, and fallback behavior, with no redundant phrases.

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 references the response shape matching ask_pipeworx, which is sufficient context. It addresses the experimental status, usage, and full functionality, making it complete for an agent to correctly select and 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?

The schema description coverage is 100%, with every parameter (question and its five aliases) documented as a string. The tool description does not need to elaborate on parameters because the schema fully explains them; this meets the baseline without adding extra semantic value.

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

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

The description clearly states this is a 'Beta version of ask_pipeworx: identical universal router' with the same 5,344 tools, arguments, and response shape, making it a full working router. It explicitly distinguishes itself from the stable ask_pipeworx and the grounded variant via the experimental edge and candidate routing improvements.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that results are compared against the stable router. It also notes that no candidate is active currently so it matches ask_pipeworx exactly, giving clear when-to-use context without ambiguity.

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

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

Beyond the annotations (readOnly, idempotent), it discloses critical behavior: the tool refuses to answer when data doesn't contain a direct answer, with specific refusal reasons, and returns evidence quotes. This adds substantial value by explaining failure modes and trust guarantees that annotations do not cover.

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, leading with the core value proposition, then detailing mechanics, return format, refusal reasons, and use cases. While every sentence carries useful information, it could be slightly tightened without losing substance, so a 4 rather than 5.

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 as a wrapper over thousands of tools, the description fully covers purpose, usage, return schema (since no output schema exists), failure modes, and cost tradeoffs. It is self-sufficient for an agent to decide when and how to invoke it correctly.

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

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

Schema coverage is 100% for the single required parameter (or its aliases), so the schema already documents the question parameter thoroughly. The description adds no additional parameter guidance, but at this coverage level a baseline 3 is appropriate per the rubric.

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

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

The description clearly states it is a 'hallucination-resistant answer mode' that routes, fetches, and extracts grounded answers, distinguishing it from the sibling ask_pipeworx with the specific verb 'extracts' and explicit comparison. It names the exact resource and behavior, leaving no ambiguity about its role.

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

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

It explicitly states when to use: 'whenever an answer will be quoted, cited, or acted on' and provides a list of high-stakes scenarios. It also gives an explicit alternative and tradeoff: 'prefer ask_pipeworx for casual lookups' because of the extra LLM call, offering clear when-to and when-not-to guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds extensive behavioral details beyond annotations: resolver contract (match confidence, alternatives), parent event extractor, news fallback handling, safety short-circuits (low_confidence_match, market_closed_or_inactive), tradeability warnings, and cancellation rule parsing. 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 lengthy but well-structured; it front-loads the core purpose and usage, then details behavior, edge cases, and response shapes. Every sentence adds value given the tool's complexity. Could be slightly tighter but remains clear and comprehensive.

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 3 parameters, no output schema, and complex behavior, the description is exceptionally complete. It covers all input variations, resolution logic, evidence aggregation, parent event context, news handling, safety measures, market status handling, and cancellation rules. Fully 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%, so baseline is 3. The description adds examples for the 'market' parameter (slug, URL, question text) but does not significantly enhance meaning beyond the schema descriptions. The 'depth' and 'include_raw' parameters are similarly covered. No additional semantic value beyond examples.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb ('Research'), resource ('Polymarket bet'), and input format (slug, URL, question text). Distinguishes from siblings by emphasizing one-call research, with explicit usage examples like 'should I bet on X'.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides classifier examples and fan-out patterns, giving context for appropriate scenarios. While it does not explicitly exclude other tools, the guidance is clear and practical.

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, openWorld, idempotent, and non-destructive. Description adds details: for companies pulls LATEST 10-K financials with fiscal year handling, for drugs pulls FAERS counts. Mentions sorted results and citation URIs. No contradictions.

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

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

Description is a single dense paragraph with front-loaded query patterns. Every sentence adds meaningful information, though it could be slightly more structured. No wasted 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?

Given the tool complexity (2 params, no output schema), the description covers what, when, and how. Mentions returned data and URIs. Could briefly note pagination or omitted details, but sufficient 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 descriptions. Description adds value by specifying data sources for each type and clarifying that values should be tickers/CIKs for companies and drug names. Also reinforces min/max constraints.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs in one call. It specifies the data sources (SEC EDGAR for companies, FAERS for drugs) and distinguishes itself from sequential single-pack lookups.

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

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

Provides explicit when-to-use triggers like 'compare X and Y' and 'which is bigger'. Explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and notes it replaces 8-15 sequential lookups, giving clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes well beyond this by explaining parallel facet decomposition, routing to 5,344 tools, gaps[] for unanswered facets, contradictions[] for disagreeing findings, hop fields, semantic excerpting of large records, timing expectations (15-90s), and the 'never invented' guarantee. No contradiction with annotations.

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

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

The description is long but every sentence provides operational value: account requirements, source coverage, non-open-web distinction, output format, alternatives, timing, and depth semantics. It is front-loaded with the critical account gate, then quickly defines the core capability. While dense, the length is justified by the tool's complexity and there is no filler or repetition.

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

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

Despite no output schema, the description thoroughly explains the return shape (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], hop field). It covers authentication, input complexity, expected latency, depth variations, limitations for current-news topics, and alternatives. This is a fully self-contained description for an agent to select and invoke appropriately.

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 depth and question have descriptions), but the description adds meaningful enrichment: depth values are explained with exact facet counts (quick=3, standard=5, thorough=8), behavior differences (gap-recovery hop, contradictions scan), and the paid-tier requirement for 'thorough'. It also clarifies that question accepts natural language and broad/multi-part queries, going beyond the schema's basic description.

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

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

The description begins with a precise verb+resource+scope: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call'. It clearly differentiates this tool from siblings by explicitly noting it is NOT open-web search and contrasts it with ask_pipeworx for single lookups. Examples of appropriate use cases ('compare X and Y's regulatory + financial exposure') further anchor the purpose.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and explicit when-not-to-use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also notes account requirements and which depth requires a paid plan, giving clear operational 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=true and idempotentHint=true, so the description correctly does not contradict them. It adds useful context beyond annotations: returns top-N tools with full schemas ready to call, no second lookup needed. This supplements the behavioral profile well.

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 yet comprehensive: opens with purpose, then usage context, then return details, concluding with a strategic note ('Call this FIRST'). Every sentence earns its place; 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?

Despite having 6 parameters (mostly aliases) and no output schema, the description covers the tool's purpose, when to use, what it returns (top-N tools with schemas), and how to structure queries. Minor gap: does not mention any error handling or rate limits, but overall it is very complete for this type of 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 adds value by providing example queries in the schema's 'examples' field and clarifying that query accepts multiple aliases (task, q, description, search). This helps the agent formulate the query parameter correctly.

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

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

The description starts with 'Find tools by describing the data or task' which clearly states the verb and resource. It distinguishes itself from sibling tools by focusing on discovery of tools rather than performing tasks, and enumerates many specific domains (SEC filings, FDA drugs, etc.) to clarify scope.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a list. Also provides guidance to 'Call this FIRST when you have many tools available...', effectively telling the agent when to prefer this tool over 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?

Description adds significant context beyond the annotations: it explains that the tool fans out across multiple sources in a single parallel call, details exactly what it returns (including that patents may soft-fail), and indicates it is a read-only, idempotent operation. 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 relatively long but front-loaded with examples. It efficiently conveys all necessary information without excessive verbosity. Could be slightly more structured, but overall very good.

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

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

Given the complexity and lack of output schema, the description is remarkably complete. It lists all returned fields (CIK, filings, fundamentals, patents, news, LEI) and even notes the patent sunset. The agent has enough context to use the tool effectively.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'value' can be ticker or CIK, and that 'type' only supports 'company' today, with a recommendation to use resolve_entity for names. This aids correct parameter usage.

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

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

The description clearly states the tool's purpose: returning a full cross-source profile of a US public company. It lists specific data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and the fields returned, and distinguishes itself from chaining multiple single-purpose 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 when-to-use examples (e.g., 'Tell me about X', 'research Acme'), specifies input formats (ticker or CIK, not names), advises using resolve_entity for names, and mentions that the patents part may soft-fail after May 2025. It also states it should be preferred over chaining single-pack lookups.

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

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

Description adds context beyond annotations: clarifies that the tool deletes a previously stored memory, making the destructiveHint concrete. However, details like irreversibility or immediate effect are not specified, but annotations already cover the destructive and idempotent nature.

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

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

Two sentences with no wasted words. Purpose, usage, and pairing are all front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, when to use, and related tools. No gaps.

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

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

The single parameter 'key' is described in the input schema as 'Memory key to delete'. The description does not add additional semantics beyond the schema, and coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key'. It distinguishes from siblings by explicitly pairing with 'remember' and 'recall', which are memory-related tools.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. 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=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool fetches the page and extracts title/description/key links, which provides useful behavioral context beyond the annotations. It does not cover limitations like rate limits or handling of dynamic content, but the information is adequate.

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

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

The description is concise (two sentences plus a list) and front-loaded with the primary purpose. Every sentence adds value: first states the main function, second explains the process, and the list enumerates use cases. No unnecessary 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?

Given the tool's simplicity (2 parameters, no output schema, strong annotations), the description covers all necessary aspects: what it does, how it works, output format, and when to use it. It implicitly explains the return value (a text blob) and does not require supplementary details.

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

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

Schema description coverage is 100%, so both parameters (url, max_links) are fully described in the schema with type and description. The tool description does not add any new meaning or constraints beyond what the schema provides, earning the baseline score 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 generates an llms.txt file for a URL, explains the process (fetch, extract, emit), and specifies the output format. It lists concrete use cases, distinguishing it from sibling tools that likely deal with AI visibility or research but not specific llms.txt generation.

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

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

The description provides explicit use cases (client site indexing, own project, competitor auditing), which helps an agent decide when to use the tool. However, it does not mention when not to use it or contrast it with similar tools like ai_visibility_check or scan_competitor_ai_presence, so it lacks exclusion 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=true, idempotentHint=true, destructiveHint=false. Description adds critical authentication requirement ('Requires _apiKey=consumer_key:consumer_secret'), which is beyond the annotations.

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

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

Two concise sentences that front-load the primary purpose and essential details. No extraneous information.

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

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

Given the tool's simplicity, an output schema exists (not shown but reported), and the description covers purpose, input format, and authentication. No additional details are 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?

Input schema has 100% coverage with description for 'number'. The tool description adds value by specifying the format ('epodoc-format') and providing an example ('EP1234567'), which clarifies usage beyond the schema's generic description.

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

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

Description explicitly states 'Fetch the abstract text of a published patent from EPO OPS given its epodoc-format number', which is a specific verb and resource. This clearly distinguishes it from sibling tools like get_biblio, get_claims, and get_family.

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

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

Description provides context by specifying the required input format (epodoc-format number with example). However, it does not explicitly mention when not to use this tool or name alternatives, though sibling names imply choices.

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

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

Annotations already indicate readOnly, idempotent, etc. The description adds valuable context by specifying the exact data elements returned (title, inventors, etc.), which is beyond the annotations. However, it doesn't discuss rate limits or authentication.

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

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

Single sentence that is front-loaded with the key purpose and specific contents. No wasted words.

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

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

For a simple tool with one parameter and an output schema, the description is complete. It explains what the tool returns, and the output schema covers the return format.

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 no extra meaning beyond the schema. The parameter is well-documented in the schema with format and example.

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 provides bibliographic data for a patent, listing specific fields (title, inventors, applicants, dates, classifications). This distinguishes it from sibling tools like get_abstract or get_claims.

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

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

The description implies the tool is for bibliographic data but does not explicitly state when to use it over other patent tools (e.g., get_claims, search_patents). No exclusions or alternatives are provided.

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

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

Annotations already indicate read-only, idempotent behavior. Description adds critical auth requirement (_apiKey), which is not in 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?

Two sentences: first states purpose and input format, second states auth requirement. 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, single-parameter tool with an output schema, the description fully covers input, auth, and data source. No gaps.

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

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

Schema coverage is 100%, description adds an example of the epodoc format but no additional semantic detail beyond the schema's own description.

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

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

Clearly states it fetches full claims text of a published patent, specifying data source (EPO OPS) and input format. Distinguishes from siblings like get_abstract or get_biblio.

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 an example input and notes the authentication requirement, but does not explicitly state when to avoid using this tool or compare with 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 and idempotentHint, so the description's burden is lower. It adds minimal behavioral context by explaining 'INPADOC family' and 'worldwide,' but does not disclose details like whether all family members are returned or if there are rate limits.

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

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

The description is extremely concise (10 words) and front-loaded, with no filler. However, it could be slightly more structured to include a hint about the output or usage context.

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

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

Given the tool has one parameter, full schema coverage, and an output schema, the description is minimally adequate. It clarifies the concept of patent families and the scope (worldwide), but does not fully describe the return type or when to choose this over 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 the parameter 'number' described as 'Patent number, epodoc format.' The description does not add any additional meaning or constraints beyond the schema, so baseline score of 3 applies.

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

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

The description clearly states the tool retrieves 'INPADOC family — related patent applications worldwide for the same underlying invention.' This specific verb+resource combination distinguishes it from siblings like get_abstract or search_patents by focusing on patent family relationships.

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 no guidance on when to use this tool versus alternatives such as search_patents or get_biblio. It lacks context like 'use when you need all family members for a given patent' or exclusions for other tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds value by listing the exact response fields (id, type, params, created_at, etc.) and clarifying that it returns active subscriptions by default.

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

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

The description is two sentences, each serving a clear purpose: first stating purpose and return fields, second providing usage guidance. No extraneous 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 description covers all needed context: what the tool does, what it returns, and when to use it. Given the tool's simplicity and rich annotations, it is fully 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 has 1 parameter with 100% description coverage. The description does not add new meaning to the parameter beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and lists the fields returned. It distinguishes itself from siblings like subscribe and unsubscribe.

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

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

The description includes explicit when-to-use guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It implies context but lacks explicit when-not-to-use.

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

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

The description discloses behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against quota, and that the team reads digests daily. 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 concise, front-loaded with the core purpose, and each sentence adds value. It avoids redundancy and is appropriately sized for the tool's complexity.

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

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

The description covers all necessary aspects: purpose, usage, constraints, and impact. No output schema is needed for this feedback tool, so completeness is high.

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

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

The description adds meaning beyond the input schema by explaining the enum values for 'type' in more concrete terms and describing the 'context' object's purpose. Schema coverage is 100%, baseline 3, but the extra detail justifies a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb and resource, and distinguishes from sibling tools by being a feedback mechanism rather than a data retrieval or analysis 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 provides explicit when-to-use guidance for each feedback type (bug, feature/data_gap, praise), and tells the agent what not to do ('don't paste the end-user's prompt'). It also mentions rate limits and cost.

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

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

Description adds behavioral context beyond annotations: derived from CF analytics-engine, no PII, cached 5min-1h depending on window. Annotations already indicate readOnly and idempotent, so 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 concise paragraphs: first explains what the tool does, second lists use cases. Front-loaded with key information, no redundant sentences. Efficient and well-structured.

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

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

Given the tool's simplicity (1 param, no output schema), the description is complete. It covers data source, aggregation method, privacy, and caching. No gaps 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% with a single parameter (window). The description enhances the parameter by tying window length to use cases (hot vs steady-state), adding semantic meaning beyond the enum values.

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

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

The description clearly states it returns 'top tools, top packs, and total call volume over a recent window'. It specifies the resource (Pipeworx trending data) and the verb (returns). It distinguishes itself from sibling tools by focusing on aggregate trending data, not individual queries.

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 lists three use cases: discovering hot data sources, confirming canonical choice, and seeing use case alignment. Also explains window selection: shorter windows for current hotness, longer for steady-state demand. Provides clear context for when to use 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?

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds rich behavioral context: scanning top 200 markets, partition checks, semantic anchor (≥0.30 Jaccard similarity), partition filter (dropping placeholder slugs), fill check against live CLOB depth, and response structure. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the main purpose. It is fairly long but every sentence adds unique value: mode usage, semantic anchor, partition filter, fill check. Could be slightly trimmed without losing info, but overall 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 no output schema and two parameters, the description is thorough. It explains the tool's full workflow, response fields, caveats (e.g., low similarity, placeholders, fill check conditions), and references a related tool. Complete for a complex arbitrage detection 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% for both parameters, but the tool description adds significant meaning: examples of event slugs (e.g., 'fed-decision-may-2026'), explains the modes they activate, and notes that full URLs are accepted. This goes well beyond the schema's brief descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes two modes (event, topic) and contrasts with sibling tools by mentioning polymarket_fill_risk for custom sizing. No tautology or vagueness.

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

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

Explicit usage guidance: 'Call with NO args for a trending_scan... pass event for ... or topic for ...'. It recommends event mode for specific markets and warns when not to trade (realizable edge ≤ 0). Also directs to polymarket_fill_risk for custom sizing, giving clear alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context: explains three model families with formulas, filters, caching policy, and output structure including diagnostics. No contradictions with annotations.

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

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

The description is lengthy but well-structured with clear segmentation into model families and knobs. It is front-loaded with purpose. While some details could be condensed, the complexity warrants the length.

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

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

Given 9 parameters, no output schema, and complex behavior, the description is comprehensive: covers input guidance, output structure (by_segment, fed_candidates, _diagnostics), caching, and exclusions. It fully addresses the complexity without 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 parameter descriptions. The description adds value by grouping parameters as 'tradeable-edge knobs' and explaining their tradeability context, 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 clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edge_tracker, which have different scopes.

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 daily betting discovery without explicit when-not or alternatives. It mentions 'tradeable-edge knobs' guiding usage, but lacks direct comparison to siblings like polymarket_arbitrage (which might focus on arbitration) or polymarket_edge_tracker (tracking edges over time).

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds detailed behavior: returns tracked/expired/snapshot_dates, explains decay calculation, and notes limits. 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?

Well-structured with clear sections. Slightly verbose but all information is valuable and front-loaded with purpose.

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

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

Despite no output schema, description fully explains response structure including fields and meanings, making agent usage clear.

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 good descriptions. Description slightly adds by specifying default values and clamping range, but largely repeats schema info.

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

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

Description clearly states it provides edge persistence and decay telemetry, answering specific question about edge age and decay. Distinguished from siblings like polymarket_edges and 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?

Provides context on when to use (to distinguish fresh vs old edges) and notes limitations (60-day TTL). Could explicitly mention alternatives but sibling names provide some differentiation.

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 behavioral traits beyond annotations: it checks live order-book depth, walks the ladder, returns slippage, max fillable, verdicts, per-leg details, and warns about forced directional risk. Annotations already declare readOnlyHint, idempotentHint, and no destructiveness, so description adds valuable context about query behavior and risk assessment.

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 clear sections for requirements, single-market, basket, and usage. Every sentence adds value given the tool's complexity. Could be slightly more concise, but the detail is warranted.

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

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

Given the tool's complexity (two modes, 4 parameters, no output schema), the description is remarkably complete. It explains return fields (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs) and edge cases (forced directional risk). This 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%, so baseline is 3. The description adds extra meaning: explains single-market vs basket modes, default side logic, size_usd interpretation for buys vs sells and basket settlement notional. This provides essential context beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, and the verb 'check' plus resource 'order-book depth' make it specific. The tool is distinct from siblings like polymarket_arbitrage and polymarket_edges.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why (theoretical overround not capturable on thin books, partial fills create directional risk) and mentions alternatives implicitly by linking to sibling tools.

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

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

Annotations confirm read-only, idempotent, open-world behavior. Description adds rich behavioral detail: explains compatibility conditions, temporal alignment requirements, and how skipped comparisons work. Warns that pre-mapped topics are not automatically tradeable. No contradiction with annotations.

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

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

The description is fairly long but every sentence adds value. It is organized into logical sections (overview, modes, response, safety). Could be slightly more structured (e.g., bullet points) but remains readable and concise for the content density.

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

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

Given no output schema, the description compensates by detailing the response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). All three parameters are explained with examples. The tool stands alone among siblings with unique purpose.

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

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

Schema coverage is 100%, so baseline is 3. Description adds significant value by explaining the two modes, listing all 10 topic shortcuts, and describing how explicit tickers override topic mapping. Provides examples and 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?

Clearly states cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from siblings like polymarket_arbitrage by specifying it's cross-venue. Describes two modes (topic shortcuts and explicit tickers) with specific examples.

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

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

Explains when to use (to find spreads) and includes critical safety caveats (compatibility_warning, temporal_alignment). Notes that most pre-mapped topics return warnings, setting expectations. Does not explicitly compare to other sibling tools but provides sufficient context for usage decisions.

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

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

Annotations already indicate read-only and idempotent. The description adds context about scoping and the list-all-keys behavior, which goes 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?

The description is concise, front-loaded, and every sentence provides value. No wasted words, covering purpose, use cases, and pairing.

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

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

For a simple, read-only tool with one optional parameter, the description covers all necessary aspects: purpose, usage, scoping, and relationships. 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?

The single parameter 'key' is well-described in both the schema and the description. With 100% schema coverage, the description does not add significant new meaning, meeting the baseline.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, using specific verbs and distinguishing from sibling tools like remember and forget. Examples and scope are provided.

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 (look up context) and when not (for saving or deleting), with clear alternatives mentioned (remember, forget). The pairing advice is very 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 discloses that mark_read:true flags events as read, modifying state. However, annotations declare readOnlyHint=true, indicating no state modification. This contradiction undermines transparency, as the agent receives conflicting signals. Score 1 per rubric for contradiction.

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

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

The description is concise (3-4 sentences) and front-loaded with the core purpose. Each sentence adds unique information (purpose, returned fields, filtering, side effect, alternative access) without redundancy.

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

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

The description covers returned fields, filtering, mark_read behavior, and polling suitability. While missing explicit pagination details or error handling, the limit parameter and simple nature make it sufficiently complete for a read tool with good schemas.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples (type 'sec_8k'), clarifying that 'since' is an ISO timestamp, and explaining the effect of mark_read, 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 'Pull fired events from your subscription feed,' specifying the verb 'pull' and the resource 'alerts from subscription feed.' It details returned fields (source, citation_uri, raw payload) and filtering options, distinguishing it from sibling tools and the alternative GET endpoint.

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

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

The description provides clear context for when to use this tool to retrieve recent alerts, mentions filtering options, and notes that polling works fine. It also points to an alternative REST endpoint for scripts/dashboards, implying a usage boundary, but does not explicitly compare with sibling tools or state when not to use it.

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

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

The description discloses behavioral traits beyond annotations: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail note), returns structured changes grouped by source, total_changes count, and citation URIs. This aligns with readOnlyHint and idempotentHint 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 and well-structured, starting with user query examples, then explaining the underlying mechanism, parameter details, return format, and finally guidance on alternatives. Every sentence adds value without redundancy.

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

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

For a tool with no output schema, the description adequately explains the return format (changes[] grouped by source, total_changes, citation URIs). It covers tool complexity (multi-source, fallback logic) and provides all necessary context for correct invocation.

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

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

The description adds significant meaning beyond the input schema: explains 'since' accepts ISO dates or relative shorthand like '7d', '30d', '3m', '1y', and recommends '30d' or '1m'. Clarifies 'value' can be ticker or CIK, and 'type' currently supports only 'company'. Schema coverage is 100% but description still enriches.

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

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

The description clearly states the tool provides a change feed for a company over a time window, with examples of user queries ('What's new with X', 'latest on Y'). It distinguishes from the sibling tool entity_profile by specifying when to use each.

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

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

The description provides explicit guidance on when to use this tool (for recent changes/updates) and when to use entity_profile instead (for static profile). It also includes example queries and a suggested default for the 'since' parameter ('30d' or '1m').

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?

While annotations already indicate non-read-only, idempotent, and non-destructive, the description adds valuable behavioral context: scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24 hours) sessions, and storage mechanism (key-value). 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?

Three well-crafted sentences, front-loaded with the core action, followed by when-to-use and behavioral details. No wasted words; every sentence earns its place.

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

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

For a 2-parameter write tool without output schema, the description covers purpose, usage, behavior, and parameter examples. Could mention whether existing keys are overwritten or return value on success, but the idempotent hint partially addresses that. 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% with clear parameter descriptions. The description adds meaningful usage context with examples (e.g., 'subject_property', 'target_ticker') and explains the key-value pair nature, enhancing understanding beyond schema.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It provides concrete examples (resolved ticker, target address, user preference, research subject) and distinguishes from siblings by mentioning 'recall' and 'forget' as companion tools.

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

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

Explicitly tells when to use: 'Use when you discover something worth carrying forward'. Also advises pairing with 'recall' and 'forget', giving clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that internal cascading through several endpoints replaces 2-3 manual lookups, providing useful behavioral 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?

Well-structured with examples first, followed by purpose and supported types. Every sentence adds value, though slightly lengthy; appropriate for the complexity.

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

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

Given no output schema, the description fully explains what each entity type returns (ticker, CIK, RxCUI, etc.) and mentions internal cascading. Complete for a lookup tool.

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

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

Schema descriptions are present but generic. The description enriches both parameters with concrete examples (e.g., 'AAPL', 'ozempic') and explains what each type returns, adding significant meaning beyond the schema.

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

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

The description clearly states the verb (resolve) and resource (name to identifier), provides example queries, and distinguishes from siblings by emphasizing 'Use FIRST whenever you have a name but need an ID.'

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

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

Explicit guidance to use this tool first when needing an ID from a name. Supported types are listed, but no explicit exclusions for when not to use it are given; context is clear nonetheless.

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. The description adds significant behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density per entity. No contradictions.

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

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

The description is two sentences: first sentence clearly states the purpose and mechanism, second sentence adds a use case and output summary. No wasted 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?

Despite no output schema, the description fully explains the output format (ranked list with score, confidence, signal density per entity). It addresses the tool's complexity (multiple entities, calling another tool, ranking) completely.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by noting that the first entity is treated as the 'subject' for narrative, providing additional semantic 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 it compares AI visibility across multiple entities side-by-side, using specific verbs like 'Compare', 'Probes', 'ranks', and 'surfaces'. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (general comparison).

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

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

The description explicitly says it is useful for competitive AI-marketing audits and provides an example question. While it doesn't state when not to use it, the context is clear and implies it's for multiple entities vs. a single check.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds significant behavioral context: fans out to two services, partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed listed, and return format details. 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 well-structured: purpose first, then usage, then behavior. It's appropriately detailed with examples and edge cases. Could be slightly tighter but every sentence provides value.

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

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

Given the moderate complexity (2 params, no output schema), the description covers return format, partial failure behavior, ecosystem scope, and timing caveats. It is complete enough for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so parameters are already documented. The description adds value by mentioning scoped packages are accepted and that version defaults to latest. This is 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 is a composite check for deciding whether to add an npm package, covering license, advisories, version history, bundle size, etc. It uses specific verbs ('check') and resources ('npm package'). No sibling tool performs similar function, so distinction is clear.

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

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

Explicitly states when to use: 'when an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also specifies NPM ecosystem only and directs to alternatives for other ecosystems (PyPI/Maven/Cargo/Go via deps.dev:version directly).

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, providing a clear safety profile. The description adds only pagination detail, not substantial behavioral context beyond what annotations provide.

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

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

Three concise sentences with example queries front-loaded. Every sentence adds value, with no wasted words.

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

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

The description covers the tool's purpose and basic usage. Given the presence of an output schema and many sibling tools, it is sufficiently complete for a search tool, though it could mention result structure briefly.

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 parameters are well-described. The description adds example queries but does not significantly enhance understanding beyond the schema's field descriptions. Baseline 3 is appropriate.

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

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

The description clearly states that the tool searches published patents using CQL, returning a paginated list of publication numbers. It is specific and distinguishes from siblings like get_abstract or get_biblio, which handle different patent data retrieval tasks.

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 example queries and indicates CQL usage, giving clear context for when to use the tool. However, it does not explicitly state when not to use it or compare with alternative patent search tools among the siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint, so little needed. Description adds rich details: embedding model (BGE-base-en), cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. These go well beyond annotations.

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

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

Three sentences: first nails purpose, second explains when/why, third gives technical details. Front-loaded, no wasted words. Excellent structure.

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 3 params, no output schema, but describes output (passages with offsets and scores), limitations (200K cap, truncation), and pairing with sibling tool. Sufficient for reliable agent 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%, so baseline is 3. Description adds minimal extra: clarifies 'text' size, provides examples for 'query', and states range for 'limit'. Useful but not substantial beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb ('search') and resource ('text inside a record'). It distinguishes from siblings by contrasting with fetching entire documents and mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Explains benefits (saves context, returns relevant passages). Mentions alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.' Lacks explicit when-not, but 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?

The description contradicts the annotation idempotentHint=true because creating a new subscription each call is not idempotent (returns new ID). Per scoring rules, contradiction yields a score of 1. The description otherwise adds many behavioral details (OAuth requirement, type-specific params, delivery limitations), but the contradiction is critical.

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 packed with necessary details for complex inputs (5 types, 3 delivery channels). It is front-loaded with the core purpose, then organizes type and delivery details. While verbose, every sentence earns its place given the tool's complexity.

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

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

Given the tool's complexity (3 params, nested objects, multiple types and delivery options), the description is remarkably complete. It covers return value (subscription ID), authorization requirements, parameter examples, delivery channel behaviors, and edge cases like webhook auto-disable and SMS cap. No output schema exists, but the return value is described.

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

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

Schema coverage is 100%, but the description adds substantial meaning beyond schema: it explains each type-specific params structure, delivery channel constraints (phone verification, webhook HTTPS-only, HMAC signing, auto-disable), and required account type. This lets an agent correctly construct inputs without external knowledge.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from sibling tools like list_subscriptions and unsubscribe, which manage existing subscriptions, while subscribe creates new ones.

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 extensive usage guidance: requires Pipeworx OAuth account, lists supported subscription types with example parameters, explains delivery channels (feed always on, optional email/sms/webhook with constraints like phone verification and 10/day cap). It does not explicitly state when not to use or compare alternatives but gives clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: it returns 'category-bucketed example questions' with exact tool + argument shapes, drawn from a live catalog. It explains behavior for no arguments vs. topic focus. 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 starts with the core purpose and examples, then details the output and usage. Every sentence adds value, but it could be tightened slightly. Still well-structured and front-loaded with key info.

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 1 optional parameter and no output schema, the description is remarkably complete. It describes what the tool returns (category-bucketed examples with tool + argument shape), how to use it (no args vs. topic), and when to use it (first onboarding). It compensates well for the lack of 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?

With 100% schema coverage, baseline is 3. The description adds significant meaning beyond the schema: it lists specific valid topic values (finance, pharma, etc.) that are not enumerated in the schema, and explains the effect of omitting the parameter (cross-category spread). This makes parameter usage much clearer.

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 as the onboarding entry point for discovering what questions to ask Pipeworx. It lists specific user intents ('what can I ask?', 'give me ideas', etc.) and the resource (Pipeworx capabilities) with a specific verb ('suggest questions'). This clearly distinguishes it from sibling tools like 'ask_pipeworx' or 'discover_tools'.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools', providing clear guidance on when to use it. It also explains how to focus on a topic with the 'topic' parameter. However, it does not explicitly state when not to use it or list alternatives beyond the meta-tools reference.

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 ownership enforcement, deactivation vs deletion, and that historical events remain via recent_alerts. This adds value beyond annotations (idempotentHint, destructiveHint) by explaining state change and side effects.

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

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

Two sentences with no wasted words. Front-loaded with the action and key constraints. 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?

For a simple tool with one parameter and no output schema, the description covers purpose, usage constraints, behavioral effect, and historical data preservation. Complete and sufficient.

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

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

Schema coverage is 100% and the parameter description 'Subscription id (uuid) returned by subscribe' is adequate. The tool description adds little beyond the schema, so baseline 3 applies.

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

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

The description uses the verb 'Cancel' on resource 'subscription', specifies cancellation by id, and distinguishes from deletion by stating deactivation. It clearly indicates it is the inverse of 'subscribe'.

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

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

The description provides clear context for when to use the tool (cancel your own subscription) and notes ownership enforcement. However, it does not explicitly state when not to use it or compare to alternatives.

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

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

The description adds substantial behavioral details beyond the annotations: it explains the two verification paths (structured SEC vs. grounded pipeline), the returned verdict categories, and that it provides actual value with citation and reasoning. No contradiction with annotations.

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

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

The description is a single block of text with two paragraphs and many details; it could be more structured or front-loaded. While every sentence adds value, it is longer than necessary and could benefit from bullet points or a more concise opening.

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 parameters, no output schema), the description is quite complete: it explains the claim types, routing logic, return values (verdict, actual value, citation, reasoning). It lacks only a brief note on potential limitations or edge cases (e.g., unsupported claims).

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 meaningful context: examples for 'claim' (e.g., Apple's revenue), and for 'tolerance_pct' it explains the default behavior (implied by wording, capped at 5) and when to override (1–2 for hallucination detection). This goes beyond the schema.

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

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

The description clearly identifies the tool's purpose with specific examples like 'fact check' and 'verify the claim that...', and distinguishes it from sibling tools by explaining it replaces 4–6 sequential calls and handles two types of claims (company-financial via structured path, other via grounded pipeline).

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

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

The description explicitly states when to use the tool ('whenever the agent needs to check whether something a user said is factually correct') and explains its internal routing logic. However, it does not explicitly mention when not to use it or compare to alternatives like 'ask_pipeworx' or 'deep_research', though the context is clear.

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