Data Winnipeg

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

Annotations indicate read-only, idempotent, non-destructive. Description adds return structure details and clarifies that API key is passed through to Anthropic. No contradictions. Could mention rate limits but not required.

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

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

Four sentences, front-loaded with main action, each sentence adds essential information. No redundancy or filler.

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

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

Given no output schema, description adequately covers return structure and usage. Missing details on error handling or limits, but sufficient for a straightforward read-only tool with good annotations.

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

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

Schema coverage is 100%, but description adds value by explaining default model behavior, condition for _apiKey usage, and purpose of context parameter. Enhances understanding beyond schema.

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

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

Clearly states the verb 'probe' and resource 'LLMs for what they know about a business/brand/product/topic' and outcome 'score visibility (0-100) per model'. Distinguishes from siblings like scan_competitor_ai_presence by focusing on general visibility scoring.

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

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

Explicitly lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. However, does not explicitly state when not to use or differentiate from similar sibling tools like scan_competitor_ai_presence.

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

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

Beyond the readOnlyHint annotation, the description discloses it returns 'structured answer with stable pipeworx:// citation URIs', mentions it 'fills arguments', 'works on every tier, one fast call', and routes to live news. It adds significant behavioral context without contradicting the annotations.

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

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

The description is longer than average but front-loads the most critical instruction ('PREFER OVER WEB SEARCH') and uses clear sections (examples, step-up guidance). While a bit verbose, every sentence adds value, though some repetition exists (e.g., multiple 'current' instances).

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 breadth (a router over 5,566 sources) and minimal schema (one parameter), the description fully covers usage intent, examples, exclusions, and behavior. It even addresses edge cases like breaking news and explicitly notes it works on every tier.

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% (all parameters are aliases of 'question'). The description reinforces that it accepts natural language but does not add parameter-level detail beyond the schema's own descriptions. Baseline 3 is appropriate as the schema is sufficient and description adds no compensation needed.

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

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

The description uses specific verbs and resource types: 'Routes the question to the right one of 5,566 tools across 1462 verified sources' and explicitly names categories (SEC filings, FDA, FRED), clearly distinguishing from web search and sibling tools. It clearly states what it does and provides numerous concrete 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?

Explicitly gives contrastive guidance: 'PREFER OVER WEB SEARCH', 'Step up only when needed: for ... use ask_pipeworx_grounded; for ... use deep_research', and even addresses breaking-news cases. This is a model example of when-to-use vs alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive, and open-world. The description adds valuable context about the beta status, live candidate evaluation, and that it's a full working router with no fallback. It also mentions the same response shape, going beyond annotations without contradiction.

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

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

The description is concise yet informative, covering the beta context, current status, usage comparison, and operational details. It is well-structured, front-loads the core purpose, and each sentence earns its place, though slightly verbose for a simple 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?

The description fully explains the tool's role as a beta router, its equivalence to ask_pipeworx, and the experimental edge. It addresses the lack of an output schema by noting 'same response shape' as ask_pipeworx, making it complete for an agent to understand what to expect.

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

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

Schema coverage is 100% with all 6 parameters described as aliases for 'question'. The description adds no parameter-level detail beyond what the schema provides, which is appropriate given the simplicity. Baseline 3 applies since schema does the heavy lifting.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router handling 5,566 tools with the same arguments and response shape. It distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded by its experimental nature and live candidate routing improvements.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router, implying when not to use it (for stable production). Also clarifies that currently it matches ask_pipeworx exactly, giving clear context for selection.

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

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

The description discloses extensive behavioral traits beyond annotations: it uses only tool result data, returns a structured response with evidence and refusal reasons, and caps its operation by refusing when data doesn't directly answer. It also clarifies the behavior of the refusal mechanism and data provenance. This significantly enriches transparency beyond what the readOnly/openWorld/idempotent hints provide, with no contradiction.

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

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

The description is dense yet concise, front-loading the core purpose and then detailing mechanics, output, refusal behavior, use cases, and cost trade-off. Every sentence serves a purpose—no fluff. It efficiently communicates both the 'what' and 'when' in a compact format.

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

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

Given the tool's complexity (routing to 5,566 sources), the description covers the essential aspects: the grounding principle, the output contract including fields like evidence and source, the refusal conditions, and the performance trade-off. It also addresses niche failure modes (e.g., 'data_truncated','no_tool_match') without requiring an output schema. This is comprehensive for an agent to decide and use effectively.

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

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

The schema already covers 100% of parameters with clear descriptions (question and its aliases). The description does not add parameter-specific information, but per the rubric, high schema coverage sets a baseline of 3. No extra value is provided about parameters beyond the schema, so a 3 is appropriate.

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

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

The description clearly states the tool is a 'hallucination-resistant answer mode for high-stakes reads' and explains it routes to the right tool, fetches data, and extracts the answer. It distinguishes itself from the sibling ask_pipeworx by emphasizing grounded, evidence-based answers without inventing facts. This is a specific verb+resource+scope statement that differentiates from its siblings.

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

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

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts and legal claims. It also warns about the cost ('Costs one extra LLM call') and recommends the alternative ('prefer ask_pipeworx for casual lookups'), offering clear when-to-use and when-not-to-use direction.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds extensive behavioral detail: resolution confidence, parent event extraction, news fallback mechanisms, safety guards for low-confidence matches, closed markets, wide spreads, and cancellation rules. Far exceeds what annotations provide.

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

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

Description is long (multiple paragraphs) but front-loaded with the main action. Contains structured sections (e.g., RESOLVER CONTRACT) but could be more concise. Every sentence adds value, but length reduces readability.

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

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

No output schema, but description thoroughly explains response shapes (result.market, analysis, evidence, etc.), edge cases, cancellation rules, and safety mechanisms. Covers all aspects for effective tool invocation.

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

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

Schema coverage is 100% with descriptions; description adds meaningful context for the 'market' parameter (slug/URL/text) and explains 'depth' and 'include_raw' behavior with examples, enhancing understanding beyond schema alone.

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

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

The description explicitly states 'Research a Polymarket bet by pulling the relevant Pipeworx data' and provides clear examples of use cases. It distinguishes itself from sibling tools like 'ask_pipeworx' by focusing on specific bet analysis.

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

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

Explicitly says 'Use for "should I bet on X"...' and provides examples of when to use. Lacks explicit exclusion guidance but adequately implies context.

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

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

Annotations declare read-only, open-world, and idempotent. Description adds concrete details: for companies it pulls latest 10-K data with correct off-calendar handling (e.g., AAPL Sep, NVDA Jan); for drugs it uses FAERS, FDA, and trial counts. It also explains sorting and citation URIs. No contradictions.

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

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

Description is moderately long but every sentence adds value—examples, behavioral notes, sorting, and efficiency claims. Structure is front-loaded with usage examples. Minor verbosity (e.g., listing all example queries) 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?

No output schema, but description explains returns ('paired data + pipeworx:// citation URIs per entity') and sorting. For a tool with 2 simple params and no nested objects, this covers the key information needed for agents.

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

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

Input schema covers both parameters with enums and descriptions (100% coverage). Description enriches by providing example values (e.g., tickers ['AAPL','MSFT'] for company, drug names like 'ozempic') and clarifies what data each type returns.

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 opens with natural-language examples like "Compare X and Y" and explicitly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It distinguishes from sibling tools (e.g., entity_profile) that perform single-entity lookups.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8–15 sequential lookups. Lacks an explicit when-not-to-use, but the positive guidance is strong.

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, and idempotentHint, so the safety profile is clear. The description adds behavioral context about keyword-based search and pagination (offset/limit). This adds value but is not extensive.

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 with no unnecessary words. It front-loads the purpose and then provides actionable guidance. 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?

The description explains the return fields (resource_id, name, description, category, update date) and suggests the next step. Given the absence of an output schema, this is sufficient context for an agent. It covers behavior, parameters, and 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 description coverage is 100%, so parameters are well-documented. The description does not add significant extra meaning to the parameters beyond what the schema provides. The mention of passing resource_id to 'query/metadata' is about the return value, not 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's purpose: searching the Winnipeg Open Data catalog by keyword. It specifies the action (search), resource (Winnipeg Open Data catalog), and the mechanism (by keyword). The return fields are listed, making it distinct from sibling tools.

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

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

The description provides clear context for use: searching datasets and then using the resource_id with 'query/metadata'. It does not explicitly state when not to use or mention alternatives, but the context is sufficient for an agent to understand when this tool is appropriate.

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

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

Annotations only declare readOnly/openWorld/idempotent/non-destructive. The description richly discloses operational behavior: parallel decomposition across 5,566 tools, return packet structure (evidence, confidence, source, fetched_at, citation), gaps[] for unanswered facets, contradictions[] for standard/thorough, hop field and citation_uri resolvability, semantic excerpting, and 15-90s latency. No contradiction with annotations.

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

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

The description is long (~400 words) but every sentence carries distinct operational or selection information: account constraints, alternative tools, internal mechanics, output format, edge cases, latency. It is front-loaded with the critical account requirement and ends with latency, making it dense rather than verbose. A slightly tighter middle section could improve scannability but nothing is wasted.

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

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

The tool is complex (multiple depth levels, parallel routing, citation semantics, gap handling) and has no output schema, so the description must explain return values and behavior. It fully covers the findings packet, gaps[], contradictions[], hop field, citation_uri fetchability, and timing. It also addresses failure modes (empty gaps for news topics) and scaling behavior across depth levels. Complete for an AI agent's decision-making.

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

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

Schema coverage is 100% so baseline is 3. The description adds substantial value: explains 'quick', 'standard', 'thorough' in terms of facet count, hop behavior, gap recovery, contradiction scan, and pricing. Also clarifies that 'question' can be broad/multi-part and decomposition is built in, which is not obvious from the schema alone.

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

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

The description states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and clarifies it is NOT open-web search. It also distinguishes from siblings like ask_pipeworx ('single lookup') and live-news tools, making its scope and value explicit.

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: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also covers account requirements and paid tier for 'thorough' depth, giving clear when-to-use and when-not-to-use conditions.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it returns top-N relevant tools with names, descriptions, full input schemas with curated examples, and that results are ready to call directly. No contradiction with annotations.

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

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

Description is moderately long but front-loaded with purpose and usage, then return value. Each sentence adds value, though could be slightly more concise. Well-structured overall.

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 (6 params, no output schema), the description covers purpose, usage scenarios, and return format thoroughly. No missing critical information for a discovery tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds little beyond schema (mentions query types), but the schema already explains aliases and purpose. No additional parameter-level detail beyond usage context.

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

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

The description clearly states the tool finds tools by describing data or task, with a specific verb ('find') and resource ('tools'). It distinguishes itself from siblings by noting it returns schemas ready to call.

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

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

Explicitly says when to use ('when you need to browse, search, look up, or discover what tools exist for...') and provides specific domains. Also advises to call this FIRST when many tools are available, giving clear context and alternatives.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds that the tool fans out across multiple sources, mentions that patents may soft-fail after May 2025, and describes the fallback mechanism for news. 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 dense but efficient, with front-loaded examples and detailed output breakdown. Each sentence adds value, though it is somewhat lengthy. It could be slightly more concise, but appropriate for the complexity.

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

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

The description covers all aspects: input limitations, output fields, data sources, fallbacks, and soft-fail states. No output schema exists, but the description sufficiently details the return structure (cik, filing URIs, fundamentals, patents, news, LEI).

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

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

The schema already provides good descriptions and 100% coverage. The description reinforces that type is only 'company' and value is ticker or CIK, adds examples, and clarifies that names are not supported. This adds helpful context beyond the schema.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company in ONE parallel call,' with explicit example queries. It distinguishes from siblings by advising to prefer this over chaining single-pack lookups for holistic views.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies that names are not supported and to use resolve_entity first, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is not in annotations.

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

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

Two concise sentences front-load the purpose and usage, with no wasted words.

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

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

For a simple 1-parameter tool, the description covers purpose, usage context, and related tools. No gaps.

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

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

Schema coverage is 100% and the parameter is well-described in the schema. The description adds no extra parameter information, earning baseline 3.

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

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

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

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

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

Explicitly states when to use: 'context is stale, task is done, or you want to clear sensitive data'. Also pairs with remember and recall for context.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral context: fetches the page, extracts title/description/key links, emits standard markdown, and notes output is a single text blob. No contradictions.

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

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

The description is a single paragraph of four sentences, front-loaded with the core purpose. Every sentence adds value: purpose, process, output format, use cases. No 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?

Given no output schema, the description adequately explains the output format (standard llms.txt markdown, ready to drop at site-root). It covers the main behavior and result, making it complete for a non-complex tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides no additional parameter information beyond the schema; it repeats the URL concept but does not add new 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 states the tool generates a production-ready llms.txt file for any URL, specifying the verb and resource. It distinguishes from siblings by focusing on a unique function not covered by other tools like scan_competitor_ai_presence.

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

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

The description gives concrete use cases (client indexing, personal projects, competitor auditing) that help the agent know when to use it. It does not explicitly exclude cases or mention alternatives, but the examples are clear enough for typical scenarios.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds value by specifying return fields and default behavior (active subscriptions only). No contradictions.

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

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

Three sentences: purpose, return fields, usage guidance. No wasted words. Front-loaded with core action.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, return fields, and usage context completely.

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

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

Schema coverage is 100% for the single parameter, so baseline is 3. The description does not add new parameter info but implicitly indicates default behavior (active only). Minimal extra value.

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

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

The description clearly states 'List the caller's active subscriptions' and lists return fields. It distinguishes from sibling tools like subscribe and unsubscribe by mentioning using it to review before adding or to get an id to cancel.

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

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

Explicitly tells when to use: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides direct context for agent decision-making.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds concrete return details (columns, types, row count) without contradicting annotations.

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

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

Single sentence, no filler, front-loaded with purpose and example. Every word earns its place.

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

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

For a simple one-parameter tool with no output schema, the description fully explains input and expected output, making it self-contained.

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

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

Schema coverage is 100% with a clear description for resource_id. Description reinforces with an example, adding value beyond the schema.

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

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

Clearly states the tool retrieves schema and metadata for a dataset by resource_id, specifying return fields like columns, types, row count, etc. Distinct from sibling tools.

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

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

Provides a specific use case and example parameter. While it doesn't explicitly mention when not to use, the narrow scope makes usage 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 are all false, so the description carries the full behavioral burden. It fully discloses the dual submit/read behavior via claim_token, the rate limit ('5 per identifier per day'), the quota exemption ('doesn't count against your tool-call quota'), and the expected signal (team reads digests daily). It also warns against pasting end-user prompts and clarifies which server can act on the feedback.

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 approximately 150 words, but every sentence earns its place: purpose, triggers, exclusions, claim_token workflow, roadmap signal, and rate limits. It is front-loaded with the most important guidance before qualifiers, and the length is justified by the tool's dual submit/read nature.

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?

There is no output schema, but the description addresses the return contract ('returns a `claim_token`', 'to read whether it was fixed and what changed') and covers cost/quota and routing. It could explicitly describe the exact output shape beyond the token, but the schema's claim_token parameter description fills that gap.

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

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

Schema description coverage is 100%, with every parameter (type, context, message, claim_token) already richly described. The description restates claim_token usage in behavioral terms but adds no new parameter syntax or constraints beyond the schema, so the high-coverage baseline of 3 applies.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist' – a specific verb, resource, and scope. It then enumerates concrete use cases (bug, feature/data_gap, praise) and explicitly restricts scope to this Pipeworx connection, distinguishing it from sibling research/search tools and other vendors' connectors.

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 gives explicit when-to-use triggers: 'returns wrong/stale data (bug)', 'wish existed isn't in the catalog', or 'worked surprisingly well'. It also provides a clear exclusion – 'if the tool came from a different MCP server ... file it with that server instead' – and offers a quick test for ambiguity: 'Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral details beyond annotations: caching (5min-1h), data derivation (CF analytics-engine), and no PII. This provides useful context for the agent.

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 paragraphs with front-loaded core purpose. Every sentence adds value (use cases, caching, data source). It is appropriately concise for the tool's simplicity, with no wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It covers what is returned, why it's useful, caching behavior, data derivation, and privacy. No gaps remain for agent decision-making.

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

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

Schema coverage is 100%, so the schema already documents the 'window' parameter with enum values. The description adds value by explaining the semantic difference between short and long windows ('shorter windows surface what's hot right now; longer windows show steady-state demand'), which aids selection.

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

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

The description clearly states the tool's purpose: returning top tools, top packs, and total call volume over a recent window. The verb 'returns' and specific resource (trending data) make it distinct from siblings like 'discover_tools' or 'datasets'.

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

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

The description explicitly lists three use cases (discovering hot data sources, confirming canonical tools, aligning use cases) and explains the caching behavior. It doesn't explicitly say when not to use or name alternatives, but the use cases are clear enough for most agents.

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 scanning scope (top 200 markets by default), partition filter (placeholders, similarity threshold), response structure with fields like opportunities[] and partition_check, and fill check details. Annotations already indicate read-only, idempotent, non-destructive; description adds extensive behavioral context without contradiction.

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

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

The description is lengthy but well-structured with sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and bold labels. Front-loaded with main purpose, then detailed sections. Every sentence adds detail, but could be slightly more concise for quicker scanning.

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

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

Given the tool's complexity (two modes, multiple checks, output with opportunities and partition_check), the description is thorough. It covers when to use, expected output, caveats (e.g., realizable edge), and mentions sibling tools. No output schema exists, so the response description is essential and provided.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that event accepts slugs or full URLs, topic accepts seed questions, and elaborates on behavior for each mode. It provides context beyond the schema 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?

The description clearly states the tool's purpose: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies two modes (event and topic) with distinct use cases, and distinguishes itself from sibling tools like polymarket_fill_risk.

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

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

Provides explicit guidance: event mode for specific markets, topic mode for cross-event scanning. It explains when not to trade (realizable_edge_pp ≤ 0 from fill check) and directs to polymarket_fill_risk for custom sizing, showing awareness of alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds extensive behavioral context beyond annotations: it details response structure (by_segment, fed_candidates, _diagnostics), cache behavior (cached 1h), edge effects, slippage assumptions, and why segments might be empty. No contradictions.

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

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

The description is long but densely packed with valuable information. It front-loads the core purpose and then provides detailed methodology. While every sentence adds value, it could be more concise; however, it is well-structured for comprehension.

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 explains the response structure and diagnostics. It covers why segments might be empty and the fed_candidates exclusion. For a complex tool with 9 parameters, it provides near-complete context.

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

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

Schema description coverage is 100% (baseline 3). The description adds value by explaining the 'tradeable-edge knobs' like min_liquidity and max_spread_pp, and clarifies the nuance of min_partition_leg_kelly. This goes beyond the schema descriptions.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It specifies the verb 'scan' and the resource 'top Polymarket markets', and distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by detailing its unique methodology for discovering edge opportunities.

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 is built for the use case 'what should I bet on today' and explains how agents can discover opportunities without paging. It provides knobs and filters for tuning results. However, it does not explicitly contrast with siblings or state when not to use this tool, missing some guidance on alternatives.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds significant behavioral context: response structure (tracked[], expired[], snapshot_dates[]), computed fields (trend, decay_pp_per_day), data source limitations (60-day TTL, snapshot gaps), and that decay is based on daily closes not intraday. No contradiction with annotations.

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

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

The description is detailed and front-loaded with the core question. It is structured with clear sections for input, response, and limits. However, it is somewhat verbose and could be more concise. Every sentence adds value, but there is room for tighter wording.

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 (time-series analysis), the description is highly complete. It explains the output fields, computed metrics, data source reliability, and limitations (TTL, gaps). Without an output schema, the description fully covers expected return values and their interpretation.

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 (days, window) are fully described in the input schema with defaults and ranges. The description adds minor context (e.g., snapshot family, cache-miss behavior) but does not significantly extend beyond what schema already provides. Schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it provides edge persistence and decay telemetry from daily snapshots. It answers a specific question ('how long has this edge existed and is it shrinking?') and distinguishes between fresh and old edges. This differentiates it from sibling tools like polymarket_edges, which likely provides current edge values.

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

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

The description implies usage for evaluating edge history before trading, but does not explicitly state when to use this tool vs alternatives (e.g., polymarket_edges). It provides context on interpretation but lacks direct 'when-to-use' or 'when-not-to-use' guidance. Usage is implied but not fully explicit.

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

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

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe and non-mutating. The description adds valuable behavioral details: it walks the order-book ladder, returns specific metrics like slippage_pp, verdict, capture_ratio, and forced_directional_risk, and warns that partial basket fills create unhedged directional risk. This goes well beyond the annotations without contradicting them.

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

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

The description is well-structured with clear sections (SINGLE-MARKET, BASKET) and a bolded usage note. It is front-loaded with the core purpose, followed by detailed but necessary parameter and return information. Despite its length, every sentence adds value, and the formatting aids readability.

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 meticulously documents all return fields for both modes (e.g., top_of_book, vwap_fill_price, capture_ratio, thin_legs, forced_directional_risk). It explains the behavioral consequences of partial fills and the dominant loss mode. Given the complexity (two modes, multiple parameters), the description is comprehensive and leaves no critical gaps.

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

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

Schema description coverage is 100% (each parameter has a description in the schema). However, the tool description adds significant meaning: it explains the difference between single-market and basket modes, the interpretation of size_usd as settlement notional for baskets, and the default behavior of the side parameter. This provides crucial context beyond the schema descriptions, justifying a score above the baseline of 3.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth,' specifying the verb (check) and resource (order-book depth). It distinguishes two modes (single-market and basket/partition), and its purpose is distinct from sibling tools like polymarket_arbitrage (which presumably creates trades) and polymarket_edges (which identifies edges).

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risks of not using it ('theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position'), providing clear context for when this tool is necessary.

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 safe, idempotent read behavior. The description adds rich behavioral detail: it explains how compatibility_warning fires in two distinct cases, describes temporal alignment checks, and exposes counters for skipped leg-pair comparisons. No contradictions with annotations.

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

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

The description is well-structured with front-loaded purpose, clear sections for modes, response, and safety fields. However, it is somewhat verbose; a few sentences could be tightened. Still, 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?

Despite having no output schema, the description thoroughly explains the response structure (leg prices, spread, compatibility_warning, temporal_alignment, skipped counters) and the meaning of each field. Given the tool's complexity, this is comprehensive.

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

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

Schema coverage is 100% but the description adds significant meaning: it lists the 10 topic shortcuts, explains that explicit tickers override the topic default, and clarifies the effect of each parameter. The examples in the schema further support usage.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from sibling tools like polymarket_arbitrage by focusing on spread computation with compatibility warnings.

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

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

The description provides explicit guidance on when to use each mode, warns that most pre-mapped topics return compatibility warnings, and explains the conditions under which spreads are meaningful. It also tells users to check compatibility_warning and temporal_alignment before acting on the result.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. Description adds that output is JSON and explains SoQL clause formatting, but doesn't cover rate limits or pagination details beyond limit/offset. Adequate given annotation coverage.

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

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

Two efficient sentences with no fluff. First sentence states core action, second adds details. Fully front-loaded.

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

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

For a tool with full schema coverage and no output schema, description adequately covers parameter usage and return format. Could mention that results are JSON array, but overall sufficient.

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

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

Schema covers all 7 parameters with descriptions. Description adds value by clarifying that SoQL clauses are used without leading '$' and that limit defaults to 1000, going beyond schema explanations.

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

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

Description clearly states the tool runs SoQL queries against a Winnipeg Open Data dataset by resource_id, mentions key parameters, and returns JSON. It distinguishes from siblings like 'datasets' by focusing on querying rather than listing.

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 indicates when to use (for filtering/aggregating data) and provides examples. It does not explicitly mention alternatives or when not to use, but the context of sibling tools makes the purpose clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, which cover key behavioral traits. The description adds scoping details ('to your identifier') and pairing with other tools, but doesn't contradict or significantly extend beyond the annotations. The bar is lowered by the rich annotations, so a 3 is appropriate.

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

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

The description is three sentences long, each sentence serving a purpose: stating the action, explaining usage context, and noting scoping. It is front-loaded with the core function and has no wasted words.

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

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

Given the tool's simplicity (one optional parameter, no output schema, full annotations), the description covers all necessary aspects: purpose, usage, scoping, and relationship to sibling tools. It is complete and leaves no obvious gaps.

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

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

The schema coverage is 100% with one optional parameter. The description explains the parameter's effect ('omit to list all keys'), which mirrors the schema's own description. Since the schema already does the job, the description adds minimal additional value, resulting in a baseline 3.

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

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

The description starts with a clear verb ('Retrieve' or 'list') and specifies the resource ('value previously saved via remember' or 'saved keys'). It distinguishes itself from sibling tools like 'remember' and 'forget' by naming them, making its purpose unambiguous.

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

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

The description explains when to use the tool: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions scoping and pairing with remember/forget. However, it does not explicitly state when not to use it or provide alternatives, so it's not a 5.

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

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

The description states 'Set mark_read:true to flag returned events read', implying a write side-effect, but annotations declare readOnlyHint=true. This is a clear contradiction between description and annotations, warranting a score of 1.

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

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

The description is concise, front-loaded with the main action, and includes only relevant details 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?

Given the 5 optional parameters and no output schema, the description covers most behavioral aspects including filtering, mark_read behavior, and alternative access. It only lacks explicit handling of the unread_only 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%, and the description adds context beyond the schema, such as the effect of mark_read and the format of results. This provides additional value.

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

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

The description clearly states 'Pull fired events from your subscription feed' and details the returned data, making the purpose evident. However, it does not differentiate from sibling tools like 'list_subscriptions' or 'recent_changes'.

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

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

The description mentions that polling works fine and provides an alternative HTTP endpoint, but lacks explicit guidance on when to use this tool vs. siblings or when not to use it.

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

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

The description discloses all key behavioral traits: parallel fan-out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, return structure (changes grouped by source + total_changes + citation URIs). This is beyond what annotations (readOnly, openWorld, idempotent) provide, adding valuable context without contradiction.

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

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

The description is fairly detailed but every sentence serves a purpose: purpose, sources, parameters, return structure, and alternative. It front-loads with example queries. Could be slightly more concise but remains well-structured 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?

The tool has 3 required parameters, no output schema, yet the description fully covers the purpose, sources, behavior, parameter usage, and return format. It also provides a clear alternative. This is complete for an agent to use correctly.

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

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

Schema coverage is 100% with each parameter described. The description adds value by explaining 'since' with examples and recommended usage, clarifying 'type' is limited to 'company', and specifying 'value' can be ticker or CIK. This enriches 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's function: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It lists example queries and distinguishes from sibling tool 'entity_profile' by specifying that the latter is for static profiles, not time-windowed changes.

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 guidance on when to use this tool vs 'entity_profile' and recommends using '30d' or '1m' for typical monitoring. It does not explicitly list all cases where the tool should not be used, but the alternative is clearly defined.

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?

Goes beyond annotations by detailing storage as key-value pair scoped by identifier, persistence differences for authenticated vs anonymous users (24-hour retention), and pairing with recall/forget. No contradictions with annotations.

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

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

Four sentences, front-loaded with main purpose, followed by usage guidance and behavioral details. Every sentence adds value; no redundant or extraneous information.

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

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

Given two simple parameters, no output schema, and annotations, the description is complete. It explains scope, persistence, and how to use with sibling tools, covering all necessary context for an agent.

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

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

Schema already provides clear descriptions for key and value. The tool description adds context about usage but does not elaborate on parameter specifics beyond what schema offers. Baseline 3 is appropriate given full 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 the action ('save'), the resource ('data the agent will need to reuse later'), and the scope ('across this conversation or across sessions'). It distinguishes from sibling tools like recall and forget by explicitly naming them as 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?

Provides explicit guidance on when to use: 'when you discover something worth carrying forward' with concrete examples. Does not explicitly state when not to use, but implies alternatives via mention of recall and forget.

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

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

Beyond the readOnly/annotations, the description reveals multi-endpoint internal cascading, graceful degradation when GLEIF/OpenFIGI are unavailable, source labeling for each identifier, explicit unresolved fields, and ISIN-to-LEI mapping. These are significant 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?

The description is long but front-loaded with examples and a clear 'SUPPORTED TYPES' structure. Each segment (sources, fallback, output detail) earns its place; it is dense rather than redundant.

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

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

With no output schema, the description carries full burden of explaining return values. It covers all resolved identifiers, source labels, ownership/children for LEI, unresolved handling, and fallback behavior, giving an agent enough to correctly invoke and interpret results.

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

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

Though schema coverage is 100%, the description enriches both parameters significantly: value for company accepts ticker, CIK, ISIN, or name with detailed resolution logic; drug includes RxCUI, ingredient, brand, and citation. This goes well beyond the schema's brief descriptions.

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

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

The description opens with concrete user queries and clearly states the tool resolves a name to canonical identifiers. It names specific sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm) and distinguishes itself from sibling tools by positioning as the central ID lookup prerequisite.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID' and gives examples of phrasing. While it lacks explicit 'when not to use' or named alternatives, the instruction is a clear bright-line rule for its use.

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

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

Annotations already declare safe, idempotent, read-only behavior. Description adds significant value by detailing the internal process (probes each entity with ai_visibility_check, ranks by score) and output structure (ranked list with score, confidence, signal density). No contradictions.

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

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

Two sentences, front-loaded with main action, no filler. Every sentence adds essential information, including a concrete example and output details.

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

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

Despite no output schema, description fully describes the return value. All 4 parameters are covered (schema + description). Complexity is moderate and well addressed. Nothing critical is missing.

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

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

Schema coverage is 100% with detailed descriptions. Description adds contextual meaning: 'entities' first entry is subject, rest competitors; explains default models and API key requirement. This enhances understanding beyond schema, so a 4 is justified.

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

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

Description clearly states it compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. Distinguishes from siblings like ai_visibility_check (single entity) via explicit method (probes each with that tool) and multi-entity comparison.

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

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

Provides a concrete use case: competitive AI-marketing audits with an example question. Implicitly clear when to use it (comparing multiple entities), but doesn't explicitly exclude alternatives like compare_entities. Still strong 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, not destructive. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia first measurement may take 5-30s, and sources_failed lists timeouts. No contradiction with annotations.

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

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

The description is a single paragraph of 6 sentences, front-loaded with the main purpose. It is dense but well-structured, with each sentence adding value. Could be slightly more scannable with bullet points, but still concise.

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

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

With no output schema, the description thoroughly explains the return shape (summary block with fields, per-advisory detail, links, alternative versions) and covers edge cases (partial failures, scoped packages, performance caveats). Complete for a 2-parameter read 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% with clear descriptions for both parameters (package name with scoped support, version with default to latest). The description does not add significant extra meaning beyond the schema, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool performs a composite check for adding an npm package, combining deps.dev and bundlephobia data. It specifies the verb 'scan dependency' and resource 'npm package', distinguishing it from sibling tools like scan_competitor_ai_presence.

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: whenever an agent asks about safety, popularity, size, or cost of adding a package. It also notes the NPM-only scope and directs other ecosystems to deps.dev:version, providing clear usage context. No explicit when-not-to-use, but the guidance is sufficient.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds concrete implementation details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and that results include character offsets for verification. This far exceeds what annotations provide.

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

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

Four sentences, each earning its place: first sentence states purpose, second gives usage rationale, third explains pairing with sibling, fourth provides technical details. Front-loaded and no redundancy.

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

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

Despite no output schema, the description mentions return format (passages with offsets and similarity scores), input limits (200K chars), and embedding methodology. Covers all essential aspects for tool selection and 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%, but description enriches each parameter: explains 'text' as document to search, gives max char hint; 'query' as natural language with examples; 'limit' as max passages with default. Adds constraints and usage context not in schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with specific verb ('search'), resource ('text'), and scope ('inside a record'). Differentiates from sibling tools like ask_pipeworx_grounded by explaining how they pair together, leaving no ambiguity about its unique function.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides an alternative usage pattern: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives clear when-to-use and when-not-to-use guidance.

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

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

Discloses beyond annotations: subscription persistence requires OAuth, feed always on, webhook secret returned once, auto-disable after 10 failures. No contradiction with annotations.

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

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

Front-loaded with purpose, detailed but each sentence is informative. Slightly lengthy but justified by complexity; minor redundancy in delivery description.

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

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

Covers all aspects: required account type, types, params, delivery options, return value, behavioral traits, constraints. No output schema but return value mentioned.

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

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

Schema coverage 100% but description adds rich examples for type and params, delivery constraints, and webhook signing detail – significantly beyond schema.

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

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

Clearly states 'Create a proactive monitoring subscription' and 'Returns the new subscription id', with specific verb and resource. Distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

Explicitly notes prerequisite (Pipeworx OAuth account), supported types with examples, delivery channels with constraints (phone verification, 10/day cap, webhook auto-disable). Provides clear when-to-use guidance.

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

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

Annotations already declare readOnlyHint=true etc. The description adds that it draws from a live catalog, returns example questions with tool shapes, and explains the behavior of the optional parameter. No contradiction.

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

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

The description is somewhat lengthy but well-structured with examples and usage guidance. Every sentence earns its place, though it could be slightly more concise.

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

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

Given no output schema, the description explains the return format and covers the parameter's purpose well. Annotations cover safety. Complete for this 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% for the single parameter, but the description adds meaning by listing possible values and explaining the behavior when omitted.

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

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

The description clearly states it is the onboarding entry point that returns category-bucketed example questions, and it distinguishes itself from siblings by recommending use when the agent doesn't know what Pipeworx can do.

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

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

Explicitly says to use it first when unsure, and shows how to focus via the `topic` parameter. Does not explicitly mention when not to use or name sibling alternatives, but the guidance 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?

Discloses key behaviors beyond annotations: ownership enforcement, deactivation (not deletion), and historical event availability via recent_alerts. Annotations indicate non-destructive mutation; description adds precise nature of the operation.

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 superfluous words. All information is essential 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?

Given the simple tool (1 param, no output schema), the description covers effect, ownership, and relation to other tools (recent_alerts). No gaps.

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

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

Schema coverage is 100% and schema already describes 'id' as subscription UUID. Description does not add additional semantic meaning beyond 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?

Clearly states 'Cancel a subscription by id', specifying verb and resource. Distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and the deactivation vs deletion behavior, providing clear context for when to use. Does not explicitly state when not to use, but sufficient 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?

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial behavioral transparency beyond that: it details the verdict taxonomy, explains that could_not_verify means the check did not happen and is NOT evidence, describes unsupported semantics, and notes the structured vs. grounded fallback. 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 and front-loaded with the most important usage cues, but it is somewhat long. The list of paraphrases at the beginning adds value for triggering, and the warning about could_not_verify is important, but some sentences (like the pipeline detail) could be tightened. Still, every sentence earns its place overall.

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?

There is no output schema, so the description must explain return values and edge cases. It does so thoroughly: lists all possible verdicts, mentions the actual value with pipeworx:// citation and reasoning, explains could_not_verify with error metadata, and defines unsupported. It also covers the routing logic and source fallback, making the behavior complete for an agent to invoke and interpret results.

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

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

Schema coverage is 100% and both parameters have descriptions, but the tool description adds meaningful semantics: it explains tolerance_pct overrides claim wording, defaults are implied by wording capped at 5, and suggests using 1–2 for hallucination detection. The claim parameter is also contextualized with natural-language examples, going beyond the raw 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 is explicit: it is a natural-language claim verification tool against authoritative sources, with clear verb phrases like "fact check" and "verify the claim that…". It differentiates from sibling tools by framing the task as checking whether a user statement is factually correct, and it even distinguishes the financial structured path from the general grounded pipeline.

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

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

It provides clear context: "Use whenever the agent needs to check whether something a user said is factually correct." It also explains the routing logic (financial vs. other claims) and claims to replace multiple sequential calls. However, it does not explicitly state when NOT to use this tool or name alternatives, so it stops short of a 5.

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