Design Feeds

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

Annotations already provide readOnlyHint, idempotentHint, and openWorldHint. Description adds behavioral context: default model is free, Anthropic requires own key, and return structure includes per-model {score, confidence, signals, raw_response} plus combined view. No contradictions. This additional info helps an agent understand side effects (none) and key requirements.

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

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

Description is concise (two dense sentences plus a list) with no wasted words. It front-loads the core action and then adds parameter details and use cases efficiently.

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 (4 parameters, no output schema), the description fully explains its purpose, parameters, return structure, and typical use cases. It provides enough information for correct invocation without additional context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds meaningful guidance: explains that 'models' default to workers-ai, that '_apiKey' is only needed for Anthropic, and that 'context' disambiguates common names. This goes beyond schema descriptions and helps correct parameter usage.

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

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

Description clearly specifies the verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100) per model'. It distinguishes from sibling tools by focusing on brand visibility across multiple models, not Pipeworx-specific or entity profile tools. Use cases are explicitly listed: AI-marketing audits, pre-launch brand checks, competitive monitoring.

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 states when to use this tool via listed use cases. It does not explicitly mention when not to use or provide alternatives, but the purpose and scope are clear enough for an agent to infer appropriate contexts.

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

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

With annotations already declaring readOnlyHint, openWorldHint, idempotentHint, and non-destructive, the description adds substantial context: it routes to 5,372 tools, fills arguments, returns structured answers with stable citation URIs, works on every tier, and handles news via live feeds. It also hints at a potential limitation by recommending the grounded variant for hallucination-resistant answers.

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-loaded with the key 'PREFER OVER WEB SEARCH' directive, and includes concrete examples and alternatives. It is slightly verbose with repeated emphasis on 'START HERE' and 'default entry point', but every part contributes to selection and invocation guidance.

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

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

Despite having no output schema, the description explains what the agent can expect: a structured answer with stable pipeworx:// citation URIs. It covers the tool's scope, examples, usage triggers, and escalation paths, making it complete enough for an agent to decide when and how to use it.

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

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

The input schema already covers all parameters with 100% description coverage, including the primary 'question' parameter and its aliases. The description adds examples and trigger phrases but does not materially extend parameter semantics beyond what the schema provides. Baseline 3 is appropriate given the 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?

The description clearly states what the tool does: routes questions to the right underlying tool among 5,372 options and returns structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point for factual questions.

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

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

The description explicitly says to prefer this tool over web search, lists trigger phrases and examples, and provides clear guidance on when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions). This is exemplary usage guidance.

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

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

Annotations already declare read-only and idempotent hints, so the bar is lower. The description adds meaningful context about dynamic behavior (candidate routing improvements enabled live), the current inactive candidate state, and that it is a full working router, not a stub. This goes beyond annotation basics.

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

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

The description is four sentences, each serving a distinct purpose: identity, current state, usage, and clarification. It is slightly dense but not wasteful, and front-loads the core function before introducing beta-specific details.

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

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

For a beta router with no output schema, the description explains its relationship to the stable tool, experimental status, and current behavior. It references the stable tool's response shape rather than explaining it, which is acceptable given sibling context. Slight gap in not detailing routing behavior changes when a candidate is active.

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

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

Schema coverage is 100% for all six alias parameters, so the baseline is 3. The description adds 'same arguments' as the stable tool but no further parameter-specific meaning, leaving the schema to handle semantics.

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

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

The description clearly identifies this as the beta version of ask_pipeworx, describing it as an identical universal router with the same tools, arguments, and response shape. It explicitly distinguishes from the stable sibling by highlighting experimental routing improvements, making the tool's purpose unambiguous.

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

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

It provides clear usage context by stating 'Use it exactly like ask_pipeworx when you want the newest routing,' which implies the stable tool is the alternative. However, it lacks an explicit when-not-to-use condition, such as avoiding production environments, so it falls short of a full 5.

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

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

The description discloses detailed behavioral traits beyond the annotations: extracts answers only from tool results, returns evidence as verbatim quotes, lists five possible refusal reasons, and explicitly mentions the extra LLM call cost. Annotations (readOnly, idempotent) align with the description, 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?

Every sentence earns its place: purpose, process, success return shape, refusal return shape, use-case guidance, and cost trade-off. The structure is dense and front-loaded, with no fluff.

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

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

Given no output schema, the description fully carries the burden of explaining return values (answer, evidence, refusal_reason), failure modes, and behavioral guarantees. It is complete for a complex tool with many routing and refusal scenarios.

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 has 6 parameters but all are aliases for the same question field, and schema description coverage is 100%. The description adds no semantic nuance beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states this is a 'Hallucination-resistant answer mode for high-stakes reads' that routes to tools and extracts answers grounded only in the tool result. It explicitly distinguishes itself from its sibling ask_pipeworx by emphasizing refusal behavior and evidence extraction.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' It also contrasts with the alternative: 'prefer ask_pipeworx for casual lookups,' citing the extra LLM call cost.

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

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

The description goes far beyond annotations by explaining internal mechanics: resolver contract, parent event extractor, news fallback, safety short-circuits, resolution-rule risk, and tradeability. No contradictions with annotations (readOnlyHint=true, 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?

The description is very thorough but overly long (500+ words). While front-loaded with purpose, the excessive detail in sections like RESOLVER CONTRACT and RESOLUTION-RULE RISK could be streamlined without losing essential guidance.

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

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

Given the complexity of the tool and no output schema, the description covers all essential aspects: input formats, processing logic, output structure (response shapes), error states (low_confidence_match, market_closed_or_inactive), and safety warnings. It is highly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for the 'depth' parameter (quick vs thorough fan-out) and 'include_raw' (payload size control), which enhances understanding beyond the schema definitions.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb 'Research' and resource 'Polymarket bet'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edges by explicitly stating use cases ('should I bet on X', etc.) and providing detailed fan-out examples.

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

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

The description provides extensive usage guidance, including when to use the tool, how inputs are resolved, fan-out behavior, and when to inspect fields like market_match_confidence. It also covers edge cases like low-confidence matches, closed markets, and wide spreads.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is a single efficient paragraph, front-loaded with trigger phrases and key functionality. Every sentence adds value, though it could be slightly more structured (e.g., separate bullet points for types). Still, it is concise 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's complexity (two entity types, multiple data sources, no output schema), the description covers return format (paired data + citation URIs), sorting behavior, data sources, and edge cases (off-calendar fiscal years). The parameter schema is well-documented, making the description complete for agent usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains what 'company' and 'drug' types retrieve (financial vs. adverse events data), provides examples for 'values' (tickers vs. drug names), and clarifies the count bounds.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs, with specific trigger phrases like 'compare X and Y' and 'rank these companies'. It distinguishes from sibling tools by noting it replaces 8-15 sequential lookups and is preferred over single-pack lookups.

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

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

Explicit when-to-use cues are given (natural language patterns like 'X vs Y'). It also states 'ALWAYS PREFER over sequential single-pack lookups' and specifies entity count limits (2-5), guiding proper invocation.

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

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

Despite having annotations (readOnly, openWorld, idempotent), the description adds substantial behavioral disclosure beyond them: account/plan requirements, decomposition into facets, parallel routing to 5,372 tools, findings packet structure (verbatim evidence+confidence+source+fetched_at+citation, gaps[], contradictions[], hop field), semantic excerpting, latency expectations, and a 'never invented' guarantee. This far exceeds what annotations provide and fully sets agent expectations.

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 (~250 words) but dense with critical operational facts. It is front-loaded with the account requirement, then flows from what it is to when to use, then to behavioral details. Minor redundancy appears (gaps[] mentioned four times, contradictions twice), and some sentences are complex. A trim of a few clauses would improve conciseness, but the overall structure is logical and not wasteful.

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

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

This is a high-complexity tool with no output schema, so the description must explain return values on its own. It thoroughly covers the findings packet format, gaps[], contradictions[], citation URIs, semantic excerpting, latency, and error behavior (empty gaps for off-catalog topics). For a research orchestrator, every important operational aspect is addressed, making it impossible to misuse due to missing 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 already describes all parameters (100% coverage), including enum meanings for depth. The description adds value by linking depth to account requirements (thorough is paid), clarifying the default depth, and reinforcing behavioral consequences (gap recovery, contradiction scan). Some redundancy exists with the schema, but the added account gating and the explicit 'broad/multi-part is fine' for question make it more than 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 explicitly states 'Grounded multi-source research across Pipeworx's 1397 STRUCTURED data sources' in one call, with a specific verb (research) and resource (structured data sources). It also distinguishes itself from siblings by contrasting with ask_pipeworx ('NOT open-web search', 'not one LLM call') and by specifying its ideal use case for broad/multi-part questions. This is a clear, specific purpose that no sibling tool shares.

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?

Offers explicit when-to-use scenarios: 'Best for broad/multi-part questions over structured data' and when not to use: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives a fallback if not signed in. These are concrete, actionable alternatives, not vague hints.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds value by noting returns are ready to call directly with full schemas and examples, no second lookup needed.

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 purpose, then domains, then return details. It is slightly long but each sentence adds value. Could be trimmed slightly but remains clear.

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

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

No output schema, but the description fully explains what is returned (top-N tools with names, descriptions, schemas, examples, call-ready). Covers aliases and usage guidance. Complete 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%. The description mentions natural language query and aliases, but the schema already describes these. No additional meaning beyond schema.

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

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

The description clearly states the tool finds tools by describing data or task, listing many domains. It distinguishes from sibling tools which are specific tools, making this the discovery gateway.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear when-to-use and implied when-not-to-use.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent. The description adds important behavioral details: it fans across multiple sources, notes the sunset of PatentsView API with soft-fail behavior, fallback from GDELT to GNews, and the constraint that names are unsupported. No contradictions.

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

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

The description is somewhat lengthy but well-structured: begins with example queries, then a concise summary, followed by detailed return fields and constraints. Every sentence adds information, though it could be trimmed slightly for agents that prefer brevity.

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 (multiple data sources) and the simple schema (2 parameters, no output schema), the description provides a fairly complete picture of what the tool returns: CIK, company_name, recent_filings, fundamentals, patents, news, LEI. It also mentions fallbacks and limitations, which helps in understanding expected output.

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

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

Schema coverage is 100% and schema descriptions are already present. The description adds value by explaining the limitation of the 'type' parameter (only 'company' supported) and clarifying the acceptable formats for 'value' (ticker or zero-padded CIK) with examples. This goes beyond the schema.

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

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

The description starts with diverse example queries (e.g., 'Tell me about X', 'research Acme') and clearly defines the tool as providing a 'full cross-source profile of a US public company in ONE parallel call'. It explicitly distinguishes from chaining single-pack lookups and from sibling tools like compare_entities or resolve_entity.

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

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

The description explicitly states when to use (holistic view of a company) and when not to ('Names not supported — use resolve_entity first'). It also advises preferring this tool over sequential single-source searches, providing clear contextual guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds value by revealing normalization behavior and a proxy fallback mechanism for blocked sources. No contradictions or missing critical 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?

Two sentences, no filler. The first sentence covers core purpose and normalization; the second adds robustness and usage guidance. Front-loaded and efficient.

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

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

For a simple fetch tool with well-documented parameters and good annotations, the description covers key aspects: what it fetches, normalization, proxy fallback, and guidance. Lack of output schema is mitigated by the tool's simplicity, but a brief note on return format would improve completeness.

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

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

Schema coverage is 100%, with each parameter already described clearly. The description does not add additional semantic nuance beyond what is in the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb (fetch) and resource (RSS/Atom/RDF feed by URL), and distinguishes from siblings by specifying normalization and the suggestion to use list_feeds for curated sources. It covers feed types and proxy fallback, making the tool's scope unambiguous.

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

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

Explicitly advises to 'Use list_feeds first for curated sources,' which provides clear context for when this tool is appropriate versus siblings. However, it does not explicitly state when not to use it or mention alternatives beyond list_feeds.

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 aligns with annotations (destructiveHint=true, readOnlyHint=false) by stating it deletes a memory. It adds useful behavioral context about why you might delete (stale data, sensitivity), which annotations alone do not 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 three sentences with no wasted words. The purpose is front-loaded, followed by usage guidance and sibling references. 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 tool (one required param, no output schema), the description fully covers purpose, usage, and behavioral context. No gaps remain for an agent to invoke it correctly.

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

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

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

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

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

The description clearly states the verb 'Delete' and the resource 'memory by key', making the tool's purpose unambiguous. It distinguishes from sibling tools 'remember' and 'recall', which are for creating and retrieving memories.

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 the tool (stale context, task done, clear sensitive data) and pairs it with related tools 'remember' and 'recall'. This provides clear guidance on selection and 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?

Discloses that the tool fetches the page, extracts title/description/key links, and outputs standard markdown. Annotations already declare read-only and idempotent; description adds fetch and extraction behavior, though could note potential network issues.

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 plus bullet list of use cases. No filler; main purpose and output format front-loaded.

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

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

Explains output format and contents sufficiently given no output schema. Covers extraction detail and deployment location. Could mention error handling for unreachable URLs, but adequate for typical use.

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

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

Both parameters are fully described in the input schema (100% coverage). Description adds no new meaning beyond schema descriptions, so baseline 3 is appropriate.

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

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

Specific verb ('generate'), resource ('llms.txt file'), and context ('for any URL so AI crawlers can index the site cleanly'). Clearly distinguishes from sibling tools like 'scan_competitor_ai_presence' which focus on analysis rather than 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?

Explicitly lists three use cases: getting client site indexed, drafting own llms.txt, auditing competitor. Does not provide when-not-to-use or alternative tool guidance, but context is clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about curated feeds and returned fields but no behavioral traits beyond annotations, which is acceptable as annotations cover safety.

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

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

Two sentences with no wasted words. First sentence defines scope and output, second sentence covers options and alternative tool.

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

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

Tool is simple with 2 optional params and no output schema. Description mentions returned fields, which is sufficient. No mention of pagination/limits, but not critical 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 coverage is 100%, but description adds the allowed category values ('design, photography') not present as enums in schema, enhancing semantic understanding.

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

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

Clearly states 'List the curated design & photography feeds' with specific fields returned, and distinguishes from sibling read_feed by noting 'Pass an id to 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?

Provides guidance on optional filters and directs to read_feed for a specific feed. Could be more explicit about when not to use, but adequate 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 readOnly, idempotent, non-destructive. The description adds details about returned fields, but lacks info on pagination limits. Score high as annotations carry the burden.

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

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

Three sentences, no redundancy. Every sentence adds value: purpose, return fields, and usage guidance.

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 single optional parameter, rich 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 coverage is 100% with description for the only parameter. The tool description adds no further parameter detail, meeting baseline but not exceeding.

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

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

The description clearly states the action 'List the caller's active subscriptions' and lists specific return fields (id, type, params, etc.). This differentiates it from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This helps the agent decide between this 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 that feedback is read daily, affects roadmap, rate-limited to 5 per identifier per day, and doesn't count against tool-call quota. Annotations lack such detail, so description adds significant 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?

A single concise paragraph of 4 sentences that front-loads the core purpose and provides all necessary guidance without unnecessary words.

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

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

For a feedback tool with no output schema, the description covers purpose, usage, behavior, and limitations completely. No missing information.

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

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

Schema coverage is 100% and already explains the parameters. The description adds context like 'Describe the issue in terms of Pipeworx tools/packs' but does not substantially enhance parameter meaning beyond the schema.

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

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

The description clearly states the tool sends feedback about Pipeworx tools/packs, listing specific types (bug, feature, data_gap, praise). It distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback, not questions.

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: for bugs, missing features, data gaps, or praise. Provides instructions on what to include and what to avoid (e.g., not pasting user prompts). Also mentions rate limits and quota.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable context: data is derived from CF analytics-engine, no PII, just counts; caching behavior (5min-1h depending on window). No contradictions.

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

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

Description is front-loaded with the core output, followed by bullet-point use cases, then technical details. Every sentence earns its place; no redundancy. Efficient and well-structured.

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

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

Despite no output schema, the description explains return contents (top tools, top packs, total call volume) and caching behavior. This is complete for a simple, read-only tool with excellent annotations and a single parameter.

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

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

Schema coverage is 100% for the single parameter 'window', with enum and description. The description reinforces the intent (shorter windows for hot trends, longer for steady-state demand) but does not add substantive meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool returns top tools, packs, and total call volume over a configurable window. It lists three specific use cases, distinguishing it from siblings like discover_tools or ask_pipeworx. The verb 'returns' identifies the action, and the resource is clearly the trending usage data.

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

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

Three explicit use cases are given: discovering hot data sources, confirming canonical tool choice, and aligning use case with agent needs. While it doesn't explicitly state when not to use, the scenarios cover appropriate contexts well. No alternative or exclusion guidance is provided, but the description's clarity suffices.

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

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

The description goes far beyond annotations by detailing internal logic: partition_sum checks with >3pp deviation, Jaccard similarity threshold of 0.30, placeholder filtering, fill check against CLOB depth, and response structure. It adds significant behavioral context without contradicting the readOnlyHint, openWorldHint, or idempotentHint annotations.

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

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

The description is well-structured, starting with the core purpose, then detailing modes, followed by technical details. It is somewhat lengthy but every sentence adds value. Minor redundancy (e.g., explaining partition_check twice) slightly reduces conciseness, but overall it is efficient for the complexity involved.

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 covers response fields (opportunities array, partition_check details), behavior for each mode, constraints (similarity threshold, placeholder filter), and cross-references to sibling tools for additional functionality (fill risk). It is complete for an analysis tool of this complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds substantial meaning: it explains that `event` accepts slugs or full URLs and is recommended for specific markets, while `topic` is a seed question for cross-event scanning, and it also describes the default behavior with no arguments. This enriches the parameter semantics beyond the schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges, polymarket_edge_tracker, and polymarket_fill_risk by detailing unique methods and modes.

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 specifies when to call with no args (trending scan), with `event` (single-event partition check), or with `topic` (cross-event scan). It explains the benefits of each mode and refers to polymarket_fill_risk for custom sizing, providing clear alternative guidance.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, which the description reinforces. It adds extensive behavioral details: cache behavior ('Cached 1h at the KV level'), model specifics (FRED log-returns, GDELT, partition_overround with per-sport α), edge calculation (edge_pp_net after slippage, kelly capped at 0.25, 24h-move warning), and diagnostic sections. No contradictions.

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

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

The description is a dense block of text but logically organized: purpose, three segments, per-opportunity fields, tradeable-edge knobs, response top-level. While informative, it could be broken into sections or bullet points for readability. Each sentence is meaningful, but length slightly hurts scannability.

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

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

With 9 parameters, no output schema, the description fully explains the response structure (by_segment, fed_note, _diagnostics) and details every field (edge_pp_net, kelly_fraction, market.liquidity, etc.). It covers cache behavior, model assumptions, and knob effects. No obvious gaps remain for an agent to understand inputs and outputs.

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

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

All 9 parameters are described in the schema (100% coverage), and the description adds rich context beyond name/type. For example, min_kelly explains 'Minimum half-Kelly fraction... Skips opportunities that are too small to bet sensibly even if the edge is large.' Slippage_pp discusses execution cost and Polymarket's zero fees. Every parameter gets practical guidance.

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

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

The description clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the verb (scan, return), resource (Polymarket markets), and distinguishes from sibling tools like polymarket_arbitrage and polymarket_edge_tracker by focusing on broad opportunity discovery.

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

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

The description explicitly says 'Built for "what should I bet on today"' and explains the three segments and their use cases (e.g., concentrated_longshot is rare-by-design). It does not directly state when not to use it, but the context and sibling names imply its role as a discovery tool versus analysis tools.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context: data from daily snapshots, 60-day TTL, response structure, and that decay is based on daily closes, not intraday. 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 with clear sections and front-loaded with purpose. While somewhat long, every sentence adds value, explaining response fields and limits without unnecessary fluff.

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

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

Given no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]), including field meanings and sign interpretation. It also covers limits like TTL and gap handling, making it comprehensive.

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

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

Schema coverage is 100% and schema descriptions are already detailed. The tool description adds context by explaining the purpose of days and window, but largely repeats schema info, so only marginal added value.

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

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

The description clearly defines the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering a specific question about edge age and trends. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking.

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

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

The description explains what the tool answers and includes limits, but does not explicitly state when to use or not use it compared to alternatives. The context is clear enough for an AI 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 declare readOnlyHint and idempotentHint, making the tool safe and non-destructive. The description adds valuable behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap, slippage, etc.), and warns about forced directional risk. 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 relatively long but well-structured with headings (SINGLE-MARKET, BASKET) and bullet lists. Every sentence provides necessary detail; the length is justified by the complexity of the two modes. It is front-loaded with the core purpose.

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

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

Given the tool has no output schema, the description fully covers all return fields for both modes (e.g., shares_filled, max_fillable_usd, profit_usd, thin_legs). It also explains edge cases like partial basket fills creating directional risk, making it complete for an agent to understand behavior.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond parameter descriptions: it explains the default for side (auto based on partition sum), the interpretation of size_usd for buys vs sells (max spend vs target proceeds), and the dual behavior of market vs event parameters. This helps the agent select correct parameters.

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

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

The description 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 differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly stating it is a prerequisite before acting on their signals.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books is not capturable, partial fills lead to directional risk). This provides clear when-to-use and rationale for exclusion.

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

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

Annotations declare read-only, idempotent, and non-destructive. Description adds substantial context: compatibility warnings, temporal alignment, skipped cross types, and explanation of when spreads are meaningful. Exceeds the burden by detailed behavioral traits beyond annotations.

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

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

Description is well-structured with a clear summary up front, followed by modes, response, and safety fields. However, some parts (e.g., detailed explanation of skipped_cross_type) are verbose and could be condensed without losing clarity.

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, three parameters, and no output schema, the description covers input usage, response fields, safety mechanisms, and limitations (e.g., temporal alignment, compatibility). Annotations handle safety, leaving description to fill in all operational 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?

Input schema has 100% coverage, but description adds meaning by listing the 10 pre-mapped topics and explaining how explicit tickers override topic mapping. Provides context that schema alone does not, enhancing parameter understanding.

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

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

Clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. Distinguishes from siblings by its specific function of comparing two prediction markets. Provides explicit details on modes and response.

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

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

Explains when to use (for cross-venue spread analysis) and warns that pre-mapped topics often return compatibility warnings, implying not all are tradeable. Could be more explicit about when not to use, but context of sibling tools suggests no direct alternatives.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds context about the output format ('Returns normalized items including title, link, published, summary') and optional keyword filtering, which are useful beyond the structured annotations.

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

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

The description is two sentences long, front-loads the main purpose, and contains no superfluous information. Every clause 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 read tool with good annotations and thorough schema, the description covers the key aspects: what it does, input prerequisite, output fields, and filtering option. It lacks details on pagination or rate limits but is mostly complete given the tool's complexity.

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

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

Schema coverage is 100%, with each parameter described. The description adds minimal extra meaning: it explains the feed id comes from list_feeds and mentions optional keyword filtering. This is adequate but does not significantly surpass the schema descriptions.

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

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

The description uses a specific verb ('Read') and resource ('a curated design & photography feed by its id'), clearly stating the tool's action and scope. It also notes the prerequisite ('from list_feeds'), which helps differentiate from similar tools like fetch_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 implies that the feed id should come from list_feeds, but it does not explicitly state when to use this tool versus alternatives like fetch_feed or search_within. No exclusion criteria or alternative recommendations are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context: it retrieves values, is scoped to an identifier, and pairs with remember/forget. 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 main action. It is concise but covers all necessary points. Slightly verbose, but no unnecessary information.

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

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

Given the low complexity (one optional parameter, no output schema), the description is complete. It explains use cases, scoping, and integration with other tools.

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

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

The description adds meaning beyond the input schema by explaining that omitting the key lists all keys. Schema coverage is 100%, but the description enhances understanding.

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

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

The description clearly states the tool's function: retrieve a value saved via remember, or list all saved keys. It uses specific verbs ('retrieve', 'list') and identifies the resource ('saved keys'). It distinguishes from sibling tools like remember and forget.

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

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

The description explains when to use the tool (look up context stored earlier, avoid re-deriving) and how (omit key to list all). It mentions scoping and pairing with remember/forget, but could be more explicit about when not to use it 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?

The description adds behavioral context beyond the annotations, such as the effect of mark_read on subsequent calls and the structure of returned alerts (source, citation_uri, raw payload). Since annotations already declare readOnly and idempotent, the description appropriately complements them.

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

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

The description is concise (5 sentences) and well-structured, front-loading the core purpose and progressively adding details on return fields, filtering, and usage notes. Every sentence serves a purpose.

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

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

Given complete schema coverage and rich annotations, the description adds sufficient context about the tool's behavior, including return fields and the mark_read feature. It is fully adequate for an agent to invoke correctly.

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

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

All 5 parameters have schema descriptions (100% coverage), and the description adds examples (e.g., 'sec_8k') and clarifies the mark_read behavior. The description enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed' and distinguishes itself from sibling tools like fetch_feed or read_feed by specifying it returns the most recent alerts from the persisted 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 provides usage guidance by mentioning polling works fine and that the same feed is available via a REST endpoint for scripts/dashboards. However, it does not explicitly state when to use this tool over alternative feed-related tools like fetch_feed or read_feed.

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

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

Beyond annotations (readOnlyHint, etc.), the description details multiple data sources (SEC EDGAR, GDELT, GNews, USPTO), fallback behavior, and current USPTO status. This adds significant behavioral context.

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

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

The description is information-dense but somewhat long. It front-loads purpose with example queries, then details sources and param guidance. Slightly more structured formatting could improve scanability, but overall 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?

With 3 required params and no output schema, the description covers input format, data sources, return structure (changes[], total_changes, URIs), and limitations (USPTO soft-fail). 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?

Despite 100% schema coverage, the description adds practical context: notes that type only supports 'company', explains since format with examples, and mentions ticker vs CIK for value. This meaningfully supplements 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 defines the tool as a change feed for a company in a recent window, using phrases like 'what's new with X'. It distinguishes from the sibling entity_profile by stating when to use that instead.

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

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

The description provides explicit usage scenarios ('What's new with X') and an explicit alternative: 'Use entity_profile instead when you want the static profile'. It also clarifies the since parameter options.

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 idempotentHint (true) and destructiveHint (false). Description adds valuable behavioral context: key-value scoping by identifier, retention durations for authenticated vs anonymous sessions. 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, front-loaded with purpose, then usage, then technical details. Every sentence serves a purpose, no fluff.

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

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

For a simple write tool with no output schema, the description covers purpose, behavior, usage, and even mentions related tools. It is fully adequate for correct invocation.

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

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

Schema coverage is 100% with clear descriptions. Description adds context about scoping by agent identifier and the nature of key-value storage, which is helpful but not strictly required given schema completeness.

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

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

The description clearly states the tool saves data for reuse, specifying the verb 'save' and resource 'data'. It distinguishes from siblings by naming 'recall' and 'forget' as direct companions.

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

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

Explicit guidance on when to use (discovering something worth carrying forward) and when to use alternatives (pair with recall/forget). Also notes authentication and session retention details.

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

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

Discloses internal cascading lookups and that it replaces 2-3 manual steps. Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and the description adds valuable context about output details (ticker, CIK, company name, citation URIs) 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?

Concise at 6-7 sentences, front-loaded with examples and purpose. Every sentence adds value without redundancy. Very efficient for the information conveyed.

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 return values for both entity types, including citation URIs. For a simple resolver with 2 parameters, this is entirely complete and actionable.

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

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

Schema coverage is 100%, and the description significantly enriches parameter meaning: explains accepted input formats for 'value' (ticker, CIK, name for company; brand/generic for drug) and what each type returns. Goes well beyond the schema descriptions.

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

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

The description clearly states it resolves names to canonical IDs, with examples (ticker, CIK, RxCUI). It distinguishes from siblings by saying 'Use FIRST whenever you have a name but need an ID', making its unique purpose obvious.

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 to use when you have a name and need an ID, with example queries for two types. Lacks explicit statements of when not to use or alternatives, but the sibling context and 'FIRST' hint provide reasonable guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it internally calls ai_visibility_check for each entity, ranks results by score, and surfaces most/least recognized. It also describes the output format (ranked list with score, confidence, signal density), which annotations do not cover.

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

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

The description is four sentences with no fluff. It front-loads the main purpose, then explains the mechanism, use case, and output. Every sentence adds value and is efficiently 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?

Despite lacking an output schema, the description sufficiently explains the tool's behavior, parameters, and return type. It covers internal steps (probe, rank, surface) and output fields (score, confidence, signal density). For a ranking tool with good annotations, this is complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by clarifying that the first entity in 'entities' is treated as the 'subject' for narrative and that omitting 'models' defaults to 'workers-ai'. This extra context improves understanding beyond the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using the verb 'Compare' and specifying the resource. It distinguishes itself from sibling tools like ai_visibility_check (singular) and compare_entities (generic) by focusing on AI presence and competitive audit.

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 'Useful for competitive AI-marketing audits' and gives an example query. It implies when to use (multi-entity comparison) but does not explicitly exclude single-entity use, which is covered by ai_visibility_check. Still provides 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?

Discloses that it fans out across two external services, that bundlephobia's first measurement can take 5-30s, and that partial failures degrade gracefully with sources_failed listed. This adds context beyond annotations like readOnlyHint and idempotentHint.

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 relatively long but packed with essential information. It front-loads the core purpose and then details behavior, timing, and limitations. Could be slightly trimmed but remains efficient.

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

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

For a tool with no output schema, the description provides a comprehensive list of return fields and explains partial failure behavior. It covers all necessary context for an agent to understand inputs, behavior, and outputs.

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

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

Both parameters are described in schema (100% coverage) and the description adds that version defaults to latest published, which is not in schema. 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 it performs a composite check for adding npm packages, combining deps.dev and bundlephobia data. It distinguishes from siblings like 'validate_claim' or 'scan_competitor_ai_presence' by focusing on npm dependency evaluation.

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

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

Explicitly states when to use: when an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also specifies NPM-only and directs other ecosystems to deps.dev:version, providing clear 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?

Description adds substantial behavioral info beyond annotations: embedding model (BGE-base-en), chunking strategy (500-char overlapping windows), char cap (200K) and truncation behavior. This makes the tool's inner workings transparent.

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

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

Two tightly packed paragraphs with zero wasted words. Front-loaded with purpose, then use case, then technical details. 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?

Even without an output schema, the description informs the agent of return format (top-N passages with offsets and scores). Also covers pairing with another tool and truncation. Fully sufficient for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. Description enhances meaning by explaining query as 'natural-language query', giving examples, and noting limit defaults. Adds practical usage hints beyond parameter 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?

Purpose is crystal clear: 'Semantic search INSIDE a fetched record.' It specifies verb (search), resource (a fetched record), and distinguishes from sibling tools like ask_pipeworx_grounded by describing its pairing 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: 'when the record is too big to cram into the prompt'. Describes context-saving benefit and pairing with another tool. Lacks explicit 'when not to use', but context is clear enough.

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

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

The annotations declare write behavior (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds significant context: OAuth requirement, supported event types with specific examples, delivery channels (feed, email, SMS, webhook) with constraints (SMS 10/day cap, webhook auto-disable after 10 failures), and the fact that the subscription persists. 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 well-structured: starting with the core action, then auth requirement, then supported types, then delivery options. It is informative without being verbose, though it could be slightly condensed (e.g., some type details are repeated in the schema). Still, 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 moderate complexity (3 parameters, nested objects, no output schema), the description covers all necessary aspects: purpose, auth, types, delivery channels, constraints, and return value. It provides enough detail for an agent to correctly invoke the tool, especially with the sibling tools 'list_subscriptions' and 'unsubscribe' available.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by providing type-specific examples (e.g., 'items:["5.02"]' for sec_8k) and detailed delivery channel behavior (e.g., webhook signing and auto-disable). This adds practical understanding for parameter usage.

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

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

The description begins with 'Create a proactive monitoring subscription to a live-data event stream,' which clearly specifies the verb (create), resource (subscription), and scope (proactive monitoring). It also mentions returning the subscription id. This distinguishes it from sibling tools like 'unsubscribe' 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?

The description states a key prerequisite ('Requires a Pipeworx OAuth account') and lists supported subscription types with examples. It does not explicitly exclude alternatives, but the context signals (sibling tools) imply that this is the only creation tool. The mention of phone verification and rate limits provides helpful constraints.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that it returns categorized example questions with tool usage details, no contradictions.

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

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

Packed with useful info, front-loaded purpose. Slightly long but each sentence adds value. Could be trimmed slightly but acceptable.

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

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

For a simple tool with one optional param and no output schema, the description covers purpose, usage, and behavioral context well. No gaps given the tool's nature.

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

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

Schema already describes the topic parameter and lists possible values. Description adds that omitting gives cross-category spread, reinforcing usage. Schema coverage is 100%.

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

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

The description clearly states the tool is the onboarding entry point for new agents, returning category-bucketed example questions with exact tool+argument shapes. It distinguishes from siblings like 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 says to use this FIRST when you don't know what Pipeworx can do, and explains when to pass topic vs no arguments. No explicit when-not, but context is clear.

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

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

Annotations provide readOnlyHint=false and destructiveHint=false; description adds that the row is deactivated (not deleted) and ownership is enforced. This context beyond annotations justifies a 4.

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, no redundancy. Front-loaded with the core action, then 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?

Tool is simple (1 param, no output schema), and description covers the key behavioral aspects (ownership, deactivation). Annotations complete the safety profile. No gaps remain.

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

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

Schema has 100% coverage with a clear description of the 'id' parameter. The description restates the parameter usage but adds a link to the 'subscribe' tool for provenance, which is helpful but not essential. Baseline 3 applies.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by clarifying ownership enforcement and deactivation behavior.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and notes that deactivated rows keep historical events accessible via recent_alerts. Lacks explicit when-not-to-use or alternative tools, but context is clear.

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

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

Annotations declare it safe (readOnly, idempotent, openWorld). The description adds valuable behavioral context: the exact percent-delta math for financial claims, automatic fallback to grounded pipeline for other claims, and the fact it replaces 4–6 sequential calls. 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 moderately long but every sentence adds value. It starts with concrete examples, explains routing, mentions return format, and efficiency. Could trim some repetition but overall well-structured and front-loaded.

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

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

Despite no output schema, the description fully specifies return values (verdict types, cited value, reasoning). It covers parameters, when to use, internal logic, and output. No gaps given the tool's complexity and annotation richness.

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

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

Schema covers both parameters (100%). The description adds meaningful guidance: explains tolerance_pct overrides, default behavior, and specific use case (hallucination detection with 1–2%). This enriches the schema without redundancy.

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 (verify/validate) and resource (factual claims against authoritative sources). It distinguishes from siblings by outlining two specific verification paths (SEC EDGAR for financial, grounded pipeline for others), making it distinct from general query tools like ask_pipeworx_grounded.

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

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

Explicitly says to use when the agent needs to fact-check a user's statement. It explains two internal routing paths but does not explicitly contrast with sibling tools (e.g., ask_pipeworx_grounded) or state when not to use. Still, the guidance is clear and actionable.

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