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 readOnly/openWorld/idempotent annotations, the description discloses that the tool routes to a large corpus, fills arguments, and returns structured answers with stable citation URIs. It also notes it works on every tier and is a single fast call, adding useful operational context, though it does not discuss failure modes or rate limits.

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

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

The description is long but every part earns its place: the critical preference directive is front-loaded, examples are concrete, and sibling differentiators are clearly separated into 'START HERE' and 'Step up only when needed'. There is no redundant filler.

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

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

For a router tool with no output schema, the description covers the essential context: what kinds of questions to ask, when to use it, when to use alternatives, what the response includes, and that it works across tiers. An agent has enough information to invoke it correctly for a wide range of factual queries.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful context beyond the schema by enumerating example questions and clarifying the natural-language query scope. The aliases are already documented in the schema, so the description's value is in illustrating what makes a good question.

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 this tool routes factual questions about current/historical data to one of 5,724 tools and returns structured, cited answers. It explicitly differentiates itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, so an agent knows exactly what it does.

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

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

Usage guidance is explicit: prefer it over web search for factual questions, use it for common question phrasings like 'what is' or 'find', and step up to ask_pipeworx_grounded or deep_research only for specific needs. It also covers breaking-news scenarios, making the decision boundary clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it is a beta with candidate routing improvements, currently matching the stable router, and it does not fall back to anything—it is a full working router. This goes beyond the annotations by explaining the experimental nature and current equivalence.

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

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

The description is front-loaded with the key fact (beta, identical, experimental) and then usage guidance. It is somewhat lengthy but every sentence contributes context about the beta behavior and similarity to the stable tool. It could be tightened slightly but remains 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?

For a universal router with a single question parameter and no output schema, the description explains it is identical to ask_pipeworx, which implies the same response format and scope. It also clarifies the current state (no active candidate) and that it is a full working router. This is sufficient for an agent to call it correctly, though it relies on the sibling's definition for full output details.

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

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

Schema description coverage is 100%, so all six parameters (question and its five aliases) are already fully documented. The description adds no parameter-specific meaning, which meets the baseline for high schema coverage.

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

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

The description clearly states it is a beta version of ask_pipeworx, a universal router with the same tool set and response shape. It explicitly distinguishes from the stable sibling by identifying itself as the experimental edge, so an agent can immediately understand what it does and how it differs.

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

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

It provides explicit direction: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the purpose (results compared against stable to decide merges). It implies that for stability one would use the stable router, but does not explicitly state a when-not condition, so a small gap remains.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, so the bar for added value is higher. The description goes well beyond that by disclosing that answers are extracted solely from the tool result, that refusals have explicit reasons, and that it costs one extra LLM call. No contradiction with annotations—in fact, the grounded, read-only behavior aligns with readOnlyHint and idempotentHint.

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

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

The description is dense but every sentence earns its place: purpose, mechanism, exact return shape, refusal modes, usage context, and cost/alternative. It front-loads the defining trait ('hallucination-resistant answer mode') before moving to details. For a tool with no output schema, this level of detail is justified, not bloated.

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 specifies the success return object and every refusal_reason enumeration. It also covers the routing behavior, the extra-cost tradeoff, and the scenarios where this mode should be selected. An agent has everything needed to decide when and how to invoke this tool correctly.

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

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

Schema description coverage is 100%: all six parameters are documented as aliases for the same natural-language question, so the schema carries the parameter-meaning burden. The description does not add anything about parameter format or semantics, but none is needed given the schema's clarity. 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 opens with a specific purpose—'hallucination-resistant answer mode for high-stakes reads'—and explains the grounded extraction mechanism. It also clearly differentiates from its sibling ask_pipeworx by framing it as the same routing but with evidence-based, refusal-capable answering. An agent can immediately tell what this tool does and how it differs from the non-grounded variant.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' with concrete domains like financial verdicts and legal claims. It also names the alternative and states the cost tradeoff: 'prefer ask_pipeworx for casual lookups.' This is model usage guidance.

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

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

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?

Annotations cover read-only, idempotent, and non-destructive hints, but the description adds substantial behavioral context beyond those: account/paid-plan requirements, parallel decomposition across 5,724 tools, gaps[] for unanswered facets, contradictions[] scanning, latency expectations, semantic excerpting, and resolvable citation_uri guarantees. Nothing contradicts the annotations.

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

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

The description is long but densely informative and mostly front-loaded with the account gate before the core action. There is minor redundancy around citation fields ('stable pipeworx:// citation per finding' and later 'citation_uri'), and some detail could be trimmed, but the length is largely justified by the tool's complexity.

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

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

With no output schema, the description carries the full burden of explaining return behavior, and it does so thoroughly: findings packet composition, gaps[], contradictions[], hop field, citation_uri resolvability, latency, and excerpting behavior. It also covers prerequisites, fallback tools, and when results will be empty, making the tool fully callable by an agent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes well beyond the schema by explaining what each depth value actually does: 'standard' re-angles unanswered gaps, 'thorough' chases leads and adds contradictions, and 'quick' is a single hop. It also clarifies that the question parameter is meant for broad natural-language research questions, matching the tool's decomposition purpose.

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 and resource: 'Grounded multi-source research across Pipeworx's 1497 STRUCTURED data sources... in ONE call.' It clearly distinguishes itself from open-web search and from ask_pipeworx, and explains what the findings packet contains. An agent can immediately tell what this tool does without reading the schema.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data.' It also names alternatives and conditions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' The account-requirement fallback ('use ask_pipeworx instead') is also explicitly 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?

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?

The description goes far beyond the readOnly/destructive annotations by disclosing the matching algorithm, compatibility codes, fee disclaimers, and how unknown legs are excluded from pairing. It is exceptionally transparent about potential mismatches, the meaning of null temporal_alignment, and the gross-not-net nature of spreads. This exceeds what annotations provide.

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

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

The description is a dense wall of text well over 500 words, mixing essential safety info with many caveats in a single paragraph. While it uses CAPS and some segmentation, it is not concise and would benefit from bullet points or clearer section breaks. This makes it harder for an agent to quickly extract key usage rules.

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 and the absence of an output schema, the description covers the response structure in detail, including spread fields, compatibility codes, skipped pairs, and fee notes. It explains the meaning of null temporal_alignment and the conditions for compatibility warnings, making it complete for an agent to understand expected outputs and caveats.

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

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

The schema already describes each parameter, and the description adds mode-level semantics and examples of ticker formats. The topic parameter's allowed values are listed in the schema description, and the description reinforces their meaning and how they interact with the explicit parameters. This adds value beyond the schema without being redundant.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question, which is specific and differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges. It also outlines two distinct modes (topic shortcuts and explicit tickers), making the purpose unambiguous.

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

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

The description explicitly explains the two modes and provides context on when to use each (topic shortcuts vs. explicit tickers). It also warns that many pre-mapped topics return compatibility warnings, indicating when not to expect tradeable spreads. However, it does not directly compare to sibling tools such as polymarket_arbitrage, though the this-vs-that distinction is partly implicit.

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?

The description goes well beyond the readOnly/idempotent annotations by disclosing behaviors such as graceful degradation when GLEIF/OpenFIGI are unavailable, explicit unresolved identifiers, non-assertion on ambiguous matches, and internal cascading lookups. No contradiction with annotations exists.

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

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

The description is long but front-loaded with purpose and usage guidance before diving into type-specific details. It is dense and somewhat run-on, but every sentence carries substantive information about inputs, outputs, or edge cases, making the length justifiable for a complex tool.

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

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

For a tool with no output schema, the description adequately covers accepted inputs, supported types, return fields, ambiguity handling, failure behavior, and degradation. The complex multi-source behavior is explained sufficiently for an agent to call the tool correctly and interpret results.

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

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

Schema coverage is 100% and the schema already documents the value parameter in detail. The description adds meaning beyond the schema by noting that ISIN is also accepted as input, explaining the ISIN-to-LEI resolution path, and reinforcing the entity-name-only instruction with bond-specific examples.

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

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

The description states a specific verb and resource: resolving user-spoken names to canonical/official identifiers that other tools need. It gives concrete query examples and enumerates supported entity types, making the tool's unique role in the sibling set unmistakable versus profile or comparison 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?

It explicitly says 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It does not name sibling alternatives like entity_profile or compare_entities, nor state explicit when-not-to-use conditions, so it stops short of a full 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 readOnly, openWorld, idempotent, and safe traits. The description goes well beyond annotations by explaining two execution paths (SEC EDGAR structured vs. grounded pipeline), defining the verdict enum, and crucially distinguishing 'could_not_verify' (internal failure, not evidence) from 'unsupported' (no source). This is critical behavioral context for correct interpretation.

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

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

The description is long but every sentence earns its place. It opens with example phrasings, explains routing logic, lists return values, and ends with a critical caveat about error semantics. The structure is logical and front-loaded, with no filler or repetition.

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

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

Given the tool's complexity and absence of an output schema, the description fully compensates: it spells out return values (verdict, cited value, reasoning), enumerates possible verdicts, explains error behavior, and even mentions what the tool replaces. Annotations cover safety, and the two parameters are fully documented in both schema and description.

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

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

Schema coverage is 100% with good descriptions for both parameters. The description adds extra semantics: it explains that tolerance_pct overrides the tolerance implied by claim wording, gives specific guidance for hallucination detection (1–2), and illustrates the claim parameter with concrete examples. This goes beyond the schema's 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 the tool's function: natural-language claim verification against authoritative sources. It uses specific verbs like 'fact check,' 'verify,' and 'confirm or refute,' and even provides example phrasings. It distinguishes itself from siblings by focusing on claim verification and explicitly noting it replaces 4–6 sequential calls.

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

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

The description gives explicit guidance on when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and explains routing for different claim types (company-financial vs. other). It does not name alternative sibling tools or provide exclusions, but the context is clear and the 'Replaces 4–6 sequential calls' line frames it as a consolidated alternative.

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