Epa Emissions

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

Annotations declare readOnly, openWorld, idempotent hints. The description goes beyond by explaining the default model, the requirement to bring your own Anthropic key (including cost implications), and the return structure (per-model fields + combined view). 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-loading the core action. The second sentence is somewhat long but packs necessary details without redundancy. Could be slightly more concise, but still efficient.

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

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

With no output schema, the description adequately indicates the return structure (per-model objects + combined view). All 4 parameters are documented in the schema, and the description adds usage context. The description covers the tool's complexity well.

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 the relationship between 'models' and '_apiKey' parameters (e.g., BYO key for Anthropic) and the purpose of the 'context' parameter for disambiguation, which is not obvious from the schema alone.

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

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

The description uses specific verbs ('probe', 'score') and clearly states the resource (LLMs) and output (visibility score 0-100). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on general brand/product visibility rather than specific competitor scanning.

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 lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') which imply appropriate contexts. However, it does not explicitly state when not to use or mention alternative tools for comparison, leaving some ambiguity.

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 read-only/idempotent annotations, the description adds that it routes across 5,521 tools, fills arguments, and returns pipeworx:// citation URIs. It also notes it's one fast call and works on every tier, adding useful operational context beyond what annotations declare.

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

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

The description is longer than average but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and structured with a start-here/step-up framing. Every section provides actionable guidance, examples, or alternative routing, though it could be slightly trimmed without losing 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 there's no output schema, the description compensates by explaining the return type (structured answer with citations), naming covered domains, and providing use-case examples. It also explains how to escalate to other tools, making it contextually complete for decision-making.

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

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

The schema already documents all six parameters with clear alias descriptions (100% coverage). The description doesn't add parameter-specific detail beyond examples, but the schema sufficiently explains the question field and its aliases. Baseline 3 is appropriate when schema is complete.

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 answers factual questions by routing to verified sources and returning structured answers with citations. It distinguishes itself from siblings by explicitly positioning itself as the default entry point and contrasting with ask_pipeworx_grounded and deep_research.

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

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

Explicitly advises preferring this over web search for specific domains, provides trigger phrases ('what is', 'look up', 'find', etc.), and gives concrete examples. It even says 'Step up only when needed' and names alternatives (ask_pipeworx_grounded, deep_research), giving clear when-to-use and when-not-to-use guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable context: it is a full working router, not a stub, and its experimental status means routing improvements are enabled live. It also confirms it currently matches ask_pipeworx exactly, which sets expectations for 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 three sentences, front-loaded with the tool's identity as a beta router, followed by its current status, usage instruction, and a final reassurance. Every sentence earns its place without 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 schema fully documents parameters and annotations cover safety, the description supplies the essential missing context: it is an experimental variant, currently identical to ask_pipeworx, and its response shape matches the stable version. It could go further by describing what 'routing' means in practice, but the key facts are present.

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

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

The input schema provides 100% coverage with descriptions for 'question' and all its aliases, so the schema carries full parameter documentation. The description adds no new parameter details, only reiterating that arguments match ask_pipeworx, which supports the baseline of 3.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, a universal router, and states it provides the same 5,521 tools, arguments, and response shape. It distinguishes from sibling ask_pipeworx by being the experimental edge with candidate routing improvements, making its purpose 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?

It explicitly instructs to use it 'exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This provides clear when-to-use context and names the sibling alternative. It does not spell out when not to use it, but the implication 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?

Beyond the read-only and idempotent annotations, the description discloses the refusal reasons (`not_in_source`, `no_tool_match`, etc.), the exact output shape, and the additional LLM call cost. This gives the agent a complete picture of failure modes and side effects.

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

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

The description is information-dense yet structured, with the core purpose front-loaded and each sentence adding value: process, output, use cases, tradeoff. It avoids fluff and is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (routing across thousands of sources) and the absence of an output schema, the description compensates by fully specifying the success/refusal return structures and listing concrete refusal reasons. It also addresses cost implications, making it complete for an agent to invoke correctly.

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

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

The input schema already fully documents the single `question` parameter and its aliases with 100% coverage, so the description doesn't need to add parameter-level detail. It mentions 'fills arguments' in the routing process, but that's not specific to parameters. 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 this is a hallucination-resistant answer mode for high-stakes reads, explicitly contrasting with ask_pipeworx and describing the extraction process. It specifies the exact behavior of using only tool result content to generate answers, making the purpose unmistakable.

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

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

The description explicitly says 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups,' providing clear when-to-use and when-not-to-use guidance. It also identifies the tradeoff of an extra LLM call, enabling informed tool selection.

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

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

The description goes far beyond the annotations (readOnlyHint, etc.), detailing resolution logic, fan-out, response shapes, safety mechanisms, cancellation rules, and low-confidence handling. No contradictions with annotations.

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

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

The description is quite long but well-organized into clear sections (e.g., RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS). Every part adds value, though some agents might benefit from a slightly more condensed version.

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 (multi-step pipeline, classification, evidence sources, edge cases like closed markets, low confidence, illiquid spreads), the description covers all necessary aspects comprehensively, 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%, yet the description adds meaningful context: market can be slug/URL/question; depth defaults to thorough; include_raw explains when to use. This helps agents choose correct 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 precisely states it researches Polymarket bets by pulling Pipeworx data, and details input types (slug, URL, question). It also hints at its unique role vs siblings by focusing on combined data retrieval, though not explicitly comparing.

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

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

Explicitly says 'Use for should I bet on X, what does the data say about Y, or is there edge in Z', giving clear context. However, it does not specify when not to use or compare with sibling tools like polymarket_edges.

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 valuable context: data sources (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs), correct handling of fiscal year ends, sorting by primary metric, and output with citation URIs. This goes beyond what annotations provide.

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

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

The description is a single dense paragraph that front-loads trigger phrases and purpose. It efficiently conveys all key points without redundancy. Minor improvement could be breaking into bullet-points for readability, but overall concise.

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

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

Given the tool's complexity (two entity types, no output schema), the description covers key aspects: input constraints, data sources, sorting, and output format (paired data + citations). Error handling or edge cases are not mentioned, but the provided information is sufficient for correct usage.

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

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

Schema coverage is 100% with parameter descriptions. The tool description further clarifies parameter usage with concrete examples (tickers/CIKs for company, drug names for drug) and the allowed range (2-5). This adds significant practical guidance beyond the schema.

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

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

The description starts with clear trigger phrases ('Compare X and Y', 'X vs Y') and explicitly states it performs side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from sibling tools by urging preference over sequential single-pack lookups, making the purpose and scope very clear.

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 examples of when to use ('which is bigger', 'rank these companies') and explicitly states to prefer this tool over sequential single-entity lookups. However, it does not explicitly name alternative tools like 'entity_profile' for single lookups, leaving some ambiguity.

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 (readOnly, openWorld, idempotent), the description discloses account/payment requirements, latency (15-60s, ~90s for thorough), output packet structure (evidence, confidence, source, fetched_at, gaps[], contradictions[]), citation fetchability rules, and excerpting behavior. No contradictions with annotations.

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

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

Long but dense — every sentence adds operational value (payment, alternatives, latency, return fields, edge cases). Front-loaded with account requirement then core functionality. Could be tightened but each claim is consequential.

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 carries full burden for explaining return values; it covers findings packet, gaps[], contradictions[], hop field, citation_uri, and semantic excerpting. Also covers latency, depth semantics, and alternative tool routing, making the tool fully understandable without extra lookups.

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

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

Schema covers both parameters with full descriptions. Description adds the critical paid-plan gate for depth:'thorough' and clarifies sequence of hops for standard/thorough, which is slightly beyond the schema but mostly reinforces 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?

Specific verb 'researches' with a clear resource (1452 STRUCTURED data sources) and a precise behavior (decomposition, parallel routing, findings packet). It explicitly distinguishes from open-web search and sibling ask_pipeworx for single lookups.

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

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

Explicitly states when to use: broad/multi-part structured-data questions. Gives alternatives: ask_pipeworx for single lookups or breaking news, and notes the account requirement with fallback if not signed in.

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, so safety is clear. The description adds that results are ready to call directly, but does not disclose further behavioral traits beyond what annotations provide.

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

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

The description is well-structured, front-loaded with purpose, and includes examples. The list of domains is slightly long but still valuable. Every sentence adds information, though it could be slightly more concise.

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

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

Given no output schema, the description clearly explains what is returned (tool names, descriptions, schemas with examples) and that results are callable. It covers parameter limit defaults and max. Complete for a discovery tool with good annotations.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description adds aliases for query (task, q, description, search) and example queries, but does not add significant 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 that the tool finds tools by describing the data or task, distinguishing it from sibling tools which are specific tools for specific domains. It explicitly lists domains and states that it returns top-N relevant tools with schemas.

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

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

The description explicitly says to call this tool FIRST when you have many tools and want to see the option set, implying when not to use (if you already know the tool). It provides examples of queries and the context of browsing versus direct tool 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 indicate readOnly, openWorld, idempotent, non-destructive. The description adds significant context: fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), details return fields (cik, filings, fundamentals with sort order), and notes USPTO API sunset and soft-failure behavior. No contradictions.

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

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

The description is dense but well-structured: starts with example triggers, then explains behavior and return data. Every sentence adds value, though it could be slightly more concise. The front-loading of examples is effective.

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

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

Given the tool's complexity (multi-source, multiple return fields, soft-fail for patents, fallback mechanism) and lack of output schema, the description is remarkably complete. It details what is returned for each source, ordering, and potential failure modes, leaving little ambiguity for the agent.

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

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

Input schema already covers all 2 parameters with descriptions. The description reinforces the meaning of 'value' (ticker vs CIK) and clarifies that 'type' only accepts 'company'. Adds value beyond schema by explaining name unsupported and recommending 'resolve_entity'.

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 'full cross-source profile of a US public company' and provides example queries like 'Tell me about X' and 'company profile for Microsoft'. It distinguishes itself from siblings like 'resolve_entity' by explicitly noting that names are not supported and that tool should be used first.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also instructs to pass ticker or CIK and points to 'resolve_entity' for names. Provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about what gets destroyed (stored memories) and mentions sensitive data clearing, but doesn't elaborate on idempotency or reversibility.

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 with no wasted words. Information is front-loaded and scannable.

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

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

Given the simple tool (1 param, no output schema) and thorough annotations, the description provides complete context: purpose, usage guidance, and sibling pairing.

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

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

Schema coverage is 100% with a clear parameter description. Description adds no extra meaning beyond what the schema provides; 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?

Description clearly states the verb 'delete', resource 'memory', and method 'by key'. It distinguishes from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task done, or clear sensitive data. Also recommends pairing with remember and recall, guiding alternative tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as safe. The description adds behavioral details (fetches the page, extracts content, emits markdown, returns a text blob) without contradicting the annotations.

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

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

The description is 100 words, front-loaded with the main action, followed by methodology and use cases. Every sentence provides value 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?

For a simple read-only tool with no output schema, the description explains what it does, how it works, and what it outputs. It covers the essential aspects without leaving critical gaps.

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

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

Schema coverage is 100% with both parameters described. The description only reinforces what the schema already states (url and max_links), adding minimal extra 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 specifies the verb 'generate', the resource 'llms.txt file for any URL', and lists concrete steps (fetch, extract, emit). It clearly distinguishes itself from sibling tools, none of which produce llms.txt files.

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 (indexing a client's site, drafting for own project, auditing competitor). It does not mention when to avoid using the tool or suggest alternatives, but the context is clear.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds context: data source (EPA GHGRP), data lag (~1.5y), auto-selection of latest year, return fields (metric tons CO2e, facility count). 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 three sentences, front-loaded with purpose, then details. Every sentence adds value. Could be slightly tighter, but very effective.

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

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

Given the tool's simplicity (3 params, 1 required, no enums, output schema exists), the description fully covers purpose, inputs, data source, lag, return format, and ranking. 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 covers all 3 parameters with descriptions. The description adds value by explaining state accepts 2-letter code or full name, year defaults to latest, and sector is an optional filter. Examples reinforce usage.

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

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

The description clearly states the tool provides total greenhouse-gas emissions by industry sector within a US state, answering a specific question ('which sectors emit the most in <state>'). It names sectors and distinguishes from facility-level tools (sibling exists).

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 on when to use (state-scoped, sector-level emissions) and includes examples. It does not explicitly state when not to use or list alternatives, but the sibling list includes facility-level tools, implying boundary.

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, openWorldHint, and destructiveHint. The description adds valuable context: data lags ~1.5 years, returns facility details, and is state-scoped. 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?

Two sentences, well-structured, front-loaded with purpose. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema and annotations, the description is complete: explains data source (EPA GHGRP), ranking, return fields, state scope, data lag, and optional parameters. No gaps.

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

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

Schema coverage is 100% with each parameter described. The description reinforces meaning by stating 'biggest', 'ranked by total CO2-equivalent emissions', and provides example values. It adds context beyond the schema.

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

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

The description clearly states it returns the biggest GHG-emitting facilities in a US state, ranked by emissions, including facility details. This distinguishes it from siblings like ghg_emissions_by_sector, which likely aggregates by sector.

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 that it is state-scoped and requires a state parameter, and mentions data lag and auto-selected year. It implicitly guides when to use this tool (facility-level data) but does not explicitly contrast with siblings like ghg_emissions_by_sector.

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

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

Annotations already indicate safe read operations. Description adds what fields are returned (id, type, etc.) and that include_inactive controls cancelled subscriptions. 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 concise sentences. First covers purpose and return fields, second gives usage guidance. No unnecessary words.

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

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

For a simple read-only list with one optional param, the description combined with annotations and schema provides full context. Return fields are listed explicitly.

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

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

Schema coverage is 100% with description for the only parameter. The tool description does not add new meaning beyond the schema for that parameter, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions.' It uses a specific verb and resource, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Provides context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This guides when to use, though explicit alternatives or when-not-to-use are not stated.

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 being all false (write, non-idempotent, etc.), the description adds rich behavioral context: rate-limited to 5 per identifier per day, free and doesn't count against quota, returns a claim_token for anonymous filing, and the team reads digests daily. This significantly exceeds the annotation signal and contains no contradictions.

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

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

The description is long (~150 words) but every sentence earns its place, covering purpose, exclusions, usage flow, and limitations. It is front-loaded with the core purpose and uses clear, direct language. Minor deduction only because it could be tightened without losing critical guidance, but the density of useful information justifies the 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?

For a tool with no output schema and 4 parameters, the description fully covers behavior, return value (claim_token), rate limits, scope, and the reading-reply flow. It also addresses ambiguity around 'other' types implicitly. This is a self-contained explanation that leaves almost no user questions unanswered.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful value by demonstrating the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})') and explaining the anonymous flow. It also reinforces the type enum meanings indirectly, though the schema already documents those well.

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 clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this tool from all siblings by enumerating the exact feedback categories (bug, feature, data_gap, praise) and explicitly scoping it to Pipeworx tools. This is unambiguous and well-differentiated.

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 when-to-use guidance with concrete triggers ('returns wrong/stale data', 'wish existed', 'worked surprisingly well') and a strong exclusion: tools from other MCP servers should not be reported here, naming the correct alternative (file with that server). It also explains the claim_token flow for follow-up, covering both initial filing and later retrieval.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds that data is self-aggregating from CF analytics-engine with no PII, and cached 5min-1h. No contradiction, adds valuable 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?

Description is front-loaded with core result, each sentence adds value. No wasted words. Use cases are bulleted for 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 no output schema, description explains return format (top tools, packs, volume). Explains window parameter and caching. Completely sufficient for understanding and using 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% with enum and description. Description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond schema, earning a 4.

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

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

Description clearly states it returns top tools, top packs, and total call volume over a window. Verb 'returns' with specific resources, and distinguishes from siblings like discover_tools or ask_pipeworx that serve different purposes.

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

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

Description lists three explicit use cases (hot data sources, confirming canonical tool, aligning use case) and advises on window choice. Provides clear context for when to use this tool vs alternatives.

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

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

The description goes far beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by explaining the internal algorithms: monotonicity checks, partition-sum logic, semantic anchor (Jaccard similarity >= 0.30), partition filter (placeholder fraction >20%), and fill check against live order book depth. No contradictions.

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

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

Well-structured with section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK), but quite verbose. Could be tightened without losing clarity. Still earns its length by providing critical operational details.

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

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

No output schema exists, but the description comprehensively explains the response structure: opportunities[] with fields like gap_pp, suggested_trade, reasoning, monotonicity violation context; partition_check with sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade; fill_check with theoretical_edge_pp_at_book, realizable_edge_pp, thin_legs[]. Completely covers what the agent needs to understand 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?

Despite 100% schema coverage, the description adds significant meaning: explains event slug format, topic as seed question, and how each parameter triggers different scanning modes. Provides concrete examples like 'fed-decision-may-2026' and 'Strait of Hormuz traffic returns to normal'.

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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between event mode (single-event) and topic mode (cross-event), with specific examples, making the purpose unmistakable.

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

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

Explicitly tells when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also warns about fill check and when not to trade ('do not trade it'). Includes alternative tool 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 the annotations, including the three model families, caching behavior (1h KV-level), response structure, and edge calculation details. It also explains caveats such as Fed bets being excluded. This fully discloses the tool's behavior.

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

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

The description is quite lengthy (around 300 words) and contains very detailed model explanations (e.g., 'lognormal barrier from 90d FRED log-returns') that may be excessive for an agent. However, it is structured clearly with segments and bullet points.

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

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

Given the complexity (9 parameters, no output schema), the description is highly complete. It explains the response structure (top-level fields like by_segment, diagnostics) and how to interpret results, covering all necessary context for an agent to invoke the tool correctly.

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

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

All 9 parameters are described in the input schema with 100% coverage. The description adds significant semantic value, such as explaining why min_kelly does not apply to partition opportunities and how min_partition_leg_kelly works instead. This goes beyond what the schema alone 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 clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The verb 'scan' and resource 'Polymarket markets' are specific, and the description effectively distinguishes this tool from siblings like polymarket_arbitrage by detailing unique model families and response segments.

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 positions the tool for 'what should I bet on today' and mentions that it 'discovers opportunities without paging hundreds of markets.' It provides guidance on when to use it, but does not explicitly state when not to use it or suggest alternative sibling tools for different use cases.

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

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

Beyond annotations (read only, idempotent), the description details response structure (tracked, expired, snapshot_dates), trend types, decay calculation, and data gaps. It explains negative edge_pp_net meaning and snapshot writing triggers. No contradictions with annotations.

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

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

The description is dense but well-structured: core question first, then args, then response format, then limitations. Every sentence adds value, though it could be slightly more organized with bullet points.

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

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

Despite no output schema, the description fully explains the response content, including edge time-series, trend and decay metrics, expired opportunities with lifespan, and snapshot dates. It covers limitations and data availability, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds defaults (days=14, window='1wk'), clamps (days max 30), and explains window values (24hr, 1wk, 1mo). This adds meaning beyond the schema's brief descriptions.

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

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

The description clearly states it provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from siblings like polymarket_edges by focusing on historical time series and decay analysis.

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

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

The description explains when to use (to assess edge persistence and decay) and provides limits (60-day TTL, not intraday). It does not explicitly state when not to use, but the context implies current edges are better served by the sibling polymarket_edges tool.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, establishing a safe read check. The description adds value by detailing behavioral traits: walks the order-book ladder, returns specific fields, and warns of unhedged directional risk. 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 lengthy but efficient, with every sentence contributing information. It is front-loaded with the core purpose, then details modes, parameters, and usage guidance. It could be slightly more concise, but no wasteful sentences are present.

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

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

Given the tool's complexity (two modes, multiple return fields) and the absence of an output schema, the description fully covers all return fields (top_of_book, vwap_fill_price, etc.) for both modes. It also addresses edge cases like thin legs and forced directional risk, making it complete for an agent to understand behavior.

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

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

Schema coverage is 100%, with all 4 parameters described. The description adds meaning beyond the schema: clarifies default side for basket mode (auto based on partition sum), interprets size_usd as settlement notional for basket, and lists default values and ranges. This compensates for the lack of enums.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) with explicit verbs and resources, differentiating it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why alternatives are insufficient, citing risks of partial fills and uncapturable overround.

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; description adds safety fields (compatibility_warning, temporal_alignment, skipped counts) and warns that pre-mapped topics may not be tradeable. No contradictions with annotations.

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

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

Description is dense but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds information, though could be slightly more concise without losing detail.

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

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

Despite no output schema, description comprehensively explains response fields (leg-by-leg prices, spread, compatibility_warning, temporal_alignment, counters). Covers edge cases and provides sufficient context for an AI agent to interpret results.

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

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

Schema coverage is 100%, and description adds context beyond schema: explains topic overrides, lists 10 macro shortcuts, and clarifies how explicit params override topic-mapped sides. Adds value beyond the schema definitions.

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

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

Description explicitly states it computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools by focusing on cross-venue comparison and specific modes.

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

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

Clearly explains two modes (topic shortcuts vs explicit ticker/slug), when compatibility_warning fires, and when spreads are meaningless. Provides guidance on handling various cases, though does not explicitly contrast with alternatives like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by explaining scoping (anonymous IP, BYO key hash, or account ID) and the behavior when key is omitted (list all keys). 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 clear, front-loaded sentences with no filler. Each sentence adds essential information: purpose, usage context, and scope/scoping.

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 simplicity of the tool (1 optional parameter, no output schema), the description covers the essential behavior and outcome. It could mention the return format, but it's not strictly necessary.

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

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

The schema covers 100% of parameters with descriptions. The description adds the crucial detail that omitting the key lists all saved keys, which is not in the schema description, aiding correct usage.

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

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

The description clearly identifies the tool's function: retrieve a saved value by key or list all keys when omitted. It distinguishes from siblings (remember, forget) and specifies the scope of retrieval.

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 stored context) and mentions related tools (remember, forget). It does not explicitly state when not to use it, but the context is sufficiently clear.

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

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

Annotations declare readOnlyHint=true, but the description describes a state-changing behavior with mark_read:true that flags events as read. This contradicts the readOnlyHint annotation. IdempotentHint=true may partially reconcile, but readOnlyHint is clear.

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 efficiently convey purpose, parameters, and behavioral notes. No fluff. Front-loaded with main action.

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

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

Despite no output schema, the description details return fields (source, citation_uri, raw payload) and covers filtering, polling, and an alternative endpoint. Fully adequate for agent invocation.

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

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

Schema coverage is 100%, but description adds value by giving examples (e.g., 'sec_8k'), explaining 'since' as ISO timestamp, and clarifying behavior of mark_read and unread_only. This exceeds 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 'Pull fired events from your subscription feed' and specifies it returns recent alerts with key fields. It distinguishes itself from siblings like list_subscriptions by focusing on fired events.

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 clear usage context: mentions polling is fine and offers an alternative endpoint for scripts/dashboards. However, does not explicitly exclude any alternatives or give when-not-to-use guidance.

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

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

The description discloses key behavioral traits beyond the annotations: it fans out to multiple sources in parallel, describes the fallback mechanism (GDELT preferred, GNews when rate-limited or 5xx), notes a soft-fail for USPTO (PatentsView API sunset), and specifies the return format (structured changes[], count, citation URIs). This provides a clear mental model of the tool's 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 a single paragraph that efficiently conveys purpose, sources, parameter details, return format, and alternative tool. Every sentence contributes value; there is no redundancy or filler. The structure front-loads common queries and then provides technical details, making it easy to scan.

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

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

Despite lacking an output schema, the description sufficiently describes the return structure. Given the tool's moderate complexity (three sources, fallback, parallel calls), the description covers all essential aspects: what it does, how to parameterize it, what happens under failure conditions, and how to interpret results. The mention of an alternative tool closes the completeness 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?

Although the schema already provides descriptions for all parameters (100% coverage), the description enriches them with concrete examples and usage details. For 'since', it illustrates both ISO date and relative shorthand formats with examples. For 'value', it clarifies it accepts tickers or zero-padded CIKs. This adds meaningful context beyond the raw schema.

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

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

The description begins with multiple concrete example queries ('What's new with X', 'latest on Y'), immediately clarifying the tool's purpose as a change feed for a company. It specifies the resource (company) and the data sources (SEC EDGAR, GDELT→GNews, USPTO), and distinguishes itself from the sibling tool 'entity_profile' by contrasting the dynamic feed with the static 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 explicitly states when to use this tool ('What's new with X' scenarios) and when to use an alternative ('Use entity_profile instead when you want the static profile'). It also provides usage hints for the 'since' parameter ('Use "30d" or "1m" for typical monitoring'), guiding appropriate invocation.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds beyond that: key-value scoping by identifier, persistence differences (authenticated vs anonymous). 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?

Five sentences, front-loaded with purpose, efficient without wasted words. 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 only 2 parameters, no output schema, and good annotations, the description is complete: covers usage, behavioral context, persistence, and pairing with sibling tools.

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

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

Schema has 100% coverage with descriptions for both key and value. The description adds meaningful context with key examples (e.g., 'subject_property', 'target_ticker') and value content hints, adding value 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 uses 'Save data the agent will need to reuse later' which is a specific verb-resource pair with clear scope. It distinguishes from sibling tools recall and forget, and provides concrete examples like 'resolved ticker, a target address, a user preference'.

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: 'when you discover something worth carrying forward' and contrasts with sibling tools: 'Pair with recall to retrieve later, forget to delete.' This provides clear guidance on alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses meaningful behaviors: it returns specific fields per type (ticker/CIK for company, RxCUI/ingredient for drug), includes citation URIs, auto-disambiguates company inputs, and cascades through multiple internal endpoints. It does not cover failure modes or rate limits, but the annotations already establish safety, so this is solid.

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 appropriately sized and front-loaded with examples. It covers purpose, supported types, return values, usage guidance, and even the internal cascading behavior without wasted words. 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?

For a two-parameter tool with strong annotations and full schema coverage, this description is remarkably complete. It explains what the tool does, when to use it, what parameters mean, and what outcomes can be expected (specific IDs, citations). No output schema exists, but the description covers the essential return information well.

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 has 100% parameter description coverage, so the bar is at baseline 3. The description adds concrete value with examples (AAPL, 0000320193, ozempic), explains what each entity type returns, and mentions auto-disambiguation—going beyond the schema's simple descriptions.

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

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

The description clearly states the tool's function: resolving a user-spoken name to a canonical/official identifier required by other tools. Examples ('What's the ticker for…') and specific resources (company, drug) make the purpose unambiguous and distinguish 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 says 'Use FIRST whenever you have a name but need an ID,' giving a clear when-to-use directive. It also notes that it replaces 2-3 manual lookups. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a 5.

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

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

Description adds behavior beyond annotations: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score/confidence/signal density. No contradiction with read-only, open-world, idempotent hints.

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

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

Two sentences with zero waste. The first sentence states core function, second provides usage context and return details. 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 4 parameters (1 required) and no output schema, description covers behavior, usage, and return structure sufficiently. Slightly missing is handling of errors or edge cases (e.g., fewer than 2 entities), but overall adequate.

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

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

Adds meaning beyond schema: explains that 'entities' first entry is treated as 'subject' for narrative, and clarifies the role of 'context' for disambiguation. Even though schema coverage is 100%, the description provides valuable 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 uses specific verbs ('Compare', 'Scan') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by focusing on AI visibility ranking for competitive audits.

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 'Useful for competitive AI-marketing audits' with an example query. Implies single-entity checks should use ai_visibility_check, but does not explicitly state when not to use this tool.

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

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

Beyond annotations (readOnly, idempotent), description adds details on fan-out, partial failure handling, bundlephobia timeout, and what the tool returns. 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?

Single paragraph that is dense but well-organized. Could benefit from a list for return fields but still concise and front-loaded.

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

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

Even without an output schema, the description fully details the return structure (summary block, advisories, links, alternatives). Covers edge cases (partial failures, ecosystem scope).

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

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

Schema coverage is 100%, but description adds value by noting scoped packages are accepted (not in schema) and that version defaults to latest. Slightly exceeds 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's a composite check for npm packages, fanning out across deps.dev and bundlephobia, and lists what it returns. It distinguishes from siblings by being npm-specific.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"' and notes ecosystem limitation and alternative for other ecosystems.

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

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

Discloses embedding model (BGE-base-en), chunking (500-char windows), cap (200K chars with truncation flag), and return info (offsets, similarity scores). Annotations already indicate safety; description adds valuable technical detail.

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

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

Concise (5 sentences), front-loaded with main purpose. Technical details are included but still efficient. Slightly dense but not overly verbose.

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

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

Complete for a search tool: explains inputs, outputs (passages with offsets), limitations (cap), and pairing with sibling. No output schema needed as returns 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 coverage is 100%, so baseline 3. Description adds example queries for 'query' and mentions default for 'limit', but does not add significant new meaning beyond schema descriptions.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with specific verb and resource. Distinguishes from sibling 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 tells when to use: when record is too big to prompt. Mentions alternative: ask_pipeworx_grounded for grounding over passages.

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 substantial detail beyond annotations: creation operation, subscription persistence, delivery channel behaviors (e.g., SMS cap, webhook failure handling). No contradictions with annotations.

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

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

Well-structured with front-loaded purpose. Contains necessary examples and constraints without excessive verbosity. Could be slightly tighter but overall efficient.

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

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

Covers all aspects: purpose, prerequisites, types, parameters, delivery channels, constraints, and return value. Adequate for a tool with no output schema and moderate complexity.

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

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

Schema coverage is 100%, but description adds valuable examples and clarifies parameter usage (e.g., sec_8k items, polymarket_edge topic). Enhances understanding beyond schema.

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

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

The description clearly states it creates a proactive monitoring subscription and returns the new subscription id. It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation.

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 prerequisites (Pipeworx OAuth account) and detailed type-specific guidance with examples. Does not explicitly list when not to use or contrast with alternative tools, but context 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 indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: returns 'category-bucketed example questions... drawn from the live catalog of thousands of tools', and explains behavior of omitting vs. specifying topic.

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 comprehensive but slightly lengthy. It front-loads common user queries and organizes information well (purpose, categories, usage guidance). Each part is valuable, but a more streamlined version could improve conciseness.

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 schema (1 optional param, no output schema), the description fully covers the tool's purpose, usage, parameter behavior, and return content. It also positions the tool within the broader tool suite.

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 topic as optional string with enumerated suggestions (finance, pharma, etc.). The description adds the behavioral nuance: 'Omit for a cross-category spread' and reiterates the focus areas, 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 uses specific verbs ('return category-bucketed example questions') and clearly identifies the resource (Pipeworx question suggestions). It distinguishes the tool as the onboarding entry point from siblings like 'ask_pipeworx' or 'discover_tools'.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains both the no-argument and topic-filtered usage patterns. Provides concrete examples of when and how to call.

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, covering safety and idempotence. The description adds that it returns quantities to air, water, and land by year, which is useful 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 sentence that front-loads the core purpose and output structure. No unnecessary words or repetition; every part 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 existence of an output schema and simple parameters, the description adequately covers inputs and outputs. It explains the breakdown by year and media, but does not mention that state is optional. Slight room for improvement.

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 each parameter has a description. The description restates the 'chemical' and 'state' dimensions but adds no extra meaning beyond the schema. Thus it meets the baseline for high-coverage schemas.

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

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

The description uses a specific verb 'track' and specifies the resource 'toxic chemical releases' with clear dimensions: chemical name, state, and yearly breakdown. This distinguishes it from sibling tools like tri_facility_releases (facility-level) and tri_trends (trend analysis).

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

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

The description explicitly states the two key filters (chemical name and state), making it clear when to use this tool—for chemical-state queries. However, it does not mention when not to use it or provide explicit alternatives, though sibling names imply differentiation.

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 cover read-only behavior, idempotency, and non-destructiveness. The description adds the output content (facility location, county, type, chemicals with quantities in pounds) which is helpful but not extra behavioral context like rate limits, auth, or pagination.

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

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

Two concise sentences: the first explains the search scope and query shape, the second summarizes the return fields. No redundancy, front-loaded with the verb and resource.

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

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

With a rich output schema and annotations, the description covers the core functionality well. It omits mention of the limit and facility_name parameters, but those are documented in the schema. It could mention when not to use this tool (e.g., for chemical-specific queries), but overall it is sufficient.

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

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

Schema description coverage is 100%, with each parameter already well-documented (e.g., county format). The description restates that search is by state and optional county but adds no 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 searches EPA TRI toxic chemical release facilities by state and optionally county, with an example query shape. It does not explicitly distinguish it from sibling tools like tri_chemical_releases or tri_trends, but the scope 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?

The description provides clear context for when to use the tool: for queries about toxic releases by location (state/county), illustrated by 'what toxic releases are reported in Harris County, Texas'. However, it does not mention exclusions or alternative tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's claim of returning historical data is consistent and adds moderate context. However, it does not elaborate on other behavioral traits such as pagination, data freshness, or the meaning of 'trends' beyond patterns, which would add value. 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 extremely concise at two sentences (16 words), front-loading the key action and scope. Every word contributes purpose, with no redundant or vague phrasing.

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 100% parameter documentation, the description is mostly complete. It covers the core concept, but a slight gap remains: it does not clarify whether both state and chemical can be specified simultaneously or that at least one is needed (implied by examples but not stated). The date range defaults are handled in the schema, so overall it is adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some contextual value by stating 'by state or chemical' and 'historical release data across years,' reinforcing that start_year and end_year define the range. However, it does not add new meaning beyond what the schema descriptions already provide for each parameter.

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: 'Analyze toxic release trends over time by state or chemical.' It uses specific verbs ('analyze', 'returns') and resources ('trends', 'historical release data'), and the mention of 'by state or chemical' differentiates it from sibling tools like tri_chemical_releases and tri_facility_releases, which likely focus on individual releases rather than trends.

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 the tool is for trend analysis but does not explicitly state when to use it over siblings or when to avoid it. No guidance is provided on prerequisites, exclusions, or alternative tools, relying on the user to infer from the verb 'analyze trends' versus the siblings' likely focus on specific releases.

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 critical behavior beyond annotations: 'row is deactivated (not deleted) so historical events stay available'. Also mentions ownership enforcement. No contradictions with annotations.

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

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

Two concise sentences, zero fluff, front-loaded key action.

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

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

With single parameter and good annotations, description covers action, ownership constraint, and deactivation behavior. Complete for agent invocation.

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

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

Schema covers 100% of parameter with description. Description adds no extra info beyond 'Subscription id (uuid) returned by subscribe.' Baseline score 3.

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

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

Clearly states 'Cancel a subscription by id', identifying verb and resource. Distinct from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Notes ownership enforcement ('you can only cancel your own subscriptions'), providing clear context for use. No explicit when-not-to-use but implicitly clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true. Description adds substantial behavior: dual-path processing (SEC EDGAR+XBRL vs grounded pipeline), return structure (verdict, value, citation, reasoning), and that it replaces multiple calls. No contradictions.

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

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

Description is a single paragraph but well-structured with examples, conditionals, and output summary. Every sentence adds value; could be slightly more concise but remains clear 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?

Despite no output schema, description fully explains return values: verdict types, actual value with citation, reasoning. Parameter count low, coverage high. All necessary context for correct invocation is present.

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

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

Schema coverage is 100% with detailed descriptions for both parameters. Description adds extra context: tolerance_pct overrides implied tolerance, default is implied by wording capped at 5%. This meaningfully extends the schema.

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

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

Description clearly states it verifies natural-language factual claims, with examples like 'Is it true that…' and 'fact check'. It distinguishes itself by noting it replaces 4-6 sequential calls, and explicitly covers both company-financial claims and other factual claims via different 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?

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct'. Provides conditional guidance for financial vs other claims, though no explicit when-not usage is given; still clear and actionable.

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