Eia

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

Annotations already mark readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds cost/key details and output structure (per-model score, confidence, signals, raw_response + combined view), providing extra behavioral context beyond annotations.

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

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

Four sentences, front-loaded with the main action, then details on models, key, and use cases. No wasted words; structure is efficient.

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

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

Given the tool's complexity (multiple models, optional key, score output), the description covers all essential aspects: action, default, optional parameters, return shape, and use cases. No output schema, but return is described.

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 tool description adds value by explaining default model, Anthropic key requirement, and context disambiguation, plus return format, exceeding baseline.

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

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

The description clearly states it probes LLMs for entity knowledge and scores visibility (0-100). It specifies default model and optional Anthropic probing, distinguishing it from sibling tools that focus on Pipeworx, research, or other domains.

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 notes use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies context but does not contrast with alternative tools or state when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it routes to one of 5,529 tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and works on every tier with one fast call. This goes beyond the annotations without contradicting them.

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

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

The description is front-loaded with the most important directive and organized into guidance, examples, and escalation logic. It is longer than strictly necessary, but every sentence serves a purpose; the examples and alternative-naming add practical 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 tool with no output schema, the description is remarkably complete: it explains what types of questions to route here, what the tool does internally, what output to expect (structured answer with citations), and how it relates to siblings. It also notes current data/historical data coverage, making it sufficient 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 coverage is 100% and aliases are fully documented in the input schema, so the description does not need to explain parameter meaning. The description contributes example queries, which are helpful but do not add structural parameter semantics beyond what the schema already provides.

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

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

The description opens with an explicit directive to prefer this tool over web search and specifies a broad but well-defined resource: factual questions about real-world entities, events, and numbers. It clearly distinguishes the tool from siblings like ask_pipeworx_grounded and deep_research, making the purpose immediately identifiable.

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 user asks...' and 'START HERE for most questions.' It also names concrete alternatives and when to step up to them (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), which 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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses that routing behavior can change when candidates are under test, and that results are compared against the stable router. It also states explicitly that it falls back to nothing, reinforcing it is a complete tool. This adds valuable temporal context not captured in annotations.

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

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

The description is slightly long but well-structured: it opens with the core identity (beta, identical router), then covers current state, usage, and fallback behavior. Each sentence adds necessary information; no wasted words, though it could be tightened slightly without losing meaning.

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 router tool with no output schema and 5,529 referenced tools, the description adequately explains the tool's purpose, current behavior, and relationship to ask_pipeworx. It references the response shape implicitly via 'same response shape' as ask_pipeworx, which is sufficient given the sibling context, and clarifies it is a complete working router.

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 documents all 6 parameters, with 100% coverage, all being aliases for 'question.' The description adds no additional parameter semantics, so the baseline of 3 applies as the schema does the heavy lifting.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,529 tools and arguments. It distinguishes itself from the stable sibling by stating it has 'candidate routing improvements enabled live' and currently matches ask_pipeworx exactly, which removes ambiguity.

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

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

Explicit usage guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no active candidates, so it matches ask_pipeworx) and that it is a fully working router, not a fallback, which helps the agent decide when to choose this over 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?

The description details the refusal behavior with specific refusal_reason enum values, the return object structure with evidence as a verbatim quote, and the fact that answers are limited to tool result content. This goes beyond annotations which only mark readOnly, openWorld, idempotent, and non-destructive flags.

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

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

Three sentences front-load the core value proposition, then explain mechanism, return format, use cases, and cost tradeoff. No wasted words; all content is relevant and structured.

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

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

With no output schema, the description fully specifies the return object and all possible refusal_reason values. It also covers the tradeoff of an extra LLM call and gives example high-stakes use cases. Complete for an agent to decide when to call 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?

Input schema already covers all parameters (100% coverage) and includes alias descriptions. The description adds context that the question is used to route to one of 5,529 tools and fill arguments, explaining how the content is processed, but does not add new parameter-specific semantics.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly identifying the tool's purpose. It further specifies that it routes through the same tool selection as ask_pipeworx but extracts answers only from tool results, distinguishing it from the sibling ask_pipeworx.

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 whenever an answer will be quoted, cited, or acted on...' and names the alternative ask_pipeworx for casual lookups with a cost tradeoff. Provides both when-to-use and when-not-to-use.

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

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

The description extensively details behavior beyond annotations: low-confidence resolutions, closed markets, wide spreads, resolution-rule risk, and blocking mechanisms. It adds significant value and does not contradict the readOnlyHint 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, containing many details in prose. It is front-loaded with the main purpose but could be more concise or organized with bullet sections. While structured with headers, the length reduces clarity.

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

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

Given the complexity (3 params, no output schema), the description covers input variations, fan-out examples, response shapes, edge cases, and safety mechanisms. It provides complete guidance for an agent to use the tool correctly, including resolver contract and parent event extraction details.

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 three parameters are described with additional examples and context (e.g., market input formats, depth options). Schema coverage is 100%, so baseline is 3; the description goes further by explaining behavior like raw data vs. summaries, thus adding 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's purpose: researching a Polymarket bet by fetching Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings like polymarket_edges by being a comprehensive research tool.

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

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

The description explicitly states when to use: for questions like 'should I bet on X' and provides examples. It doesn't explicitly say when not to use, but the detailed behavior and context imply exclusive use for deep analysis. It offers clear scenarios but lacks direct comparison with alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds detailed behavioral traits: pulls latest 10-K financials from SEC EDGAR/XBRL, handles off-calendar fiscal years, for drugs pulls FAERS counts, returns sorted results with citation URIs. This significantly enriches annotation 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 long but front-loaded with common user phrases. Every sentence adds value, though the example phrases could be slightly trimmed. Overall it is well-structured and informative.

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

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

For a complex tool comparing two entity types with different data sources, the description covers input constraints (2-5 items, min/max), data sources, handling of fiscal years, return format (paired data with citations), and sorting. No output schema exists, but the description adequately describes the output.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema: explains that type='company' pulls specific financials and type='drug' pulls adverse-event counts, and clarifies values are tickers/CIKs or drug names. This provides domain-specific context.

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

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

The description starts with natural language triggers like 'Compare X and Y' and states it performs side-by-side comparison of 2-5 companies or drugs. It explicitly says 'ALWAYS PREFER over sequential single-pack lookups', distinguishing from sibling tools like 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?

The description gives clear context for use: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and notes it replaces 8-15 sequential lookups. While it does not explicitly list exclusions, the guidance implies it is for comparison tasks only.

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 extensive context beyond the annotations: account requirements, pricing tiers, parallel decomposition, gaps[] with 'never invented', contradictions[], fetchable citation_uri, hop field, semantic excerpting, and latency expectations. No contradiction with annotations exists; the readOnlyHint, openWorldHint, and idempotentHint are all supported by the described 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 long but every sentence carries meaningful details—account prerequisites, data source types, internal routing, output packet structure, use-case boundaries, and performance expectations. It is front-loaded with the critical account requirement and purpose, but the density of detail could benefit from brief structural organization.

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

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

With no output schema, the description fully explains return values: findings packet with evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], and hop field. It also covers edge cases (empty gaps, unresolvable citations) and performance expectations. Given the tool's complexity, this is comprehensively 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?

Even though schema coverage is 100%, the description adds substantial meaning: it clarifies that 'question' can be broad/multi-part and elaborates on each depth value ('quick', 'standard', 'thorough') including hop counts, gap recovery, contradiction scanning, and paid status. This goes well beyond the schema's enum 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 performs 'grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources in ONE call' and explicitly contrasts it with ask_pipeworx, distinguishing it from siblings. The verb 'research' plus the resource scope is specific and unambiguous.

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

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

Provides explicit guidance: 'Best for broad/multi-part questions over structured data' and tells users to prefer ask_pipeworx for breaking news or single lookups. It also explains depth-level selection and when each is appropriate, giving clear when-to-use and when-not-to-use instructions.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, which the description aligns with. The description adds value by detailing the return format: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 yet dense, front-loading the purpose and following with usage guidance, return format, and call ordering. Every sentence contributes meaningful information, with no redundancy or 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 absence of an output schema, the description thoroughly explains the return value (top-N tools with schemas and examples). It addresses the tool's role in exploration, and the parameter descriptions in the schema complement the narrative. No gaps remain for this discovery tool.

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

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

Schema coverage is 100% as all 6 parameters have descriptions. The description adds value by summarizing that parameters are aliases for 'query' and clarifying that 'limit' controls the result count. This helps an agent understand the intended usage despite multiple parameters.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and contrasts with sibling tools that are domain-specific, setting this apart as a meta-tool for discovery.

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

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

The description explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear usage context, though it could more directly state when not to use it (e.g., if the target tool is already known).

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

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

The description discloses that an API key is required and lists covered fuel sources (coal, natural gas, etc.), adding value beyond the annotations (readOnlyHint, etc.). It does not contradict annotations. However, it lacks details on rate limits, pagination, or data range limitations.

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

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

The description is two sentences long, front-loaded with the purpose and key details. Every sentence adds value (data series, return format, auth requirement, fuel sources).

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 presence of an output schema and rich annotations, the description adequately covers the tool's purpose, required auth, data series options, and covered fuel sources. Minor omission: no mention of date range constraints or typical use cases.

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 describes all 5 parameters (100% coverage). The description adds context about the return format ('time series with period and value') and the fuel sources covered, but does not elaborate on each parameter beyond what the schema provides.

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

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

The description explicitly states 'Get EIA electricity data for a named series' and lists the available series (generation, retail_sales, prices, state_generation), clearly distinguishing it from sibling tools like eia_ethanol or eia_natural_gas by focusing specifically on electricity.

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

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

The description implies when to use the tool (when you need electricity data) but does not provide explicit guidance on when to prefer this tool over alternatives like eia_natural_gas or eia_petroleum. No comparisons or exclusions are given.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds that it uses EIA petroleum supply data filtered by product code EPOOXE, which provides useful sourcing context beyond annotations.

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

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

Two sentences plus a brief note efficiently convey the tool's purpose and key context without verbose or redundant information. Every sentence adds value.

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

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

Given the output schema exists and annotations are rich, the description is sufficient: it covers purpose, data source, and product code. It could mention default frequency or date handling, but completeness is adequate for the complexity.

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

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

With 100% schema coverage, the description adds value by mentioning the product code EPOOXE and the data source, complementing the schema's parameter descriptions. It helps the agent understand the context of the series 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?

The description clearly states it retrieves fuel ethanol production, stocks, and imports time series, distinguishing it from sibling tools like eia_electricity, eia_natural_gas, and eia_petroleum by focusing on a specific commodity within petroleum data.

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

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

The description provides context (energy-agriculture intersection, corn-based ethanol, EIA petroleum data) but does not explicitly state when to use this tool versus alternatives like eia_petroleum or eia_series for broader queries.

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. The description adds that it 'Returns period, value, and area metadata' and requires an API key, providing useful behavioral context beyond annotations. No contradictions.

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

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

The description is two sentences, front-loaded with the core purpose. The second sentence provides optional examples of included series. No extraneous information, though it could be slightly more streamlined.

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 (5 parameters, 100% schema coverage, output schema present, informative annotations), the description covers purpose, required key, series options, and return structure. It includes specific data examples, making it sufficiently complete for agent usage.

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

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

Schema coverage is 100%, so baseline is 3. The description repeats the series values and mentions the API key requirement but does not add new parameter semantics beyond the schema.

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

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

The description clearly states the tool retrieves EIA natural gas time series and lists the specific series options (prices, production, consumption, storage, spot_prices). It distinguishes itself from sibling EIA tools (e.g., eia_electricity, eia_petroleum) by focusing on natural gas data.

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

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

The description implies usage for natural gas data but does not provide explicit guidance on when to use this tool versus alternative EIA series tools. No 'when not to use' or comparison to siblings, though the series list and requirement for an API key offer some context.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint false), description adds that it returns prices/volumes with regional breakdowns and requires an API key. Complements annotations well 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?

Front-loaded with purpose, but contains redundancy ('supply, production, and imports' appears twice). Two sentences with a minor typo; could be more polished.

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 and existing output schema, description covers basics (return type, regional breakdowns, API key). Lacks details on error handling, data ranges, or rate limits, but sufficient for a simple retrieval tool.

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

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

Schema coverage is 100% so baseline 3. Description repeats product list from schema but does not add new parameter details beyond mentioning 'frequency defaults vary by product'. Adequate but not enhanced.

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 retrieves EIA petroleum time series data for specific products, listing examples. It distinguishes from generic EIA tools by mentioning 'simplified interface to common EIA petroleum series', though it could better contrast with sibling eia_series.

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 guidance on when to use this tool versus siblings like eia_series or other EIA tools. The phrase 'simplified interface' implies it is for common queries but does not specify alternatives or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the tool 'Returns historical data points with timestamps and values' and 'Returns time series with period, value, and metadata,' which provides useful context beyond annotations. 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 at just a few sentences, front-loaded with purpose, and includes helpful examples. Every sentence adds value without repetition.

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

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

Given the tool's complexity (6 params, 2 required), 100% schema coverage, and existing output schema, the description sufficiently covers purpose, usage guidelines, and return format. It mentions 'time series with period, value, and metadata,' which is adequate when combined with the 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?

Schema description coverage is 100%, so the baseline is 3. The description adds examples of route paths inline, but the schema already contains detailed parameter descriptions, including the route parameter with many examples. The added value is marginal.

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: 'Search EIA for any energy data series by route path.' It distinguishes from sibling category-specific tools by saying 'Use for specific energy metrics not covered by category tools,' and provides concrete examples of route paths.

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 tells when to use this tool vs alternatives: 'Use for specific energy metrics not covered by category tools.' This directly guides the agent toward this tool for general series queries and away from category-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?

Discloses that USPTO API sunset May 2025 soft-fails, uses GDELT→GNews fallback for news, and provides details on returned fields. Adds behavioral context beyond annotations (readOnly, idempotent). 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 moderately long but well-organized with examples and clear sections. Information is front-loaded with example queries and key behavior summary.

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

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

Given no output schema, description explains returned fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI). Covers edge cases (USPTO sunset, name not supported). Tool is self-contained.

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

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

Schema coverage 100%, but description clarifies that value accepts ticker or zero-padded CIK, and that names are not supported. Adds context beyond schema (e.g., 'zero-padded CIK').

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 returns a 'full cross-source profile of a US public company in ONE parallel call' and lists specific data sources and fields. It distinguishes from siblings by explicitly preferring over chaining single-pack lookups.

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

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

Provides explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also instructs to use resolve_entity first if only a name is available.

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 destructiveHint=true and idempotentHint=true, so the description's mention of deletion adds little. It does add context about clearing sensitive data, but no new behavioral traits beyond annotations.

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

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

Two sentences, front-loaded with the action, no wasted words. Efficient and clear.

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

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

For a simple tool with one parameter and good annotations, the description covers the essential context. Could mention idempotency or success/error return, but not necessary given simplicity. Score 4 for minor gap.

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

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

Schema coverage is 100% (the single parameter key is described). The description does not add additional meaning beyond the schema, so 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 clearly states the action (Delete), the resource (previously stored memory by key), and distinguishes from siblings by mentioning pairing with remember and recall.

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

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

Explicitly specifies when to use the tool: when context is stale, task is done, or to clear sensitive data. Also advises pairing with remember and recall, providing clear workflow 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 details the process (fetches page, extracts title/description/links, emits standard markdown) beyond what annotations provide. Annotations indicate readOnlyHint and idempotentHint, and the description's explanation of fetching and extracting aligns with these. 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 (three sentences) and front-loaded with the main purpose. Every sentence adds value: primary function, process summary, and use cases. No filler or repetition.

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

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

Given the tool's simplicity (2 parameters, no output schema, straightforward behavior), the description covers all necessary context: what it does, how it works, what the output is, and typical use cases. Annotations already convey safety, and the description fills in behavioral details.

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

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

Schema coverage is 100% with clear parameter descriptions for url and max_links. The description adds no additional parameter information beyond what the schema provides, so it meets the baseline of 3 but does not exceed it.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with a specific verb (generate), resource (llms.txt file), and goal (AI crawler indexing). It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning or checking.

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 (e.g., getting a client's site indexed, drafting for own project, auditing competitors) but does not directly contrast with sibling tools or specify when not to use this tool. The context signals list siblings, but the description lacks explicit alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds minor context about default parameter behavior (include_inactive default false) but does not contradict annotations.

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

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

Two sentences: first states purpose and return fields, second provides usage guidance. No filler, all sentences earn their place.

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

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

Given no required parameters and schema covers the optional parameter, the description lists return fields adequately. For a simple list tool with annotations, it is sufficiently complete, though pagination or ordering could be mentioned but are not critical.

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?

There is only one parameter (include_inactive). Schema coverage is 100% with a description. The description's mention of 'active' implicitly refers to the parameter default, but adds no new meaning beyond the schema.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the return fields (id, type, etc.). It distinguishes from siblings like subscribe and unsubscribe via usage context.

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 guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It provides context for when to use the tool but does not explicitly exclude other scenarios or compare with 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?

The description adds rich behavioral context beyond the annotations, including rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow, the fact that it is free and does not count against quota, and that the team reads digests daily. Annotations only say readOnlyHint=false, so this is substantial added value.

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?

Though the paragraph is dense, every sentence earns its place: purpose, use cases, boundary conditions, workflow, expectations, and rate limits. It is front-loaded with the purpose and structured logically.

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

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

The description is complete for a feedback tool with four parameters, nested context objects, and no output schema. It explains the claim_token return value and how to read it later, covers edge cases like missing accounts, and sets rate-limit expectations.

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

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

The schema already provides 100% coverage of all four parameters, including detailed descriptions for type, context, message, and claim_token. The description adds no parameter-specific semantics beyond what the schema already covers, though it reinforces the claim_token workflow.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this feedback tool from sibling tools like ask_pipeworx or research tools by framing it as reporting issues to the Pipeworx team.

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

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

It explicitly lists when to use the tool: for bugs, feature/data gaps, and praise. It also gives an explicit exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is exceptional 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?

Beyond annotations (read-only, idempotent), it adds cache behavior, data source (CF analytics-engine), no PII, and data shape. Fully transparent.

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

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

Three concise sentences covering purpose, use cases, and data details. No wasted words, well 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 optional param, no output schema, and rich annotations, the description fully explains return shape, caching, and source. 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% for the single param. Description adds semantic value by explaining the trade-off between short and long windows, which is not in 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 trending Pipeworx call data (top tools, packs, volume) over specified windows. It distinguishes from siblings like 'discover_tools' by emphasizing it's about current agent usage.

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

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

Three explicit use cases are provided, plus guidance on window selection. However, it lacks explicit when-not-to-use or alternative tool mentions, which would push to a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds substantial context: scanning top 200 markets, partition_check with threshold >3pp, semantic anchor (Jaccard ≥0.30), partition filter (placeholder >20% returns null), fill check against live CLOB depth. 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 dense but all sentences add value. It is front-loaded with purpose, then modes, then filtering details. No redundant information; every sentence earns its place.

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

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

Despite no output schema, the description explicitly lists response fields (opportunities[], gap_pp, suggested_trade, reasoning, partition_check details). It also covers edge cases (skipped_low_similarity, fill check). The tool is complex and the description fully compensates for the lack of 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?

Schema coverage is 100% with descriptions for both parameters. The description adds richer semantics: explains what 'event slug' means (e.g., 'fed-decision-may-2026'), that full URLs are accepted, and that topic is a seed question. It also details how each parameter affects behavior.

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

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

The description states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It clearly distinguishes between three modes: no args (trending scan), event, and topic. The verb 'find arbitrage opportunities' is specific and the resource is well-defined.

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 instructions: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also explains when event vs topic should be used and mentions alternatives like polymarket_fill_risk for custom sizing.

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 provides extensive behavioral details beyond annotations: caching (1h KV), skip logic for placeholder-heavy partitions, Fed bet handling, and diagnostic output. All traits are consistent with readOnlyHint=true and destructiveHint=false. This fully informs the agent of what to expect.

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

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

The description is lengthy but well-structured with clear sections (model families, knobs, response format). Front-loaded with purpose. While verbose, every sentence adds value for understanding the complex tool. Could be slightly trimmed, but overall efficient for the complexity.

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

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

Given the tool's complexity (9 parameters, 4 model families, segmentation) and lack of output schema, the description is remarkably complete. It covers all segments, knob effects, response structure, diagnostics, and caching. The agent has sufficient information to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant semantic value by explaining how parameters interact (e.g., min_kelly skips small opportunities, max_spread_pp sets tight book filters) and provides usage guidance (e.g., slippage_pp recommendation). This goes beyond mere parameter names.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, specifically for daily bet discovery. The verb 'scan and return' and resource 'Polymarket markets' are precise, and the purpose is well-defined. Although sibling tools exist, the unique focus on Pipeworx-based edges implicitly distinguishes it.

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?

Usage context is thoroughly explained: it's for 'what should I bet on today', with explicit knob tuning advice (min_liquidity, max_spread_pp) and explanation of when segments are empty. However, there is no explicit guidance on when to use this tool versus siblings like polymarket_arbitrage or polymarket_edge_tracker, which would improve score.

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

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

Annotations already declare readOnlyHint and idempotentHint, confirming safe read-only behavior. The description adds valuable behavioral details: snapshot TTL (60 days), decay computed from daily closes (not intraday), gaps indicating no scan, and response structure. No contradictions.

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

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

The description is front-loaded with the core question, then logically proceeds to arguments, response fields, and limitations. While slightly verbose, it is well-organized and every sentence adds value. Could be slightly tighter without losing meaning.

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, so the description must explain return values. It thoroughly details tracked[], expired[], and snapshot_dates[] with field semantics. Limitations are also covered. This is adequately complete for a tool of this complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context about 'days' default/max and 'window' as snapshot family, but the schema already provides defaults and enum examples. The description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and contrasts with other tools by emphasizing temporal analysis vs. static edge data.

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

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

The description implies usage context through the contrast between fresh and old edges, but does not explicitly state when not to use or name alternatives. However, the clarity of the output (tracked vs expired) guides 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?

The description adds significant behavioral context beyond annotations: it explains the ladder-walking process, return values (top_of_book, vwap_fill_price, slippage_pp, verdict), and the concept of forced directional risk for baskets. No contradiction with annotations (readOnlyHint=true is consistent with a check operation).

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and front-loaded purpose. Every sentence is informative, with no wasted words. Despite length, it earns its place for a complex 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?

Given the complexity (two modes, many return fields, no output schema), the description is remarkably complete. It explains both modes, output fields, usage context, and risks. It fully equips an agent to decide when and how to use the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the interaction between market/event parameters and modes, the default behavior for side in basket mode (auto from partition sum), and the interpretation of size_usd for baskets (settlement notional). This enriches param understanding.

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

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

The description clearly states the tool's purpose as a realizable-vs-theoretical edge check against live CLOB order-book depth, with two distinct modes (single-market and basket) and detailed output fields. It distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by specifying when to use it.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risks of thin books and partial fills, providing clear when-to-use and when-not-to-use 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?

Despite annotations already indicating read-only, open-world, idempotent, and non-destructive behavior, the description adds rich behavioral detail: explains the two cases for compatibility_warning, temporal alignment checks, skipped cross-type/subtype counters, and the caveat that pre-mapped topics are not automatically tradeable.

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 somewhat verbose, repeating the 'pre-mapped ≠ tradeable' sentiment. However, it is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS), making it easy to scan despite length.

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

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

Given the tool's complexity (cross-venue, multiple safety flags, two modes, no output schema), the description is highly complete. It documents return values (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and explains their interpretation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by explaining the two modes (topic vs explicit tickers), listing the 10 pre-mapped shortcuts, and clarifying parameter interaction (overrides). This goes beyond mere schema documentation.

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 computing cross-venue spread between Kalshi and Polymarket, distinguishes it from siblings (e.g., polymarket_arbitrage) by focusing on the same resolving question, and specifies two modes (topic shortcuts and explicit tickers).

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 (finding cross-venue spreads) and when not (most pre-mapped topics return compatibility_warning, real spreads are rare). Provides clear context for interpreting safety fields and the meaning of matched_pairs, compatibility_warning, and temporal_alignment.

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

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

Annotations declare readOnlyHint=true and idempotentHint=true, which the description's 'retrieve' and 'list' align with. The description adds context about scoping to user identifier, which goes beyond annotations. No contradictions.

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

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

Three sentences, no fluff. First sentence defines core action, second adds use cases, third adds scoping and pairing. Purpose and usage are conveyed efficiently.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, and side effects. It does not detail return format, but given simplicity, it is largely complete.

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

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

Schema describes the 'key' parameter. The description adds dual behavior (retrieve vs list) and provides concrete examples of keys (ticker, address, research notes), 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?

The description clearly states the tool's function: retrieve a saved value or list all keys. It distinguishes from sibling tools remember and forget by specifying this is for retrieval, and gives concrete examples of stored context like ticker, address, research notes.

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

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

The description explains when to use the tool: to look up previously stored context without re-deriving. It mentions scoping and pairing with remember/forget, but does not explicitly state when not to use it or compare with all 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 indicate read-only, idempotent, non-destructive. The description adds valuable behavioral details: what fields are returned, how mark_read affects future calls, and that polling is safe. 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?

Four sentences, each serving a distinct purpose: main action, return data, filters and mark_read, polling and alternative access. No unnecessary words; front-loaded with the primary function.

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

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

Given the simple read-only nature and no output schema, the description covers all essential aspects: purpose, return fields, filtering, mark_read behavior, polling suitability, and alternative access method. Missing only minor details like ordering, but these are inferable.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds further context: an example filter type (sec_8k) and explains that mark_read ensures 'the next call only shows newer ones,' which goes beyond the schema's 'Flag the returned events read.'

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It lists return fields (source, citation_uri, payload) and implicitly distinguishes from sibling tools like list_subscriptions by focusing on event data rather than subscription metadata.

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

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

The description provides clear context for use, including polling suitability and mark_read behavior. It does not explicitly contrast with sibling tools, but it does mention an alternative REST endpoint for scripts/dashboards, giving a when-not scenario.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds details about parallel fan-out to multiple sources, fallback logic, soft-fail for USPTO, and the structured return type, providing rich behavioral context beyond annotations.

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

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

The description is a single paragraph but efficiently packs example queries, source details, fallback behavior, and usage alternatives. It is front-loaded with user query examples, though slightly lengthy, it remains clear and purposeful.

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 sources, date formats, fallback, soft-fail), the description covers all necessary aspects. Despite no output schema, it mentions the return structure (changes[] grouped by source, total_changes, citation URIs), making it complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'since' accepts both ISO dates and relative shorthand (e.g., '7d'), and recommends '30d' for typical monitoring. It also clarifies 'value' accepts ticker or CIK and 'type' is restricted to 'company'.

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

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

The description clearly states the tool provides a change feed for a company, listing specific sources (SEC, GDELT/GNews, USPTO) and distinguishes from sibling 'entity_profile' by explaining when to use that instead for static profiles.

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

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

It provides explicit example queries ('What's new with X'), specifies the fallback behavior from GDELT to GNews, and explicitly recommends using 'entity_profile' when a static profile is needed, giving clear 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?

Beyond annotations (idempotent, non-destructive), the description adds key behavioral traits: scope by identifier, persistence differences for authenticated vs. anonymous users (24h TTL), and pairing with other tools. This significantly enhances agent understanding.

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 at about 4 sentences, front-loading the purpose and usage. It avoids fluff and efficiently conveys scope, persistence, and pairing. Slight room for tightening, but overall well-structured.

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

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

Given the tool's simplicity (key-value store with no output schema), the description covers purpose, usage, parameters, and behavior (scoping, TTL). It does not mention error cases, but that is acceptable for this type of tool. The information is sufficient for correct use.

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

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

Schema coverage is 100%, with good parameter descriptions. The description reinforces the schema with examples (e.g., key naming conventions) but does not add substantial new meaning beyond that. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'Save' and resource 'data' with a specific purpose: reuse across conversations or sessions. It distinguishes itself from sibling tools like recall and forget by explaining the pairing, and provides concrete examples of data to store.

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

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

The description explicitly says 'Use when you discover something worth carrying forward' and lists examples (resolved ticker, target address, etc.). It also advises pairing with recall and forget, providing clear context. No explicit when-not-to-use, but the positive guidance is strong.

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

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

Annotations already convey read-only, idempotent, and non-destructive hints, so the bar is lower, but the description adds substantial behavioral context beyond that: it cascades through multiple lookup endpoints, degrades gracefully if GLEIF/OpenFIGI is unavailable, and explicitly returns unresolved identifiers under an `unresolved` field. This gives agents an accurate model of expected behavior and edge cases.

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

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

The description is long but information-dense, front-loading concrete examples and purpose before diving into supported types. Some redundancy exists (e.g., repeating accepted input formats), but each clause contributes operational detail. It is structured enough to be parseable despite its length, though it could be slightly tightened.

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 sources, conditional enrichment, fallback behavior), the description is thorough: it specifies exact identifiers returned per type, explains unresolved handling, and describes degradation. This fully compensates for the absence of an output schema and gives the agent a reliable mental model of the tool's behavior.

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

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

Schema coverage is 100% with detailed parameter descriptions and examples, so the baseline is 3. The description adds meaning by explaining what each type produces (e.g., cross-source identity spine for company, RxCUI/ingredient/brand for drug) and clarifying the limited scope of each entity type, going beyond the raw schema definitions.

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

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

The description states a clear purpose: resolve user-spoken names to canonical/official identifiers that other tools need as input. It uses a specific verb ('resolve') and resource, and differentiates itself as a first-step lookup by citing example queries and noting that it replaces 2-3 manual lookups. This clearly distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

The description explicitly instructs to 'Use FIRST whenever you have a name but need an ID,' giving a strong when-to-use signal. It also maps each supported entity type to its accepted input formats, providing clear context for selecting company vs drug. However, it does not explicitly state when NOT to use the tool or name alternative sibling tools for non-ID lookup needs, which would make it a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds behavioral context: probes each entity via ai_visibility_check, ranks by score, returns 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?

Two sentences, front-loaded with purpose. Every phrase adds value (process, output format, example use case). 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?

Covers purpose, process, output format (ranked list with score/confidence/signal density). No output schema but description suffices. Could mention the 2-8 entity limit from schema but it's in the input schema 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%. Description adds key semantic: first entity is treated as 'subject' for narrative (not in schema). Also clarifies optional models and context usage 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?

Description clearly states the tool compares AI visibility across multiple entities, uses ai_visibility_check internally, and returns ranked results. Distinguishes from sibling ai_visibility_check (single entity) and compare_entities (generic) by specifying the process and output.

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

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

Provides a concrete use case ('competitive AI-marketing audits') and implies when to use this tool (multiple entities) vs ai_visibility_check (single entity). Could explicitly state alternatives, but the 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 read-only, idempotent, and non-destructive behavior. The description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list timeout sources while returning remaining data. This goes beyond annotations and helps the agent handle latency and partial results.

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 front-loaded with the composite concept. Every sentence adds value, though it is somewhat lengthy. Minor improvements could be made for brevity, but overall well-structured.

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

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

Despite no output schema, the description thoroughly covers return values: summary block, per-advisory detail, links, and alternative versions. It also explains error/partial failure behavior, making the tool's behavior fully predictable even without an 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?

Schema coverage is 100% with descriptions for both parameters. The description adds value by noting that scoped packages (e.g., @types/node) are accepted and that version defaults to latest when omitted, providing practical usage details beyond the schema.

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

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

The description clearly states the tool's composite nature: combining deps.dev (license, advisories, version history) and bundlephobia (bundle size, dependencies, ESM/tree-shaking) into a single call for npm packages. It distinguishes from siblings by specifying 'NPM ecosystem only' and directing other ecosystems to deps.dev:version directly.

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"'. It also clarifies when not to use by noting that other ecosystems (PyPI, Maven, etc.) should use deps.dev:version directly, providing clear alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds technical details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, character limit of 200K with truncation and flagging, and every passage carries an offset for verification. This goes well 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 a single paragraph that is well-structured and front-loaded with the main point. Every sentence adds value, though some technical details could be slightly condensed. Overall, it is appropriately sized.

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

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

Given the tool has 3 parameters and no output schema, the description fully covers what the tool does, its inputs, outputs (passages with offsets and scores), technical details, and a pairing suggestion. Complete enough for an AI agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds extra context: explains truncation cap for 'text', provides example queries for 'query', and specifies default value and range for 'limit'. This adds 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 the tool performs semantic search inside a fetched record. It specifies inputs (text and query) and outputs (top-N passages with offsets and scores). Also distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' Also mentions an alternative workflow: 'Pairs with ask_pipeworx_grounded.' Provides clear context for usage.

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

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

The description adds significant behavioral context beyond annotations: it explains the requirement of an OAuth account, delivery channel details (feed always on, email, sms with caps, webhook with HMAC signing and auto-disable), and that it returns the subscription id. The annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true) are not contradicted, though idempotency is not explicitly addressed.

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

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

The description is well-structured, starting with the core purpose, then elaborating on types and delivery channels. It is relatively concise given the complexity of the tool, though it could be slightly shorter. Every sentence adds value, and key 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?

For a creation tool with 3 parameters (2 required) and no output schema, the description adequately covers inputs, constraints (account, delivery limitations), and return value. It could benefit from explicitly stating whether the subscription ID is returned in a specific format, but overall it is complete for an agent to use correctly.

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

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

With 100% schema coverage, the description adds rich meaning beyond the schema by providing concrete examples for each subscription type (e.g., items codes for sec_8k) and detailed explanations for delivery channels (e.g., webhook signing secret and retry policy). This helps the agent understand how to correctly populate parameters.

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

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

The description clearly states that the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by explaining the create action. Specific types (sec_8k, polymarket_edge, fred_series) with examples further clarify purpose.

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 when to use the tool (to create subscriptions), prerequisites (Pipeworx OAuth account), and supported types with parameters. It does not explicitly tell when not to use it or suggest alternatives, but given the set of sibling tools (e.g., list_subscriptions, unsubscribe, recent_alerts) the usage context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns 'category-bucketed example questions' and is a safe, non-destructive onboarding tool. 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 front-loads common user phrases and is moderately long but every sentence adds value. It could be slightly more concise, but it effectively conveys all necessary information without unnecessary 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?

Despite lacking an output schema, the description thoroughly explains the return format (category-bucketed examples with tool+argument shape). It also covers both argument scenarios and the tool's role in onboarding.

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

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

Schema coverage is 100% with a description of the topic parameter. The description adds value by listing example values for topic and explaining how omission yields a cross-category spread, going beyond the schema's basic 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 identifies the tool as an onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings like ask_pipeworx and discover_tools by being the first tool to use when learning about Pipeworx's capabilities.

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' and explains how to use arguments (omit for full spread, pass topic to focus). While it doesn't explicitly list when not to use, the guidance is clear and practical.

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?

Adds value beyond annotations by explaining the row is deactivated not deleted and historical events remain via recent_alerts. Consistent with idempotentHint and destructiveHint.

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

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

Two efficient sentences with no redundancy. First sentence states action, second provides critical behavioral detail (ownership and deactivation).

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-parameter mutation tool with annotations, the description is complete: explains purpose, ownership, and non-destructive nature. Links to recent_alerts for continuity.

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% with description for the only parameter (id). Description adds no further insight beyond the schema, so baseline 3 is appropriate.

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

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

The description uses the specific verb 'Cancel' with resource 'subscription by id'. It clearly distinguishes from sibling tools like subscribe (create) and list_subscriptions (list).

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use. Does not mention alternatives explicitly but context is clear.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds high-value behavioral context: the meaning of each verdict, especially that 'could_not_verify' means the check did not happen and must not be treated as evidence for/against the claim, and that 'unsupported' means no source exists. It also details the routing logic and that claims are answered with verbatim evidence before being judged. 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 substantial but every sentence serves a purpose: trigger patterns, core function, path distinction, return values, caller-critical caveats, and efficiency rationale. It is front-loaded with user-intent phrases and immediately states the core purpose. Despite length, there is no filler or redundancy.

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

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

The tool has no output schema, so the description compensates by enumerating verdict values, the citation-bearing value, and reasoning. It covers the two distinct operational modes, error semantics (could_not_verify with verification_error{stage,detail}), and the meaning of unsupported. This is complete for an agent to select and correctly interpret the tool's results.

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

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

The input schema already provides descriptions for both parameters (claim with examples, tolerance_pct with range and default behavior). The description itself does not add further parameter-level detail; it only reinforces the claim examples implicitly. With 100% schema coverage, a baseline of 3 is appropriate, as the description adds no significant semantic value beyond what the schema already states.

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

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

The description opens with concrete trigger phrases ('Is it true that...', 'fact check', 'verify the claim that...') and explicitly states the tool performs 'natural-language claim verification against authoritative sources.' It distinguishes two distinct paths (SEC EDGAR/XBRL for company financials vs grounded pipeline for everything else), and notes it replaces 4–6 sequential calls, making its scope and role clear relative to 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 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies when the structured fast path applies (company-financial claims) and when it falls back to the grounded pipeline, plus the explicit efficiency note that it replaces multiple sequential calls. This gives clear when-to-use guidance and implicitly distinguishes it from chaining other tools.

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