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 annotations, the description discloses meaningful behavior: the tool automatically routes to one of 5,798 tools, fills arguments, returns structured answers, and emits stable pipeworx:// citation URIs. It also explains how it handles breaking news. This gives the agent a clear model of what happens when the tool is invoked.

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

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

The description is long but well organized: it front-loads the most important guidance, provides a domain list, trigger phrases, concrete examples, and routing alternatives. A small amount of redundancy exists between 'PREFER OVER WEB SEARCH' and the later 'START HERE' guidance, but every section contributes useful information.

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

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

Given the simple single-parameter schema and the absence of an output schema, the description is complete enough. It covers what the tool does, what inputs to provide, what outputs to expect, and how to choose among sibling tools. An agent should be able to invoke it correctly with confidence.

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 documents the question parameter and its aliases at 100% coverage. The description adds value by showing concrete example queries and listing the kinds of questions the parameter should contain, which helps the agent formulate the natural-language input appropriately.

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 exactly what the tool does: routes natural language questions to the right tool among thousands of verified sources, fills arguments, and returns structured answers with stable citation URIs. It also clearly distinguishes itself from web search and from siblings like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: prefer it over web search for factual, current, or historical data; use it for trigger phrases like 'what is' or 'look up'; and it names alternatives for single grounded answers, broad multi-part research, and breaking news. This is strong routing guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds valuable context beyond that: it is an experimental edge, candidates may be enabled live, none is currently active, results are compared against the stable router, and it 'falls back to nothing' but remains a fully functional router. This is strong behavioral disclosure.

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

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

The description is front-loaded with the core beta-twin concept and contains mostly useful detail: current candidate state, usage guidance, and fallback behavior. It is slightly redundant with phrases like 'matches ask_pipeworx exactly' and 'Use it exactly like ask_pipeworx,' but overall it is appropriately sized for a nuanced beta 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 is complete enough for an agent to understand when and how to invoke the tool, especially with the full parameter schema and strong annotations. The only minor gap is that output shape is not described directly, but 'same response shape' references ask_pipeworx, which is an acceptable pointer given the tool is a beta twin.

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

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

Schema description coverage is 100% and the schema already documents the question parameter plus all aliases with clear descriptions. The tool description itself adds no parameter-level meaning, but because the schema fully covers the parameters, the 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 states a specific purpose: a beta version of ask_pipeworx with identical routing behavior and response shape, differentiated by candidate routing improvements. This clearly distinguishes it from the stable ask_pipeworx sibling and makes the tool's role 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 explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing,' which gives clear when-to-use guidance and names the key alternative. It also explains the current no-active-candidate state, but it does not provide explicit when-not-to-use exclusions or mention ask_pipeworx_grounded as an alternative.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, the description goes well beyond by disclosing the explicit refusal contract, the refusal_reason enum, the extraction-only-from-tool-result guarantee, and the extra LLM call cost. This is substantive behavioral context that annotations alone do not convey. No contradiction with annotations exists.

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 every sentence earns its place: core purpose, routing mechanism, success/refusal return contract, usage guidance, and cost trade-off. It is front-loaded with what the tool does and communicates the essential distinctions without rambling. Despite its length, it remains well-structured and readable.

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 definition is self-contained: it fully explains success and refusal outputs, specifies when the tool should be used versus alternatives, and notes the extra-call cost. Since there is no output schema, the detailed return-format disclosure is essential and present. No critical operational information needed to call the tool correctly 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?

The input schema has 100% description coverage: it fully documents the single required question parameter and its five aliases (query, q, prompt, text, input). The description itself adds no parameter-level detail, which is acceptable given the schema's completeness. A baseline 3 is appropriate because the schema carries 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 a specific verb and resource: it extracts answers using ONLY the tool result, making it hallucination-resistant. It differentiates itself from sibling ask_pipeworx by emphasizing refusal behavior and the grounded extraction mechanism. The title 'Grounded' is concretely explained rather than left as a vague label.

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 this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') with concrete high-stakes examples. It names the alternative (ask_pipeworx) and the condition to prefer it ('casual lookups'), plus the same-routing relationship. No ambiguity remains about tool selection.

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

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

Annotations 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 already mark the tool as read-only and non-destructive, and the description adds extensive behavioral context: account and paid-plan requirements, parallel decomposition across tools, explicit gaps[] reporting with no invented findings, citation_uri availability rules, hop and contradictions fields, semantic excerpting of large records, and latency expectations. No statement contradicts 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 dense and front-loaded with account requirements, the primary alternative tool, and the core capability before delving into details. It is somewhat long and contains minor repetitions like the repeated 'use ask_pipeworx instead' and 'in one call', but the length is largely justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does: findings packet components, citation URI behavior, gaps[], contradictions[], hop field, fetching semantics, and large-record excerpting. Combined with auth requirements, tier differences, and latency expectations, an agent has enough context to invoke and interpret the tool correctly.

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

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

Both parameters are already fully documented in the input schema, so the baseline is 3. The description adds operational meaning by tying depth choices to paid access and expected latency, and by reinforcing that multi-part questions are appropriate, but most depth behavior is already described in the schema, so a 4 rather than a 5.

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

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

The description clearly identifies the tool as grounded multi-source research over Pipeworx's 1517 structured data sources in a single call, explicitly distinguishing it from open-web search. It also names broad/multi-part questions as the intended use case and contrasts it with ask_pipeworx for single lookups, so an agent can tell what this tool is for.

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

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

The description gives explicit routing guidance: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also states this tool is best for broad/multi-part questions over structured data, providing clear conditions for when to choose it rather than leaving the decision to inference.

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?

Beyond the readOnly/idempotent annotations, the description discloses the multi-source fan-out, the exact returned fields (cik, company_name, resolved_from/to, recent_filings, fundamentals, sources_used/failed), and the meaning of empty sections as real 'no data'. It also explains the private-company resolved:false behavior. No contradiction with annotations.

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

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

The description is long but information-dense, front-loading the core purpose and usage rule before details. Minor redundancy with the schema's type/value descriptions and the 'person/place coming soon' note could be trimmed, but every sentence otherwise 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?

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates returned fields, source fallbacks, resolved_from/to behavior, and edge cases for private companies and empty sections. An agent can call this tool correctly without additional lookups.

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

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

Schema coverage is 100% and already documents both parameters, including the interchangeability of type and the accepted value shapes. The description largely repeats this information, adding only marginal behavioral nuance about resolution outcomes rather than new parameter 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 opens with concrete user intents and states a specific verb+resource: 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes itself from chained single-source lookups and sibling tools by emphasizing the holistic, cross-source nature.

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 gives guidance on input forms and the private-company fallback, leaving little ambiguity about when to use this tool.

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

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

Annotations 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond by disclosing gross vs net spreads (Kalshi fees not modeled), the meaning of null temporal_alignment, unknown legs never paired, and the standing pairing_unverified caveat. No contradiction with annotations.

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

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

The description is long but front-loaded with the core purpose and uses clear section headers (TWO MODES, RESPONSE, SAFETY FIELDS). Every block adds distinct operational knowledge required because there is no output schema; still, some redundancy (e.g., the temporal_alignment caveat appears twice) makes it a 4 rather than 5.

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

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

With no output schema, the description carries the full burden of the return contract, and it delivers: response structure, compatibility codes, per-entry flags, temporal_alignment semantics, fees_note, skipped counters, and a reality-check warning. For a 3-param read-only tool, nothing necessary for correct invocation 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%, so the baseline is 3; the description adds meaningful relational context: topic shortcuts auto-fetch matching events, explicit ticker/slug override the mapped side, and both modes run the identical token-overlap matcher. This lifts it above baseline, though the schema already documents each parameter's format.

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

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

The description opens with a specific verb-resource pair: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes the tool from sibling tools like polymarket_arbitrage by focusing on cross-venue price differences and explicitly constraining it to the same resolving question.

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 names two modes and when each applies: pre-mapped topic shortcuts for ten macro events vs explicit kalshi_event_ticker and polymarket_event_slug for custom pairings. It does not explicitly name sibling alternatives for exclusion, but within-tool mode guidance is clear and includes the practical warning that most pre-mapped topics return compatibility_warning today.

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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes far beyond these: it explains graceful degradation when GLEIF/OpenFIGI are unavailable, the cascading lookup behavior, how unresolved identifiers are explicitly listed under `unresolved`, and that multiple matches yield no assertion but candidates. It also clarifies that non-equity instruments without tickers still resolve. No contradiction with annotations.

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

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

The description is long but densely packed with valuable information, front-loaded with example queries and the 'Use FIRST' directive. It is well-structured with a supported-types breakdown. While slightly verbose, every sentence contributes meaning—no filler. A minor trim could improve, but it remains appropriately detailed for the tool's complexity.

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

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

For a complex tool with no output schema, the description covers almost everything an agent needs: inputs, expected outputs per type, error handling (ambiguous matches, unresolved identifiers, service degradation), source labelling, and even non-US issuer coverage. It preempts common mistakes (e.g., passing full noun phrases for bonds). 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% (both params have descriptions), but the description enriches meaning substantially. For `value`, it adds concrete examples, distinguishes input types, and warns about the pitfall of passing full noun phrases instead of entity names. For `type`, it explains each enum value's output and edge cases like ISIN-to-LEI resolution. This goes well beyond the base 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 states a precise verb-object purpose: resolving a spoken name to canonical identifiers. It enumerates concrete example queries and explicitly names the resource types (company, drug) and the specific identifiers returned (CIK, LEI, FIGI, RxCUI). This clearly distinguishes it from generic search tools and from sibling comparison tools like compare_entities.

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 an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It also details when each type applies, explains the cascade of internal lookups replacing manual steps, and outlines what happens in ambiguous matches (returns figi_candidates). This is excellent guidance for an agent deciding when to invoke this tool versus 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 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.