Ecb

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive. The description adds critical behavioral details: default model is free, Anthropic requires BYO key and direct payment, and the return structure includes per-model scores. No contradictions with annotations.

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

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

The description is a single paragraph that efficiently conveys the core action and key details. It is front-loaded with the main purpose. Could be slightly more structured (e.g., bullet points for return format), but it is not verbose and earns its place.

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

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

Given the tool complexity (4 parameters, no output schema), the description covers purpose, models, key, context, and return shape. It provides sufficient context for an agent to use the tool effectively, though an explicit output schema would reduce reliance on the description.

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 beyond the schema by explaining the default model behavior for 'models' and the purpose of '_apiKey' and 'context'. This helps an agent understand parameter semantics beyond type constraints.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about an entity and scoring visibility. It specifies the default model, the option to add Anthropic, and the return format. This distinguishes it from sibling tools like ask_pipeworx or deep_research, which are for general QA or research.

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

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

The description provides usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the _apiKey parameter. However, it does not explicitly state when not to use this tool or compare it to alternatives, which would strengthen guidelines.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavior: it routes to a tool, fills arguments, returns structured answers with stable citation URIs, and notes it's a fast single call. 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 well-structured: it front-loads the key instruction ('PREFER OVER WEB SEARCH'), provides domain examples, and then explains when to step up. It is detailed but not wasteful; however, it could be tightened by trimming redundant mentions of source types.

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 one required parameter and no output schema, so the description carries full burden. It covers usage triggers, examples, alternatives, citation behavior, and access tiers. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with all six parameters documented as aliases for 'question'. The description does not add parameter-specific meaning beyond the schema, which is already clear. Baseline 3 is appropriate since schema fully covers 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's purpose: it routes factual questions to one of 5,529 tools and returns structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research, and names specific domains (SEC filings, FDA data, etc.).

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?

Excellent usage guidance. It explicitly says to prefer this over web search, provides trigger phrases ('what is', 'look up', 'find'), gives concrete examples, and states 'START HERE for most questions' with step-up alternatives (ask_pipeworx_grounded for grounded answers, deep_research for broad questions).

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context about beta status, active candidate routing improvements, and current equivalence to the stable version, which goes beyond the annotation set. 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?

Four sentences, each serving a purpose: explains beta status, current state, usage guidance, and reassurance. No wasted words, though slightly verbose for a simple tool, but front-loaded with the key beta identification.

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

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

Given the tool's complexity as a beta router with live experiments, the description covers purpose, usage, behavior, and relationship to stable version. It doesn't detail response shape but says it's identical to ask_pipeworx, and the lack of output schema is not a gap since the description addresses return behavior.

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

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

The schema covers all 6 parameters with descriptions, including the main 'question' and alias names, with 100% coverage. The description doesn't add parameter details but confirms same arguments as ask_pipeworx, which is sufficient given high schema coverage.

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

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

The description clearly identifies this as the beta version of ask_pipeworx with identical routing capabilities, distinguishing it from the stable sibling. It specifies the tool's scope (same 5,529 tools, arguments, response shape) and experimental nature, providing a specific verb+resource with sibling differentiation.

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

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

Explicitly instructs to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router. It clarifies it's a full working router with no fallback, but does not explicitly mention when-not-to-use or compare to ask_pipeworx_grounded, so clear context without full exclusions.

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

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

Annotations already mark it readOnly, idempotent, openWorld, non-destructive. The description adds substantial behavioral details: it makes an extra LLM call, extracts answers only from tool results, returns a specific structured response with refusal reasons, and can refuse when data doesn't directly answer. This goes far beyond the annotations and clarifies important constraints.

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

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

The description is longer than the minimalist examples but every sentence serves a purpose: purpose, routing, behavior, return format, use cases, and cost tradeoff. It is front-loaded with the core purpose and follows a logical flow. Slightly verbose but well-structured and not wasteful.

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

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

This tool has no output schema, so the description appropriately explains the return value structure including success and refusal cases. It covers when to use, behavior, return format, and cost comparison with a sibling. Given the complexity of a hallucination-resistant mode, the description is remarkably complete.

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

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

The input schema has 100% coverage with descriptions for all parameters, so baseline is 3. The description does not add parameter-specific semantics beyond what the schema already provides, but it also doesn't need to since the schema is comprehensive.

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

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

Clearly states it is a 'hallucination-resistant answer mode for high-stakes reads' with a specific verb+resource. It distinguishes from the sibling ask_pipeworx by explicitly mentioning 'same routing as ask_pipeworx' and adding extraction and refusal behavior, making the purpose unmistakable.

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

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

Explicitly says when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts', with examples. Also provides when not to use: 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost. This is model 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 indicate read-only, idempotent, non-destructive behavior. The description adds extensive behavioral details: market resolution, classification, parallel fan-out, response shapes, resolver contract, parent_event extraction, news fallback, safety shortcuts, and cancellation rule parsing. 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 very long and detailed, including classifiers, fan-out examples, and response shapes. While well-structured with clear sections, it could be more concise. Some details may be excessive for a tool 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?

Given no output schema, the description thoroughly covers response shapes, evidence structure, market fields, analysis, parent_event, news fields, safety, and cancellation rules. It is complete for understanding what the tool returns.

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

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

Schema covers 100% of parameters with descriptions. The description adds examples for 'market', explains 'depth' and 'include_raw' options, providing additional context beyond schema. Baseline 3, plus value for examples and usage guidance.

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

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

The description clearly states the tool researches a Polymarket bet by pulling relevant data, with examples of input formats and use cases. It distinguishes itself from siblings by focusing on bet-specific research, though it doesn't explicitly contrast with siblings.

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

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

The description provides explicit use cases ('should I bet on X', etc.) and includes safety notes about low-confidence matches and closed markets. It lacks explicit exclusion of when not to use this tool versus alternatives, but the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds critical behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, citation URIs, and efficiency gain (replaces 8–15 lookups). 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?

Description is fairly long but each sentence adds value. Front-loaded with trigger phrases and examples. Could be slightly more concise, but structure is logical and effective.

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

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

Given 2 params, no output schema, and rich annotations, the description fully covers use case, data sources, behavior, return format, and efficiency, leaving no gaps for the AI agent.

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

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

Schema coverage is 100%, baseline 3. Description adds concrete examples for values (tickers/CIKs for company, drug names) and clarifies enum semantics, enhancing understanding beyond the schema.

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

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

Description explicitly states 'side-by-side comparison of 2–5 companies or drugs' and provides clear examples like 'compare X and Y', 'X vs Y'. It distinguishes from sequential single-entity lookups, making the purpose unmistakable.

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

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

Description gives explicit when-to-use trigger phrases ('which is bigger', 'rank these companies') and instructs ALWAYS PREFER over sequential lookups, providing clear context for 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 already declare readOnly/openWorld/idempotent/destructive hints, and the description adds rich behavioral detail: account/paid-tier gate, expected latency (15-90s), output structure (evidence+confidence+source+gaps[]/contradictions[]), guarantee not to invent missing data, and semantic excerpting behavior. No contradictions with annotations.

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

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

The description is lengthy but information-dense, with every sentence contributing a distinct behavioral or usage fact. It front-loads the most critical operational constraint (account required) and uses semicolons to pack details; slight over-length prevents a 5, but there is no fluff.

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

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

Despite no output schema, the description fully specifies return packet semantics, citations, gaps[], contradictions[], latency expectations, source scope, and exclusions. It is complete enough for an agent to select, invoke, and interpret results without additional context.

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

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

Schema covers 100% of parameters with descriptive detail, so baseline is 3. The description adds value by explaining what each depth level does (gap recovery, lead-chasing, contradictions scan), offering example questions, and clarifying account/paid constraints on depth—meaningful 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?

Description states a specific verb+resource: 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that decomposes questions into facets and routes to 5,529 tools in parallel. It explicitly differentiates from ask_pipeworx by identifying scope (broad/multi-part vs single lookup) and from open-web search.

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

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

Provides explicit when-to-use: 'Best for broad/multi-part questions over structured data' and when-not-to: 'For a single lookup use ask_pipeworx' and for current news 'prefer ask_pipeworx.' Also gives account tier requirements and an alternative for non-signed-in users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: it returns top-N most relevant tools with full input schemas and curated examples, and states that results are 'ready to call directly, no second schema lookup needed.' This goes beyond annotations and fully discloses the tool's behavior.

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 4 sentences, front-loaded with the primary purpose. Every sentence adds value: purpose, when to use, what it returns, and a call to action. It is concise without any filler, wasting no 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 complexity (6 parameters, all documented in schema) and no output schema, the description is complete. It covers the return format (top-N tools with schemas and examples), domains it covers, and usage advice. No gaps remain for an agent to understand what the tool does and how to use it.

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

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

Schema description coverage is 100%, so the schema already documents all 6 parameters. The description adds meaning by explaining the 'query' parameter is a 'Natural language description of what you want to do' and lists its aliases (task, q, description, search). It also provides examples in the schema. This adds value beyond the schema, 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's purpose: 'Find tools by describing the data or task.' It uses a specific verb (find/discover) and resource (tools), and distinguishes from sibling tools by emphasizing discovery and browsing, which is unique among the listed siblings.

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

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

The description explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also lists example domains (SEC filings, stocks, etc.), giving clear context on when to use it. This provides strong usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: the rate is a published mid-market reference without bid/ask spread. It also specifies the return format (latest with period and value, plus recent observations). This goes beyond what annotations provide.

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

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

The description is succinct (3-4 sentences) and front-loaded with the core purpose. Every sentence adds value, and there is no redundant or verbose language.

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 exists, but the description explains the return format adequately. It covers main use cases (current rate, historical series) and parameter roles. It could mention error handling or rate limits, but the provided information is sufficient for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the default for last_n (30) and the purpose of start_period/end_period for history. This reduces ambiguity 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 identifies the tool as providing authoritative EUR reference rates from the ECB, listing example queries and target currencies. It differentiates from sibling tools like ecb_hicp_inflation and ecb_list_dataflows by explicitly focusing on exchange rates.

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

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

The description provides explicit use cases ('current EUR/USD rate', 'EURUSD spot', etc.) and explains how to retrieve historical data with start_period/end_period or last_n. It lacks explicit guidance on when not to use this tool or alternatives, but the context is clear enough for an agent.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds minimal behavioral detail beyond the example usage, which is consistent with annotations.

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

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

Two sentences with a concise example, no wasted words. The information is 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 5 parameters all described in schema and no output schema, the description provides sufficient context for typical usage, but could briefly mention the return format.

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

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

Schema coverage is 100%, but the description adds meaningful explanation of the key parameter (dot-separated, wildcards) and lists example flow_ref values, providing context beyond the schema.

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

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

The description clearly states 'Generic SDMX data fetch from any ECB flow', specifying the verb and resource. It distinguishes from siblings like ecb_exchange_rate and ecb_hicp_inflation which are specific 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 an example and explains the key format, implying use for generic ECB data. However, it does not explicitly state when to use this tool versus specific siblings.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds default country and frequency, but does not deepen behavioral understanding beyond annotations.

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

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

Single, well-structured sentence with key information (what, frequency, default) front-loaded. 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 read-only tool with three well-described parameters and no output schema, the description is sufficiently complete. Could optionally mention data format or limitations, but not required.

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

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

Schema coverage is 100% with descriptions for all parameters. Description adds only the default value for 'country', which is useful but not transformative. Baseline 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?

Description clearly states it retrieves the HICP annual rate of change for a country/euro area, with monthly frequency and default country. Distinguishes from sibling ECB 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?

No explicit when/when-not or alternative tool mention, but the name and description clearly indicate it is for HICP inflation data, making usage obvious.

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=true, idempotent=true, destructive=false. Description adds return format {count, dataflows: [{flow_ref, name}]}, fully transparent about output. 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 purpose and examples. 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?

For a simple tool with one optional parameter and no output schema, the description fully covers usage, behavior, and return structure. Complete enough for an agent.

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

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

Schema coverage is 100% and schema describes filter as 'Case-insensitive substring filter'. Description adds that it operates on flow_ref or name, providing context beyond schema. Baseline 3 plus extra detail justifies 4.

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

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

Description clearly states it lists all ECB SDMX dataflow IDs and names, with examples (EXR, ICP, BSI, MIR). This distinguishes it from sibling tools like ecb_exchange_rate or ecb_get_data which operate on specific dataflows.

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?

Describes the optional filter parameter and its behavior (case-insensitive substring on flow_ref or name). Usage guidance is clear, but does not explicitly state when to avoid this tool or suggest alternatives, though siblings imply this is for discovery.

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

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

Beyond annotations (readOnlyHint, etc.), the description details the data sources (SEC, XBRL, USPTO, news, GLEIF), the return structure (cik, filings, fundamentals, patents, news, LEI), and notes the patent sunset and news fallback. This adds valuable behavioral context.

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

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

The description is moderately detailed but well-structured, starting with query examples and then explaining the tool's capabilities and limitations. Every sentence adds value, 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 fully explains the return fields (cik, company_name, filings with URIs, fundamentals, patents, news, LEI) and the parallel execution. It covers all necessary aspects for a holistic profile tool.

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

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

The input schema already provides descriptions for both parameters (100% coverage). The description adds concrete examples ('AAPL', '0000320193') and clarifies that names are not supported, which enhances understanding beyond the schema.

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

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

The description clearly states it returns a full cross-source profile of a US public company, with examples like 'Tell me about X'. It distinguishes itself from chaining multiple single-pack tools, making the purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view', and advises using resolve_entity if only a name is available. This provides 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?

The description's 'Delete' aligns with annotations (destructiveHint=true), and adds context about sensitive data clearing. No contradictions, and it adds value beyond what annotations provide.

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

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

Two sentences: first states purpose, second gives usage guidelines. Extremely concise, front-loaded, and every sentence contributes meaningfully.

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 destructive tool with annotations, the description is complete. It covers purpose, when to use, and references sibling tools, leaving no significant 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?

Only one parameter (key) with 100% schema coverage. The description rephrases 'by key' but adds no new meaning beyond the schema's 'Memory key to delete', 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 'Delete a previously stored memory by key', using a specific verb (delete) and resource (memory by key). It effectively distinguishes itself from siblings remember and recall, which are also mentioned.

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 provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also pairs with remember and recall, offering context for appropriate use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description confirms this with 'Fetches the page, extracts title/description/key links, and emits...' and adds context about the process. No contradictions. Could mention rate limits or error handling but not essential.

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

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

Two concise sentences plus a bullet list of use cases. Front-loaded with the primary action. No redundant or unclear phrases.

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

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

Given simple parameters, full annotations, and no output schema (but description states 'single text blob'), the description fully covers what the tool does, how it works, and when to use it. 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% with both parameters described. Description adds value by stating 'default 25, max 50' for max_links, which is not in the schema. This helps the agent set appropriate values.

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

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

Description clearly states the verb 'Generate' and the specific resource 'production-ready llms.txt file for any URL'. It distinguishes from siblings like 'scan_competitor_ai_presence' by being uniquely focused on llms.txt generation.

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

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

Description lists clear use cases: getting a client's site indexed, drafting own project's llms.txt, auditing competitor indexing. While it doesn't explicitly state when not to use, the use cases imply applicability. No sibling tool overlaps enough to require exclusion.

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

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

The description adds behavioral context beyond annotations: it notes that only active subscriptions are returned by default (not cancelled) and lists the exact fields. The readOnlyHint and idempotentHint are already present, so the description complements them 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 three sentences, front-loading the purpose and return fields, followed by a succinct usage guide. Every sentence adds value, 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?

For a simple list tool with one optional parameter, the description covers the essential aspects: what it returns, when to use it, and how it behaves regarding active vs inactive. It is complete given the tool's complexity.

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

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

The only parameter (include_inactive) is fully described in the input schema (100% coverage). The tool description does not add additional meaning or usage context for this parameter beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('List') and the resource ('caller's active subscriptions'), and lists the specific fields returned. This directly differentiates it from sibling tools like subscribe and unsubscribe.

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

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

Explicit guidance is given: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to invoke the tool relative to subscribe/unsubscribe.

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 richly covers behavioral traits beyond annotations: it discloses the claim_token workflow, rate limiting ('Rate-limited to 5 per identifier per day'), quota implications ('doesn't count against your tool-call quota'), and how feedback is processed ('team reads digests daily'). This goes far beyond the sparse annotation hints.

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

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

The description is longer than typical but front-loaded with the core purpose. Each subsequent sentence adds essential information (scope, claim_token flow, rate limits), though it could be tightened slightly without losing value. The structure is logical: purpose → when-to-use → exclusions → workflow → constraints.

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

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

Given there is no output schema, the description compensates by explaining what the tool returns ('Filing without an account returns a `claim_token`') and how to later interpret status. It also covers the nested context object, type enum semantics, rate limits, and quota impact, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for the claim_token parameter (explaining the round-trip flow: 'pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and clarifies how message should be phrased ('don't paste the end-user's prompt'), which enriches the schema's baseline 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 starts with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This unambiguously identifies the tool as a feedback mechanism and clearly differentiates it from siblings like ask_pipeworx or remember, which serve other purposes.

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' conditions for each feedback type ('Use when a tool returns wrong/stale data... or when something worked surprisingly well'), and explicitly excludes out-of-scope cases with 'ONLY for tools served by this Pipeworx connection... file it with that server instead.' This is an exemplary usage guideline.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context: 'Self-aggregating signal — derived from CF analytics-engine, no PII' and 'Cached 5min-1h depending on window.' This discloses data source, privacy, and caching behavior, adding significant value beyond annotations.

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

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

The description is well-structured with numbered use cases and concise sentences. Every sentence adds value, and there is no redundancy. The length is appropriate for the complexity of the 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?

Despite no output schema, the description explains the return: 'top tools, top packs, and total call volume.' It also mentions caching behavior. Given the tool's simplicity (single optional parameter), the description is complete and sufficient for an agent to invoke it correctly.

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

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

The schema already has 100% coverage with an enum and description. The description adds: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides additional guidance for parameter selection, 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's purpose: returns top tools, top packs, and total call volume. It lists three specific use cases, making it easy to understand when to use it. The description distinguishes this analytics tool from sibling tools like ask_pipeworx or discover_tools.

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

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

The description explicitly lists three useful scenarios (discovering hot data sources, confirming canonical tools, aligning use cases). While it does not mention when not to use it, the context is clear enough to guide agent selection. No direct alternatives are named, but the use cases are specific.

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, openWorldHint, idempotentHint – description adds rich behavioral context: it walks child markets, checks date-axis/threshold ordering, computes partition sum, uses Jaccard similarity filter, drops placeholder slugs, and performs fill check against CLOB depth. No contradictions.

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

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

The description is dense but well-structured: first sentence states purpose and default mode, then elaborates each parameter. Could be slightly more concise but every sentence adds value. 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 complexity (multiple modes, algorithmic details, fill check) and no output schema, the description is remarkably complete. It covers response structure, limitations, edge cases (placeholders, similarity threshold), and cross-references to sibling tool for custom sizing.

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

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

Schema coverage is 100% with descriptions for both event and topic. The description adds substantial meaning beyond schema: explains what each parameter triggers (single-event mode vs cross-event mode), details the subtools within each mode (partition check, fill check).

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 "Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks". It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by specifying its unique approach.

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?

Guidance is explicit: call with NO args for trending scan, pass event for specific market, pass topic for cross-event scan. It recommends event mode. However, it lacks explicit when-not-to-use or direct comparisons to siblings, so it's very good but not perfect.

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

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

Beyond annotations, the description discloses caching behavior, response structure including diagnostics, data sources (FRED, GDELT), filter skips, Fed bets exclusion, and details on edge computation. This goes well beyond the read-only and idempotent hints.

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

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

The description is long but front-loaded with the core purpose, followed by structured sections. Every sentence adds value, though some details could be condensed. No fluff.

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

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

Given the complexity (9 parameters, 3 segments, no output schema), the description thoroughly covers return structure, diagnostics, caching, and edge cases. It compensates fully for missing output schema.

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

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

Each parameter has a detailed description in the schema. The tool description adds extra semantics, e.g., explaining slippage_pp in context of Polymarket fees, why min_kelly doesn't filter partitions, and tradeable-edge knobs. It provides 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?

The description clearly states it scans Polymarket markets for discrepancies with Pipeworx data, and is built for daily betting discovery. It distinguishes from siblings by detailing three segments (model-driven, structural arbitrage, concentrated longshot) and specific models.

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

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

The description explicitly says it's for 'what should I bet on today' and avoids paging through hundreds of markets. It provides clear context but does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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

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

Annotations indicate read-only, idempotent, non-destructive. The description adds extensive behavioral context: data source, trend computation, response structure (tracked with time-series, expired with lifespan, snapshot dates), and notes on interpretation of signed edge_pp_net.

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 long but efficiently organized: starts with core concept, then details response fields and limitations. Every sentence provides value, though could be slightly trimmed.

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

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

Given the complexity (time-series, multiple response arrays, trend calculation) and no output schema, the description thoroughly explains every aspect of the tool's output and behavior, making it fully understandable.

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

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

Schema coverage is 100%, but the description adds meaning by explaining days as lookback with defaults and window as snapshot family with listed options. It clarifies the purpose of each parameter beyond the schema.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. This distinguishes it from siblings like polymarket_edges and polymarket_arbitrage.

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

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

The description gives context on when to use (e.g., differentiating fresh vs aged edges) and lists limits like 60-day snapshot TTL and decay from daily closes. It lacks explicit exclusions 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?

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description aligns perfectly and adds rich behavioral context: walks the order book ladder, returns fill prices, slippage, verdicts, warns about thin books and forced directional risk. No contradiction; the description supplements the annotations comprehensively.

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 information-dense and well-structured: starts with purpose, then required params, then mode-specific details. Every sentence adds value, though it could benefit from bullet points for easier parsing. It is appropriately sized given the tool's complexity.

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

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

Despite no output schema, the description exhaustively lists return fields for both modes, including edge cases (thin_legs, forced_directional_risk). It covers clamp behavior, defaults, and usage constraints, making the tool fully understood without needing to invoke it blindly.

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

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

Schema description coverage is 100% but the description adds significant value beyond the schema: explains interpretation of size_usd for both modes, default behaviors, clamping, and side auto-detection for basket mode. This provides the agent with clear, actionable 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 clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and defines two distinct modes (single-market and basket) with specific use cases. It differentiates from siblings like polymarket_arbitrage by explicitly stating when to use it before executing trades.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains consequences of misuse (theoretical overround not capturable, partial fills leading to unhedged directional positions), leaving no ambiguity about when to apply the 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?

Beyond annotations (read-only, idempotent), the description details response structure (leg-by-leg prices, spreads), safety fields (compatibility_warning, temporal_alignment), and edge cases (non-equivalent bet shapes). 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 thorough but verbose, covering many details in a single paragraph. Front-loads purpose and modes, but could be more concise by splitting into sections.

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, yet the description fully explains the response including safety fields (compatibility_warning, temporal_alignment, skipped counters). Handles complex behavior and multiple scenarios adequately.

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

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

Schema coverage is 100%, but the description adds value by explaining the topic list and how explicit tickers override the topic-mapped side. This context is helpful for using the tool correctly.

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

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

The description clearly states the tool computes the 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' using specific verbs like 'auto-fetch' and 'custom pairings'. It distinguishes from sibling tools by focusing on cross-venue comparison, unlike poly market-only 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 explains two modes (topic shortcuts vs explicit identifiers) and warns that pre-mapped topics often yield compatibility warnings, implying when not to rely on results. It provides clear context for each mode but could explicitly state when to avoid the tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail (anonymous IP, BYO key hash, account ID) and listing behavior, which goes beyond annotations without contradiction.

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

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

Three sentences, each serving a purpose: main action, usage context, and pairing with siblings. No redundant words. Front-loaded with key verb and resource.

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 retrieval tool with one optional parameter, good annotations, and no output schema, the description covers purpose, behavior, scoping, and usage without 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?

Only one parameter 'key' with schema description. Description adds meaning by explaining that omitting key lists all keys, which is consistent with schema and examples.

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

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

Description clearly states the tool retrieves a previously saved value or lists all keys if argument omitted. Verb 'retrieve' and resource 'value previously saved via remember' are specific. Distinguishes from sibling tools remember and forget by mentioning pairing.

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: look up stored context without re-deriving. Mentions scoping and pairing with remember/forget. Lacks explicit when-not-to-use, but context is clear enough.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable context: it details the data returned (source, citation_uri, raw payload) and the effect of mark_read on future calls. No contradictions with annotations.

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

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

The description is well-structured: purpose first, then return data, filters, mark_read behavior, and polling note. Every sentence adds value without redundancy or verbosity.

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

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

The description covers the return structure (source, citation_uri, payload) despite no output schema, and explains all parameters. It is complete enough for a simple polling 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?

All parameters are documented in schema (100% coverage), so baseline is 3. The description enriches parameters with examples (e.g., 'sec_8k' for type) and explains behavior of mark_read and since, providing meaning beyond the schema.

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

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

The description clearly states the tool pulls fired events from the subscription feed and specifies the returned data (source, citation_uri, payload). It explicitly distinguishes from sibling tools like list_subscriptions by focusing on alerts, and mentions an alternative access method for scripts/dashboards.

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 suggests polling use and gives an alternative endpoint, implying when to use this tool. However, it does not explicitly compare to sibling tools or state when not to use it, so it lacks clear exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds details on multi-source fan-out, GDELT preference, GNews fallback, and USPTO soft-fail. 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?

Concise yet thorough. Front-loaded with example queries. Every sentence adds value without redundancy.

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

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

Complete for a tool with 3 parameters and no output schema. Covers inputs, sources, fallback behavior, return structure, and alternative 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%, baseline 3. Description adds useful guidance: 'type' only supports 'company', examples for 'since' (ISO/relative), and ticker/CIK formats for '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 the tool returns a change feed for a company (SEC filings, news, patents) in recent days/weeks/months. It provides example queries and distinguishes from sibling tool 'entity_profile'.

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

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

Explicitly tells when to use (for 'What's new' queries) and when to use 'entity_profile' instead. Also explains fallback behavior (GDELT→GNews) and provides advice on the 'since' parameter.

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

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

The description adds significant behavioral context beyond annotations: scoping by identifier, persistence duration (24 hours for anonymous, permanent for authenticated), and confirms it's a write operation. No contradictions with annotations.

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

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

The description is four sentences, front-loading the primary purpose. Every sentence adds value: purpose, usage guidelines, scope details, and companion tools. 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?

For a simple tool with two required parameters and no output schema, the description covers all necessary context: what it does, when to use, scoping, persistence, and companion tools. Complete and 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?

The schema already describes both parameters (100% coverage). The description adds valuable examples for key ('subject_property', 'target_ticker') and value ('findings, addresses'), enriching understanding beyond the schema.

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

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

The description clearly states the tool saves data for later reuse, specifying the resource (key-value pair) and the action (save). It provides concrete examples like 'resolved ticker' and distinguishes from sibling tools by naming recall and forget.

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

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

The description explicitly says when to use the tool ('when you discover something worth carrying forward') and implies it's for persistent storage across sessions. It also recommends pairing with recall/forget, providing clear guidance. Lacks explicit exclusions.

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

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

Even though annotations already declare readOnly, openWorld, and idempotent hints, the description adds substantial behavioral context: it cascades through several lookup endpoints, uses multiple external sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), labels identifiers with their source, explicitly lists unresolved identifiers under `unresolved`, and degrades gracefully if GLEIF/OpenFIGI are unavailable. This is rich transparency beyond the annotations.

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

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

The description is long but well-structured, beginning with example queries and then clearly partitioning supported types and behaviors. Every sentence contributes useful information, though the extensive detail could be condensed slightly. It is front-loaded with practical examples, making it easy to skim, but the proliferation of parenthetical explanations makes it a bit dense.

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 types, multiple data sources, enriched identifiers, fallback behavior) and the lack of an output schema, the description covers all essential aspects: inputs, outputs, source identification, unresolved handling, and degradation gracefully. It provides enough context for an agent to invoke the tool correctly and interpret results, making it complete for its 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?

The schema already covers both parameters with descriptions, but the tool description adds significant meaning: it specifies accepted formats for `value` (ticker, CIK, company name for company; brand/generic for drug), explains what each type returns, and describes the `unresolved` field and source labels. This goes well beyond the schema's basic descriptions, providing operational 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's purpose: resolving user-spoken names to canonical/official identifiers. It uses a specific verb ('resolve'), names the resource ('canonical/official identifiers'), and provides numerous example queries ('What's the ticker for…') that illustrate usage. It also differentiates from siblings by instructing 'Use FIRST whenever you have a name but need an ID,' positioning it as a foundational lookup tool.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also explains what inputs are accepted for each type, what outputs to expect, and notes that it 'replaces 2-3 manual lookups.' This provides clear context for selection without explicitly enumerating alternatives, but the directive is strong and unambiguous.

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 readOnly, idempotent, and non-destructive. The description adds behavioral details beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns a list with score, confidence, and 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?

The description is concise (4 sentences), front-loaded with the main purpose, and every sentence adds value. 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 no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It covers input parameters and notes the special handling of the first entity. Complete for a comparison tool.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description does not add new parameter semantics beyond what is in the schema. Baseline 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 uses a specific verb ('Compare AI visibility across multiple entities side-by-side') and clearly identifies the resource (AI presence). It distinguishes itself from sibling tools like ai_visibility_check by noting it probes multiple entities and ranks them.

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 it is 'useful for competitive AI-marketing audits' and gives an example query. It does not explicitly mention when not to use it or list alternative tools, but the intended use case is clear from the context.

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

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

Annotations already indicate read-only, open-world, and idempotent behavior. The description adds critical behavioral details: bundlephobia's first measurement can take 5-30 seconds, and partial failures degrade gracefully (sources_failed list). This goes beyond annotations.

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

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

Concise yet comprehensive: 120 words, front-loaded with purpose and usage, then behavioral details and return fields. No wasted sentences.

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

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

Despite no output schema, the description fully explains the return value: summary block fields, per-advisory details, links, and alternative versions. This is contextually complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds value by clarifying that scoped packages (e.g., @types/node) are accepted and version defaults to latest. These are useful for correct invocation.

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 defines the purpose as a composite check for npm package evaluation using deps.dev and bundlephobia. It distinguishes from sibling tools by specifying the ecosystem and the type of analysis (license, advisories, bundle size, tree-shaking).

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: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also clarifies the limitation to NPM ecosystem, directing users to deps.dev for other ecosystems.

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 show readOnlyHint, idempotentHint. Description adds: returns passages with offsets and scores, uses BGE embeddings, 500-char windows, 200K char cap with truncation flag. No contradictions.

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

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

Well-structured with purpose first, then usage, then technical details. Slightly long but each sentence is informative. 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?

No output schema, but description explains return format (passages with offsets and scores) and technical behavior. All essential context is present.

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

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

Schema covers 100% of parameters with descriptions. Description adds examples for query and reiterates cap for text, adding marginal value beyond schema.

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

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

Clearly states the tool does semantic search inside a provided text, with specific examples (SEC 10-K, article). Distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and use case for large records.

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

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

Explicitly says to use when the record is too large for the prompt, saving context. Mentions pairing with another tool for grounding. Lacks explicit 'when not to use' but clear context suffices.

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

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

Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds critical details: auth requirements, subscription types, delivery channel behaviors (SMS cap, webhook signing), and the return of subscription id, all consistent 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 dense but well-organized, with core purpose first then details. Could be slightly more structured (e.g., bullet points) but every sentence adds value.

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

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

Given no output schema, the description adequately covers purpose, auth, types, delivery, and idempotency. It also positions the tool among many siblings, making its role clear.

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

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

Schema coverage is 100%, but the description significantly enriches param understanding with concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topics) and delivery constraints (E.164, verified phone, webhook HMAC), going well beyond the schema's own description.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource, and it uniquely distinguishes from sibling tools 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?

The description specifies the requirement of a Pipeworx OAuth account and provides type-specific examples and delivery constraints. It implicitly differentiates from read-only tools but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: it returns categorized examples with exact tool+argument shape, drawn from a live catalog. 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?

Front-loaded with user-facing aliases ('What can I ask Pipeworx?') and concise purpose. Every sentence adds value: usage example, topic parameter, and outcome 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?

No output schema, but description fully explains what is returned (category-bucketed examples with tool+argument shape). Covers all lookup and discovery capabilities for a new agent.

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

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

Schema coverage is 100% (the optional topic param is described). Description adds beyond schema: enumerates valid topic values (finance, pharma, etc.) and explains that omitting topic gives a cross-category spread.

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

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

Description uses specific verbs ('returns category-bucketed example questions') and identifies the exact resource ('the onboarding entry point'). It distinguishes from siblings like ask_pipeworx and entity_profile by framing this as the discovery tool.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to pass the topic parameter. 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?

Description adds significant context beyond annotations: deactivation (not deletion), historical events stay via recent_alerts, and ownership enforcement. Consistent with annotations (destructiveHint=false).

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

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

Three concise sentences, front-loaded with the action, no fluff. Every sentence adds value.

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

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

For a single-param tool with no output schema, description covers purpose, constraint, effect, and link to recent_alerts. Fully adequate.

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

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

Schema description coverage is 100% for the single parameter 'id' (uuid from subscribe). Description adds minimal parameter-specific info beyond purpose 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?

Description clearly states the verb 'Cancel' and resource 'subscription', specifies ownership enforcement and that the row is deactivated not deleted. Distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Description explicitly says ownership is enforced, guiding the agent to use it only for own subscriptions. Does not mention alternatives for canceling others' subscriptions, but the constraint is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond these: it explains the fast path vs. grounded pipeline, details the verdict values, describes the failure mode 'could_not_verify' as 'NOT evidence for or against the claim', and clarifies 'unsupported' semantics. It also reveals the efficiency benefit (replaces 4–6 calls). This goes considerably beyond the annotations and is consistent with 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 long but every sentence earns its place. It opens with concrete query examples to anchor the input format, then briefly explains the dual pipeline, lists return values, and delivers critical caller guidance about error semantics. The structure is logical and front-loaded, and the length is proportional to the tool's complexity. No filler or redundant repetition of schema/annotations.

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 fully complete for a tool of this complexity. It explains the two routing paths, the verdicts, the citation format, the handling of edge cases (could_not_verify vs. unsupported), and the efficiency gain. Since there is no output schema, the description's explanation of the return structure is essential and sufficient. It leaves no critical behavioral question unanswered.

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?

Even though schema coverage is 100%, the description adds meaningful semantics beyond the schema. For 'claim', it gives natural-language examples and emphasizes the 'natural-language factual claim' format. For 'tolerance_pct', it explains the default behavior ('implied by wording, capped at 5'), how to override it, and provides a specific recommendation (set 1–2 for hallucination detection). This helps the agent select and populate parameters correctly beyond the schema's basic 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: verifying natural-language factual claims against authoritative sources. It provides multiple example phrasings ('fact check', 'verify the claim that…'), explicitly mentions the return verdict types, and distinguishes itself from siblings by noting it replaces 4–6 sequential calls. The verb 'verify' and resource 'claims' are specific, and it differentiates from other tools like ask_pipeworx_grounded by focusing on claim verification rather than general queries.

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

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

The description gives explicit usage guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also specifies two distinct routing paths (company-financial claims via SEC EDGAR fast path, all other claims via the grounded pipeline), which tells the agent exactly when this tool is appropriate. It further implies that for non-fact-checking queries, other tools like ask_pipeworx should be used, providing effective context for tool selection.

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