World News Feeds

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that default model is free, _apiKey triggers direct Anthropic payment, and return fields (score, confidence, signals, raw_response, combined view). This adds meaningful behavioral context.

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

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

Four sentences, front-loaded with purpose and key details (default model, cost, return format, use cases). Every sentence earns its place; no wasted words.

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

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

Given moderate complexity (4 params, 1 required, no output schema but return format described), the description provides sufficient context: use cases, default model, optional key, return structure. Annotations cover safety. No gaps evident.

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 context: explains default model, that models array can include 'workers-ai' and 'anthropic', that _apiKey is optional and passed through, and that context helps disambiguate. This enriches 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 probes LLMs for entity visibility and scores it, with specific verb 'probe' and resource 'LLMs'. It mentions default model and optional Anthropic, but does not explicitly distinguish from sibling like 'scan_competitor_ai_presence', though the focus on per-model scoring is unique.

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

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

The description lists use cases (AI-marketing audits, pre-launch checks, competitive monitoring) but does not provide when-not-to-use or alternatives. Implicit guidance is present but no explicit exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about routing to many tools, returning stable pipeworx:// citation URIs, and being a fast single call on every tier. It doesn't go into failure modes or edge cases, but the annotations provide a safe baseline, so the added context is valuable but not exhaustive.

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

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

The description is front-loaded with 'PREFER OVER WEB SEARCH' and organized into purpose, examples, and escalation paths. Though long, every sentence earns its place: the examples are diverse, the alternative tools are named with their triggers, and the final note on breaking news closes the loop. This clarity justifies 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?

For a complex router with no output schema, the description still covers return format (structured answer, citations), the types of questions, and when to use it versus siblings. It doesn't describe error handling or exact response fields, but the open-world nature and the presence of sibling tools for grounded/fan-out tasks make this reasonably complete.

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

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

Schema description coverage is 100%: the 'question' property is fully described along with its aliases (q, text, input, query, prompt). The description provides example questions and clarifies the scope of accepted questions, but these are illustrative rather than adding new semantic constraints. Given full schema coverage, this matches the baseline of 3.

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

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

The description clearly states the tool's verb and resource: it routes factual questions to 5,501 tools across 1,441 verified sources and returns structured answers with citations. It also differentiates from siblings like ask_pipeworx_grounded and deep_research by noting their specific use cases.

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

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

The description explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and provides concrete triggers like 'what is', 'look up', 'find', etc. It also gives exclusions and alternatives: ask_pipeworx_grounded for verbatim evidence and deep_research for broad multi-part questions, plus specific coverage of breaking news via the *-news-feeds packs.

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

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

Beyond annotations, the description discloses the experimental nature, the possibility of live routing improvements, and the fact that it is a full working router (no fallback). This gives essential context about potential variability and the comparison process to the stable router. It does not contradict the readOnly/openWorld/idempotent hints.

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

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

Four sentences with high information density: states beta status, equivalence, usage instruction, and fallback behavior. Front-loaded and no redundancy.

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

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

The description fully explains the tool's role, current behavior, and relationship to ask_pipeworx. Since there is no output schema, mention of 'same response shape' as ask_pipeworx covers expected returns. Annotations plus description provide a complete picture.

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

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

The schema already provides comprehensive descriptions for all six parameters, including five aliases. The description adds no extra parameter detail beyond saying 'same arguments' as ask_pipeworx, which is consistent but not additive. Baseline 3 is appropriate given 100% schema 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 identifies the tool as a beta version of ask_pipeworx, a universal router that answers questions. It states exactly what it does and distinguishes it from the stable sibling by noting the experimental routing and comparison mechanism.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. It also clarifies the current state (no active candidate) so the agent knows it behaves identically at this moment.

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

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

The description goes far beyond the annotations by detailing the exact return payload (answer, evidence, confidence, source, fetched_at, refusal_reason), enumerating all possible refusal reasons, and stating that it uses 'ONLY what the tool result contains'. It also discloses the extra LLM call cost. No contradiction with the read-only/idempotent annotations.

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

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

Every sentence earns its place: the first sentence gives the core purpose, the second explains the mechanism, the third details the return format and failure modes, the fourth gives use cases, and the fifth gives a cost tradeoff. Despite being dense, it is tightly structured with no fluff or 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?

With no output schema, the description fully compensates by specifying the success and refusal return structures, including all refusal reason enums. It also covers cost, use cases, and the relationship to ask_pipeworx. For a tool of this complexity, the description is complete and leaves no critical gaps.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question'. The description adds no new parameter-level semantics beyond what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting, and the description does not need to compensate.

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 as a 'Hallucination-resistant answer mode for high-stakes reads' with a specific process (picks tool, fetches data, extracts answer) and differentiates it from sibling ask_pipeworx by emphasizing grounded extraction. It even names the sibling explicitly, making the distinction unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', and explicitly recommends against casual use: 'prefer ask_pipeworx for casual lookups'. It also defines the cost tradeoff, giving a clear decision rule.

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 true, and destructiveHint false. The description adds extensive behavioral context: resolver contract, parent_event extractor, news fallback, safety short-circuits, closed market handling, wide spread warnings, and resolution-rule risk. 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?

Front-loaded with purpose, then uses labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) for readability. Some examples are lengthy, but each adds value. Every sentence contributes to understanding, though could be slightly more compact.

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 return values: market, analysis, evidence, resolver contract, parent_event, news fields. Covers edge cases like low-confidence matches, closed markets, wide spreads, and cancellation rules. Complete for a complex tool.

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

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

Schema coverage is 100%. Description adds meaning beyond schema: explains how market parameter accepts slug, URL, or question text; depth default value and effect; include_raw purpose. Enhances understanding of parameter behavior extensively.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data in one call, with specific verb 'Research' and resource 'Polymarket bet'. It distinguishes itself from siblings like `polymarket_edges` by focusing on single-bet research with evidence packet and market-vs-model comparison.

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

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

Explicitly lists use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides guidance on when to inspect confidence fields but does not directly compare to or exclude siblings like `polymarket_arbitrage` or `polymarket_fill_risk`.

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 non-destructive. The description adds critical context: it makes one parallel call, explains data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handles fiscal year offsets, sorts by primary metric, and returns 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?

The description is comprehensive and front-loaded with trigger phrases. It includes examples, data specifics, and a performance claim. While slightly long, every sentence adds value; minor redundancy could be trimmed.

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

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

Given only 2 parameters with full schema coverage and no output schema, the description fully explains the tool's behavior: what data is returned, how it is sorted, edge cases (fiscal years), and citation URIs. It is complete for effective agent invocation.

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

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

Schema coverage is 100%, and the description adds substantial meaning: type='company' specifies data fields (revenue, net income, cash, debt) and source details (SEC EDGAR/XBRL with fiscal year handling); type='drug' specifies FAERS counts, FDA approvals, active trials. The values parameter is explained with examples (tickers/CIKs, drug names) and constraints (2–5 items).

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

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

The description uses specific verbs like 'compare', 'side-by-side', and 'pulls' to clearly state it performs parallel comparisons of 2–5 companies or drugs. It distinguishes from sibling tools like 'entity_profile' by explicitly noting it replaces 8–15 sequential 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?

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases like 'compare', 'vs', 'versus', 'rank these', and 'head to head'. It does not list when not to use, but the guidance is strong and clear.

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

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

Beyond the readOnly/idempotent annotations, the description discloses substantial behavioral traits: account requirements, parallel decomposition across 5,501 tools, the exact return packet (verbatim evidence + confidence + source + fetched_at + pipeworx:// citation), explicit gaps[] for unanswered facets, contradiction scanning, depth-specific iteration, latency expectations, and semantic excerpting behavior. It also notes that citations are only present when fetchable. This is far beyond baseline transparency.

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

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

The description is dense and long, but nearly every sentence adds necessary context given the tool's complexity. It front-loads the account requirement and key use-case distinction. The structure is somewhat run-on with semicolons, making it harder to parse quickly, but no sentence is wasted; it earns a 4 rather than a 5 solely due to its 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 the tool's complexity and the absence of an output schema, the description thoroughly covers the return format, limitations (gaps[] for unanswered facets, empty results for current news), depth behavior, latency, and prerequisites. It also explains the citation_uri guarantee and the semantic excerpting approach. There is no significant gap in contextual information.

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

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

Although the schema has 100% coverage for both parameters, the description enriches meaning significantly. It explains that 'Broad/multi-part is fine — decomposition is the point' for the question parameter, and it expands the depth enum dramatically: quick=3 facets, standard=5 with gap recovery and contradictions, thorough=8 with iterative hop and contradictions. This meaningfully exceeds the schema's own 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 opens with a precise statement: 'Grounded multi-source research across Pipeworx's 1441 STRUCTURED data sources... in ONE call' and explicitly clarifies 'this is NOT open-web search.' It further distinguishes the tool from siblings by identifying it as best for 'broad/multi-part questions over structured data' and contrasting it with ask_pipeworx for single lookups and current-news searches. The verb 'research' plus the resource scope make the purpose unmistakable.

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

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

Explicit usage guidance is provided: 'Best for broad/multi-part questions over structured data' versus 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also states that if the user is not signed in, ask_pipeworx should be used instead. This clearly covers when to use this tool, when not to, and which alternatives to choose.

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

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

Annotations already mark it as read-only and idempotent. The description adds value by explaining the return format: top-N relevant tools with names, descriptions, and full input schemas (with curated examples), and that results are ready to call directly.

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 purpose. It lists many categories which are informative but make it slightly lengthy. Every sentence contributes to usability.

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 what the tool returns (top-N tools with schemas). Together with annotations, all aspects of usage, safety, and behavior are covered.

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 context by explaining that the query is a natural language description, provides examples, and clarifies that multiple aliases are accepted.

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

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

The description clearly states the tool finds tools by describing data or task, with examples of categories (SEC filings, financials, etc.). It distinguishes itself from sibling tools as a meta-discovery tool, not a specific data tool.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance and implies 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context beyond annotations, such as the list of returned data sources, the patents sunset warning, and the parallel fan-out behavior. No contradictions.

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

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

The description is front-loaded with examples and a clear purpose statement. While it is relatively long, every sentence adds value—covering usage, output fields, and constraints. There is minimal 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 comprehensively lists all returned fields (CIK, filings, fundamentals, patents, news, LEI) and mentions potential failure modes. The two required parameters are well explained. The tool's behavior and constraints are fully covered.

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

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

Schema coverage is 100% with descriptions for both parameters. The description enriches semantics by providing concrete examples (ticker vs. CIK), clarifying that names are not supported and suggesting resolve_entity, and noting future types for the 'type' parameter.

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

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

The description uses concrete examples and states 'full cross-source profile of a US public company in ONE parallel call,' clearly distinguishing it from chaining single-pack lookups. It explicitly contrasts with alternative approaches and sibling tools like compare_entities or deep_research.

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

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

The description provides explicit when-to-use guidance ('ALWAYS PREFER over chaining...') and concrete usage examples. It also specifies when not to use (names not supported) and directs to resolve_entity as an alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral info: the tool fetches directly and falls back to a proxy if blocked, and normalizes the feed. 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 long, front-loaded with the core purpose, and 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 simple feed-fetching tool with 3 parameters and no output schema, the description covers purpose, behavior, and usage adequately. It could optionally detail 'normalize', but the current content is sufficient.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description does not add extra semantic meaning beyond the schema, maintaining 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 specifies the verb 'fetch and normalize' and the resource 'any RSS / Atom / RDF feed by URL', clearly distinguishing this tool from sibling tools like 'list_feeds' and 'read_feed'.

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 advises using 'list_feeds first for curated sources', giving explicit context for when to choose this tool. It also mentions the CF-robust fallback behavior, but lacks explicit 'do not use when' conditions.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data and the purpose of deletion, which is consistent and adds value beyond annotations.

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

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

Two sentences that are front-loaded with the main action and purpose. Every sentence provides value with no fluff or repetition.

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

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

Given the simplicity of the tool (one parameter, no output schema), the description is complete. Annotations cover behavior, and usage guidelines provide context. No gaps remain.

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

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

Schema coverage is 100% with a clear description for the single parameter 'key'. The tool description does not add additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Delete' and the resource 'previously stored memory by key'. It distinguishes itself from sibling tools like 'remember' and 'recall' by specifying its action.

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

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

Explicitly tells when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also suggests pairing with 'remember' and 'recall', providing clear context for use vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details (fetches page, extracts title/description/links, emits markdown format) without contradiction. No mention of rate limits or error states, but acceptable.

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 defines action and audience, second explains process, third lists use cases. No fluff, front-loaded with key information. Every sentence serves a purpose.

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

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

For a tool with two parameters, no output schema, and rich annotations, the description fully covers what the tool does, how it works, and what output to expect. No gaps given the complexity.

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

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

Schema coverage is 100% with descriptions for both 'url' and 'max_links'. The description references 'url' implicitly and adds context about max_links default (25) and max (50), but these are already in the schema. Minimal added value beyond schema.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and target AI crawlers. It distinguishes from siblings like 'ai_visibility_check' and 'deep_research' by focusing solely on 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 lists explicit use cases (client site indexing, personal projects, competitor auditing) but does not mention when not to use or compare directly to alternatives. Still, it provides clear context for appropriate usage.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, and destructiveHint false. The description adds no extra behavioral context (e.g., pagination, rate limits), but does not contradict annotations.

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

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

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

Mentions returned fields and references sibling read_feed. Lacks mention of pagination or limits, but sufficient given the tool's simplicity 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% with parameter descriptions already detailed. The description only rephrases 'filter by category (news) or keyword', adding no meaningful depth 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 'List the curated international / world-news feeds' with specific fields (id, title, category, source). It differentiates from the sibling read_feed by suggesting using it with 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?

Provides clear context: optionally filter by category or keyword, and directs to read_feed for an id. No explicit when-not-to-use, but sufficient for a simple list 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 already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds the return field list (id, type, etc.) and scope ('active' subscriptions, 'caller's'), providing valuable 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?

Two sentences, no unnecessary words. Purpose, return format, and usage guidance are front-loaded and succinct.

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

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

Given one optional parameter, safe annotations, and no output schema, the description fully covers what an agent needs: purpose, return fields, and usage context.

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

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

Schema covers the single parameter with description; description does not add new information about the parameter. 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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides clear guidance on when to use the tool: 'review what you're monitoring before adding more or to find an id to cancel.' Implicitly excludes other actions like creating or modifying subscriptions.

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

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

Annotations provide little (all false hints), so the description carries the burden and exceeds it. It discloses rate limiting ('5 per identifier per day'), token-based follow-up behavior, that it's free, and that it doesn't count against tool-call quota. 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 front-loaded with the core purpose. Every sentence adds useful context (usage, exclusions, token mechanics, limits). It could be slightly shorter, but structure is logical and scannable.

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

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

Given there is no output schema, the description covers return behavior (claim_token, later status), usage context, exclusions, rate limits, and operational details. It fully equips an agent to use the tool correctly without needing external info.

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 how to use claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies message length expectations. It enriches rather than repeats schema details.

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 (tell/feedback), the resource (Pipeworx team), and distinguishes itself from siblings by being the only feedback tool and explicitly noting it is for Pipeworx connection tools only.

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

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

Provides explicit when-to-use conditions: bug, feature/data_gap, praise. Also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' Offers a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists') and instructs not to paste end-user prompts. Highly actionable.

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

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

Annotations already mark as readOnly, idempotent, and non-destructive. Description adds valuable context: derived from CF analytics, no PII, caching windows (5min-1h). 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?

Three sentences efficiently cover purpose, use cases, and technical details. Front-loaded with output definition, no redundant 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?

Given a single optional parameter, no output schema, and thorough annotations, the description fully addresses what the tool does, when to use it, and how it works (source, caching, privacy).

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

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

Schema has 100% coverage with enum and description. The description adds extra insight by explaining trade-offs between window lengths (hot vs steady-state), going 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 returns top tools, packs, and call volume over a window, and lists three specific use cases. It distinguishes from sibling tools by focusing on trending/aggregate data rather than 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 enumerates three useful scenarios, such as discovering hot data sources or confirming canonical tools. Does not explicitly state when not to use, but context is strong enough for correct selection among siblings.

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

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

Annotations indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which are consistent with a read-only analysis tool. The description adds significant behavioral context: it details the scanning logic (top ~200 markets), partition checks (sum of YES prices, gap, placeholders), fill checks against live CLOB depth, and semantic anchor filtering (Jaccard similarity). It also warns when not to trade (realizable_edge_pp ≤ 0). 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 and front-loaded with the purpose, but it is verbose with implementation details such as the fill check and semantic anchor specifics. While dense and informative, it could be tightened slightly without losing clarity. Every sentence adds value, but some details could be moved or summarized.

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, no nested objects), the description is highly complete. It covers all three modes, filters (semantic anchor, partition filter), response structure (opportunities array, partition_check object, fill check), and references a complementary tool (polymarket_fill_risk). This exceeds the minimal required information for effective use.

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

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

Schema description coverage is 100%, and the description adds meaning beyond the schema: it explains what each mode does, provides examples of valid values ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), and clarifies that full URLs are accepted. This enriches the schema descriptions significantly.

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 specifies the verb (find), resource (Polymarket), and method, and distinguishes between three modes (no args, event, topic). This differentiates it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan...', 'event (recommended for a specific market): pass a Polymarket event slug...', 'topic (for cross-event scanning): pass a seed question...'. It explains the differences and when cross-event mode catches patterns that single-event misses, offering clear context for selection.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating safe read-only behavior. The description goes far beyond annotations, detailing caching ('Cached 1h at the KV level'), model logic (lognormal barrier, GDELT article-volume ratio, partition_overround with per-sport alpha), edge computation (net slippage, Kelly caps), response structure, and diagnostic filters. No contradictions with annotations.

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

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

The description is comprehensive but verbose, spanning multiple paragraphs with detailed model explanations and parameter usage. It is front-loaded with purpose and then dives into specifics. While every sentence adds value, the length may hinder quick scanning. Better organization with bullet points or shorter sections could improve conciseness.

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

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

Given 9 parameters, no output schema, and complex logic, the description is remarkably complete. It explains response structure (by_segment with three categories), edge fields (edge_pp_net, kelly_fraction, market stats, 24h-move warning), diagnostics (funnel counters, filter_skips), and Fed bets handling. The agent has all necessary information to invoke the tool and interpret results.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description adds significant context beyond the schema, such as explaining that slippage_pp accounts for Polymarket's zero fees but typical bid/ask spread, that min_partition_leg_kelly applies to per-leg Kelly inside partitions, and that Fed bets are excluded from ranking. This extra detail helps agents understand parameter tradeoffs and defaults.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), action (scan/return), and output (opportunities). It distinguishes itself from similar tools by emphasizing discovery without paging hundreds of markets and detailing three unique segments (model_driven, structural_arbitrage, concentrated_longshot). The sibling tools include polymarket_arbitrage and polymarket_edge_tracker, but this description makes its niche 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?

The description provides clear context for when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains the purpose of tradeable-edge knobs (min_liquidity, max_spread_pp) and how to interpret the response (by_segment, diagnostics). However, it lacks explicit guidance on when not to use this tool or comparisons to sibling tools like polymarket_arbitrage. The mention of Fed bets being excluded from ranking and diagnostics for empty segments adds useful 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?

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint) which already indicate a safe read operation, the description adds critical behavioral details: snapshot cache-gaps mean no scan, 60-day TTL bound, decay computed from daily closes not intraday, and the structure of response arrays. No contradiction with annotations.

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

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

Description is front-loaded with purpose and includes all necessary detail, but is somewhat verbose with multiple sentences and explanatory parentheticals. Could be trimmed slightly without losing value, but overall 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 no output schema, the description thoroughly documents the return format (tracked[], expired[], snapshot_dates[]) with field explanations. It also specifies limits (60-day TTL, snapshot gaps) and caveats (decay from daily closes). This is complete for an agent to use correctly.

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

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

Schema covers 100% of parameters, so baseline is 3. Description adds context: default values (days=14, window='1wk'), clamping behavior (days clamp 2-30), and enum options for window. This is helpful beyond the schema, earning an extra point.

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

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

Description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question about edge age. It distinguishes from siblings by focusing on time-series behavior versus snapshots. The verb 'answers' and resource 'edge telemetry' are specific and unambiguous.

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

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

Description explicitly states the use case: 'answers how long has this edge existed and is it shrinking?' and provides a trade-off example (fresh vs old wide edge). It does not explicitly contrast with sibling tools like polymarket_edges or specify when not to use, but the context is clear enough for an agent to infer appropriate usage.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive nature. Description adds significant behavioral context: walks the ladder, returns detailed fill metrics and verdict, and warns about partial basket fills converting arb into directional risk. Does not contradict annotations.

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

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

Description is detailed and well-structured with clear sections for single-market vs basket, bolded key terms, and front-loaded with the core purpose. Every sentence provides value, though length is justified by complexity.

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

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

Despite no output schema, description fully enumerates return fields for both single-market and basket modes, explains risk (thin legs, directional exposure), and covers edge cases. Complete enough for a complex tool with four parameters.

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

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

Schema description coverage is 100%, but description adds meaning beyond schema: explains that market and event are mutually exclusive, clarifies default side logic for basket mode ('auto from partition sum'), and specifies interpretation of size_usd for each mode (spend vs target proceeds vs settlement notional).

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

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

Description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes between single-market and basket modes. It explicitly tells the agent to use this before acting on signals from sibling tools polymarket_arbitrage and polymarket_edges, differentiating 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?

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides rationale about uncapturable theoretical overround and risk of unhedged directional positions from partial basket fills.

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 no destructiveness. The description adds extensive behavioral context: two compatibility_warning scenarios, temporal_alignment check, skipped_cross_type/subtype counters, and the caution that real spreads are rarer than the shortcut list suggests. 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 with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the purpose. It is verbose but every sentence adds essential detail. Slightly longer than ideal but remains readable and informative.

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 (cross-venue matching, multiple modes, safety fields) and lack of output schema, the description fully compensates by detailing response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, skipped counters, temporal_alignment). All aspects needed for correct invocation are covered.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds significant value beyond schema: lists the exact topic shortcut values ('fed', 'btc', etc.), explains override behavior, and provides example ticker formats. This makes parameter usage clear and actionable.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two modes ('topic' shortcuts and explicit tickers) and distinguishes this from siblings like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

Provides explicit guidance on when to use each mode: 'topic' for pre-mapped macro shortcuts, explicit 'kalshi_event_ticker' and 'polymarket_event_slug' for custom pairings. Also warns that most pre-mapped topics return compatibility warnings, advising that pre-mapped does not equal tradeable. This helps the agent decide when the tool is appropriate.

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 it returns normalized items (title, link, published, summary) and optional keyword filtering. This is useful but not extensive; the annotations cover the safety profile.

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

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

Two sentences, no wasted words. The main action is front-loaded, and the optional filter is mentioned clearly. Every sentence earns its place.

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

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

Given the simple parameters and no output schema, the description is fairly complete. It covers what the tool does, input requirements, and output structure. It could mention pagination or ordering, but not necessary for 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?

Schema description coverage is 100%, so the description adds minimal value beyond the schema. The description mentions optional keyword filtering, which matches the 'query' parameter, but does not elaborate on format or behavior.

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 reads a curated feed by id, returns normalized items, and optionally filters by keyword. It distinguishes from siblings like list_feeds (which lists feed ids) and fetch_feed (which might fetch raw feed). The verb 'read' and resource 'feed' are specific.

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 calling list_feeds first to get feed ids, and mentions optional keyword filtering. It does not explicitly state when not to use it or compare to sibling tools, but the context is clear enough for an AI agent.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds scoping to user identifier, behavior when key omitted (list keys), and pairing with other tools. No contradictions.

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

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

Three sentences, front-loaded, no fluff. Every sentence adds essential information.

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

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

Provides enough context for a simple retrieval tool: scope, pairing, and what it returns. No output schema, but return values (value or list of keys) are implied. Good for the complexity level.

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

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

Schema covers the parameter with 100% coverage. Description adds value by explaining the effect of omitting the key (list all keys) and providing example usages.

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

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

Description clearly states the tool retrieves a saved value or lists keys, with concrete examples of stored context (ticker, address, notes). It distinguishes from siblings remember and forget by stating it's for retrieval.

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

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

Explicitly says when to use: to look up stored context without re-deriving. Mentions scoping to identifier and pairing with remember/forget. Lacks explicit when-not-to-use, but overall clear.

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

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

Beyond annotations (readOnly, idempotent), explains that mark_read flags events as read to affect subsequent calls, and that the feed is persisted. No contradictions with annotations.

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

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

Two sentences with no extraneous information. Main verb and resource are front-loaded, and each sentence adds value.

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

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

Covers return structure and key parameters. Lacks error handling or rate limit info, but is adequate given annotations and optional parameters.

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

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

Schema coverage is 100%, but description adds value by giving a concrete example for type ('sec_8k') and explaining the effect of mark_read. This helps the agent select appropriate parameters.

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

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

Clearly states it pulls fired events from the subscription feed, specifying return fields (source, citation_uri, payload). Distinguishes from generic feed tools like fetch_feed or read_feed by focusing on subscription alerts.

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

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

Provides context that polling works fine and mentions an alternative REST endpoint, but does not explicitly state when to use this tool vs. siblings (e.g., fetch_feed, read_feed) or 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?

Annotations indicate readOnly, idempotent, and non-destructive. The description adds important behavioral context: parallel calls to multiple sources, fallback behavior (GDELT→GNews), soft-fail on USPTO, and return structure. This goes beyond annotations, though an output schema would provide even more clarity.

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

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

The description is well-structured with a front-loaded list of example queries. It is relatively long but every sentence adds value, detailing sources, parameters, and fallback. Minor redundancy could be trimmed, but overall it is informative and efficient.

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

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

Given the tool's complexity (multi-source, fallback, multiple parameters) and lack of output schema, the description covers sources, parameter formats, return structure overview, and sibling tool differentiation. It lacks detailed return object fields, but is still fairly complete for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds further meaning by explaining `since` with examples and typical monitoring values, and clarifying `value` accepts ticker or CIK. This provides significant added value over the schema alone.

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

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

The description explicitly states the tool returns a change feed for a company in a recent time window, listing example queries and sources. It also distinguishes from the sibling tool `entity_profile`, making the purpose very clear.

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

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

The description provides explicit guidance on when to use this tool (temporal change feed) and when not to (use `entity_profile` for static profile). It also explains parameter usage with examples like `since` formats.

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 key behavioral traits beyond annotations: persistence details (authenticated users get persistent memory, anonymous sessions retain 24 hours), key-value pair scoping by identifier. Annotations already provide idempotentHint=true and destructiveHint=false, and description adds valuable context without contradiction.

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

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

Three concise sentences with no filler. Front-loaded with clear action verb 'Save', followed by usage guidance and behavioral details. 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 key-value storage tool with no output schema, the description covers all necessary aspects: purpose, usage, behavior, persistence, and pairing with siblings. No gaps remain.

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

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

Schema coverage is 100% with good parameter descriptions. The description adds meaning beyond schema by explaining scoping ('by your identifier') and providing naming conventions ('subject_property', 'target_ticker'). Slight improvement over baseline.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later' with specific examples (resolved ticker, target address, user preference, research subject). It distinguishes from siblings recall and forget, making the purpose unmistakable.

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

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

Provides explicit guidance on when to use: 'Use when you discover something worth carrying forward' and pairs with recall/forget. No ambiguity about context or alternatives.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior. The description adds behavioral context by noting internal cascading lookups, auto-disambiguation, and citation URI generation, which goes beyond the structured annotations and helps the agent understand how the tool behaves.

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

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

The description is detailed but well-structured, leading with example queries, then clear guidance, followed by per-type specifics. Each sentence contributes useful information, though slightly verbose for a lookup tool, it remains appropriately sized 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?

For a tool with no output schema, the description thoroughly explains the return fields for both entity types, including citation URIs. It also covers accepted input forms and disambiguation behavior, making it complete for selecting and invoking the tool correctly.

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

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

Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description adds extra value by showing example values, accepted formats, and providing return semantics (e.g., company returns ticker + CIK + company_name), which enriches understanding of what the parameters represent and how they affect output.

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 action: resolving a user-spoken name to a canonical identifier. It distinguishes itself from siblings by specifying the output types (ticker, CIK, RxCUI) and explicitly stating it's for when 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?

It provides explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also lists supported types and input variations, making it clear when to invoke this tool versus alternatives like entity_profile or compare_entities.

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, idempotent, non-destructive. The description adds that it probes each entity with ai_visibility_check, ranks by score, and surfaces most/least recognized. No contradictions.

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

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

Two sentences front-load the core action and output, then provide a use case and example. 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?

Given no output schema, the description adequately describes the ranked list with score, confidence, signal density. Parameters are well-covered in the schema. Leaves no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as subject and rest as competitors, which goes beyond the schema's simple description.

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

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

The description clearly states it compares AI visibility across multiple entities, using ai_visibility_check, and returns a ranked list. It distinguishes from siblings like ai_visibility_check (single probe) and compare_entities (generic).

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

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

The description provides a clear use case (competitive AI-marketing audits) and an example. It implies when to use this tool over ai_visibility_check (multiple entities) but does not explicitly state when not to use or name alternatives.

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

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

Discloses important behavioral traits beyond annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed list when timeouts occur. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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 moderately long (3-4 sentences) but every sentence adds value. Front-loaded with purpose. Minor redundancy (returns summary block) but overall efficient for the detail provided.

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

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

Given no output schema, description fully explains return structure (summary block, per-advisory, links, alternative versions). Also covers error handling (partial failures, sources_failed). Complete for a read-only composite tool.

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

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

Schema coverage is 100% (both parameters described). Description adds value by noting default version behavior and that scoped packages are accepted, which is not in schema. Slightly above baseline for high schema 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?

Description uses specific verbs ('scan', 'check') and clearly identifies the resource (npm package). It goes beyond a vague purpose by stating the composite nature across deps.dev and bundlephobia, covering license, advisories, bundle size, etc. Distinguishes from siblings by specifying it's an npm-focused composite check.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also clarifies ecosystem constraints (NPM only in v1) and directs to deps.dev:version for other ecosystems. Provides clear context and alternatives.

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

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

Discloses technical details beyond annotations: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging. All consistent with readOnlyHint, idempotentHint, etc. No contradictions.

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

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

Well-structured with key info front-loaded. Each sentence adds value, though slightly detailed. Could be more concise but still clear and organized.

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

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

No output schema, but description explains return values (passages with offsets and scores). Covers cap, truncation, and pairing with sibling. Complete for a 3-param read-only tool.

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

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

Schema coverage 100% but description adds value: examples for query field, mentions 200K char cap for text, default range for limit. Goes beyond schema descriptions.

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

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

Clearly states it performs semantic search inside a fetched record, using specific verb 'semantic search INSIDE a fetched record' and distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded. No tautology.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides alternative strategy with ask_pipeworx_grounded. Also gives example use cases like SEC 10-K, article, long tool result.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds significant behavioral details: returns subscription ID, requires OAuth, caps on SMS (10/day), webhook signing, auto-disabling after failures, and the always-on feed behavior. 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, front-loading the core purpose and return value, then detailing requirements, types, and delivery options. It is somewhat lengthy but every sentence adds value; no waste.

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, no output schema), the description covers all necessary context: purpose, authentication, parameter details with examples, delivery channels, and constraints. It is fully adequate for an agent to use correctly.

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

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

Schema coverage is 100%, but the description enriches each parameter with examples (e.g., sec_8k: {ticker:'AAPL', items:['5.02']}), explains type-specific filters, and details delivery channels with usage notes (e.g., phone must be pre-verified). This adds 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 ('Create'), the resource ('a proactive monitoring subscription to a live-data event stream'), and the return value ('Returns the new subscription id.'). It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by focusing on creation of a subscription.

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

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

The description provides explicit context: requires a Pipeworx OAuth account (not anonymous/BYO), lists supported types and their parameter formats, and mentions delivery options. While it doesn't explicitly state 'when not to use' this tool, the purpose is clear and it implicitly differentiates from 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: it returns example questions with tool+argument shapes drawn from a live catalog, and serves as an onboarding entry point. 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 concise for the amount of information conveyed. It front-loads the purpose and usage triggers, then explains output and parameters. Every sentence adds value, though a minor reduction in length could be possible.

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

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

Given no output schema, the description adequately explains the return format: category-bucketed example questions with exact tool+argument shapes. It also mentions the source (live catalog) and the tool's role as an onboarding entry point, making it complete for a simple 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 useful context: examples of topic values ('finance', 'pharma', 'betting') and explains behavior when omitted ('cross-category spread'). This enhances understanding beyond the schema.

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

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

The description uses specific verbs ('returns', 'suggest') and resource ('example questions') and lists multiple usage triggers (e.g., 'what can I ask', 'show me examples'). It clearly distinguishes its role as an onboarding entry point 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?

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides usage tips: call with no arguments for full spread, pass `topic` for focus. Implicitly advises against using other tools until onboarding is complete.

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?

Describes that the row is deactivated (not deleted) and historical events stay available, adding context beyond annotations like readOnlyHint=false and destructiveHint=false.

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

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

Two concise sentences with front-loaded action and behavioral detail, 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?

Covers all essential aspects for a simple tool: what it does, ownership constraint, deactivation behavior, and impact on historical data.

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 param 'id' described. The description adds that the id is returned by subscribe, providing useful linkage beyond the schema.

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

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

The description clearly states 'Cancel a subscription by id', with a specific verb and resource, and distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly says ownership is enforced, so you can only cancel your own subscriptions. This tells when to use and when not to, providing 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 indicate read-only, idempotent, and open-world behavior. The description adds meaningful context: the two-pipeline operation (structured vs. grounded), the verdict types returned, citation format, and tolerance behavior. This goes beyond what annotations provide.

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

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

The description is a single, dense paragraph that efficiently conveys purpose, usage, architecture, and return values. It front-loads common natural-language triggers and is free of redundancy. Every sentence adds value.

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

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

Given the tool's complexity (two pipelines, tolerance parameter, multiple verdict types) and lack of output schema, the description fully covers the return values (verdict, actual value, citation, reasoning), operational paths, and the role of the tolerance parameter. It also notes the efficiency improvement, making it complete for agent decision-making.

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

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

Input schema covers 100% of parameters with descriptions. The description adds value by explaining the tolerance_pct parameter's override behavior and default (implied by wording, capped at 5), and clarifies the claim parameter's natural-language nature. This enriches 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 opens with clear natural-language triggers ("Is it true that…", "fact check") and explicitly states it verifies claims against authoritative sources. It distinguishes between company-financial claims using SEC XBRL and other claims via a grounded pipeline, differentiating it from sibling tools like 'deep_research' or 'ask_pipeworx_grounded'.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing explicit context. It does not explicitly state when not to use it, but the focus on factual claims implies exclusion of subjective questions. It also mentions efficiency gains over sequential calls, adding helpful guidance.

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