Epa Echo

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety. The description adds valuable behavioral context: default model is free, BYO key for Anthropic, pricing model, and that probing calls external APIs. This goes beyond the annotations.

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

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

The description is two sentences long, front-loads the action and output, and every sentence adds value. It efficiently covers purpose, output structure, model details, and use cases 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?

The tool has 4 parameters and no output schema, yet the description explains the output structure ('per-model {score, confidence, signals, raw_response} + combined view'), scoring range, and key parameter constraints. It is fully complete for an agent to understand what the tool returns and how to invoke it.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds significant meaning: it explains the 'entity' parameter's purpose, lists supported models for 'models', details the '_apiKey' format and purpose, and describes how 'context' disambiguates. This greatly aids correct parameter 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's purpose: probing LLMs for brand visibility and scoring 0-100 per model. It uses a specific verb ('probe') and resource ('one or more LLMs'), and distinguishes from siblings like 'scan_competitor_ai_presence' by emphasizing multi-model probing and scoring.

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

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

The description provides explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly state when not to use or mention alternatives, but the context is sufficiently clear for an agent to decide.

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?

Annotative hints (readOnly, openWorld, idempotent) are aligned and extended: description explains that the tool routes to 5,578 tools, fills arguments, and returns structured answers with pipeworx:// citation URIs, plus notes it works on every tier and is a single fast call. This goes beyond annotation basics, revealing internal workflow and output format without contradicting declarations.

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

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

The description is long but well-structured, using capitalization for 'PREFER OVER WEB SEARCH' and stepwise guidance. Some redundancy is present (e.g., repeating that it's the default entry point), yet each sentence brings new information—examples, routes, fallback tools. It is readable and front-loads key 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 tool's high complexity (many sources, routing, citations) and absence of an output schema, the description covers domain range (filings, drugs, economics, etc.), behaviors (routing, argument-filling, citation URIs), and contrasts with siblings. No major gaps; it sets correct expectations for use cases and results, making it complete 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?

Schema covers all 6 parameters, all aliases for the question, with descriptions already stating 'natural language'. The description does not add extra parameter-level detail beyond what the schema provides, but it does reinforce that the question is the only input. With high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool answers factual questions about current or historical data from authoritative sources, listing specific domains (SEC, FDA, FRED, etc.) and giving concrete examples. It also distinguishes itself by preferring it over web search and positioning it as the default entry point compared to sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly states when to use (for factual questions on real-world data) and when to step up to alternatives, naming ask_pipeworx_grounded for single grounded answers and deep_research for broad/multi-part queries, and clarifying that news/breaking topics are handled by itself. This binding guidance is precise and actionable.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable dynamic context: that candidate improvements may be live, the current state (no candidate active, retired 2026-07-26), and that results are compared for merge decisions. This helps the agent understand variability over time. It could add more detail on error behavior or timeout semantics, but for a router with good annotations, this is solid.

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

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

A single dense paragraph of about 100 words, front-loaded with the most critical facts (beta of ask_pipeworx, identical interface). Every sentence earns its place — current state, usage instruction, comparison process, and disclaimer that it falls back to nothing. Slightly long, but no fluff.

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

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

Given the complexity (an evolving router with one required parameter, no output schema), the description compensates well by confirming the stable response shape and its full production-readiness ('this IS a full working router'). It addresses potential misconceptions about the beta label. Loses a point for not elaborating on return/response specifics beyond 'same response shape,' but the reference to the stable version mitigates this.

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 parameters documented as aliases for 'question.' The description adds no parameter-specific guidance, but the schema already documents the question semantics well. Baseline of 3 is appropriate since the description is doing nothing extra here, though the schema fully covers the burden.

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 immediately identifies this as the beta of 'ask_pipeworx' with a specific role: a universal router (5,578 tools, same arguments). It provides concrete scope (what's identical: arguments, response shape; what differs: candidate routing improvements). It distinguishes from siblings by explicitly naming the stable alternative (ask_pipeworx) and framing this as the 'experimental edge.'

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

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

The description gives explicit usage context: 'Use it exactly like ask_pipeworx when you want the newest routing' and names the comparison behavior against the stable router. The alternative is named, though it could be more explicit about when to prefer the stable version over the beta, or about stability caveats.

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

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

The description adds substantial behavioral detail beyond the annotations: the exact success return shape {answer, evidence (verbatim quote), confidence, source, fetched_at, refusal_reason:null}, the full refusal enum, the verbatim-quote evidence guarantee, and the cost disclosure ('Costs one extra LLM call'). The refusal mechanism aligns with and enriches openWorldHint=true, and no contradiction with the 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?

Exceptionally information-dense at ~130 words with zero fluff: front-loaded purpose, then mechanism, return types with enum values, usage criteria, and cost/alternative trade-off. Each detail earns its place. Deduction for being a run-on wall of text that would benefit from structural segmentation, though this is partially offset by the value of the compact content.

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 provides complete coverage: the full success and failure return contracts with enums (critical given output schema absence), refusals for open-world semantics, multiple example high-stakes domains, cost implications, and explicit comparison to the sibling. It is a model example of compensating for missing structured output documentation.

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 6 parameters documented as aliases for the question string. The description meaningfully adds orchestration context (routing across 5,578 tools and 1,463 sources) and refusal semantics that inform how the question will be handled, which elevates it above the baseline 3. It stops short of a 5 because it doesn't provide guidance on question formulation or quality, though that's a minor gap given the single-string 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 leads with a specific, verb+resource statement ('Hallucination-resistant answer mode for high-stakes reads') and details the exact mechanism: routing to 5,578 tools, fetching data, and extracting answers with verifiable evidence. It clearly differentiates from the sibling tool ask_pipeworx by the grounded evidence/refusal behavior, going well beyond a tautological restatement.

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

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

Explicit when-to-use guidance is given: 'Use whenever an answer will be quoted, cited, or acted on' with concrete domains (financial verdicts, legal claims, medical lookups, public statements). It also provides a clear when-NOT-to-use: 'prefer ask_pipeworx for casual lookups,' naming the exact alternative and the reason (costs one extra LLM 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 indicate safe, read-only behavior. The description goes far beyond by detailing fan-out logic, response shapes, resolver contract, parent_event extraction, news fallback handling, safety short-circuits, and resolution-rule risk. 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 excessively long (approximately 1000+ words) and includes many low-level details that could be in separate documentation. While front-loaded with the main purpose, it lacks conciseness for quick agent parsing.

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, no output schema, and three parameters, the description covers all behavioral aspects: resolution reliability, parent event extraction, news fields, safety checks, tradeability, and cancellation rules. It is exhaustive.

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%, providing baseline 3. The description adds meaningful context: explains 'market' accepts slug/URL/question, 'depth' quick vs thorough defaults, and 'include_raw' purpose and size implications.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific input types (slug, URL, question text) and use cases like 'should I bet on X'. It is specific and distinct from sibling tools like polymarket_edges or arbitrage tools.

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

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

The description provides explicit usage contexts ('Use for should I bet on X...') and mentions blocking conditions for closed markets or low-confidence matches. However, it does not compare against sibling tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, etc., and the description adds valuable behavioral details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URI generation. No contradiction with annotations.

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

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

The description is well-organized with trigger phrases first, then detailed behavior. Every sentence adds value, but it is slightly verbose. Could be trimmed slightly without losing substance.

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, multiple data sources, sorting, citation URIs), the description covers all necessary aspects: input format, data retrieval details, output characteristics, and comparison with alternatives. No output schema, but the description sufficiently indicates what is returned.

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 significant meaning: it explains the 'type' enum in terms of data sources and behavior, and provides concrete examples for 'values' (tickers/CIKs for company, drug names for drug). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It provides specific trigger phrases like 'X vs Y' and 'which is bigger', and distinguishes it from similar tools like 'entity_profile' by emphasizing its multi-entity comparison capability.

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

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

Explicitly instructs to prefer this tool over sequential single-entity lookups when comparing entities, stating it 'replaces 8-15 sequential lookups'. This gives clear usage context and tells the agent when to choose this tool over alternatives.

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

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

Annotations provide readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial context: requires an account, free tier vs paid for depth:'thorough', not open-web search, returns citations and gaps[] when data can't answer, contradictions[] for standard/thorough, time expectations (15-60s, up to ~90s), and that large records are semantically excerpted. No contradiction with annotations.

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

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

The description is a long paragraph with many details. While each sentence contributes important information, it is not concise and could be better structured (e.g., bullets for depth levels, caveats). It is front-loaded with account requirement and alternatives, but the length exceeds what is typical for a tool description, though the complexity of the tool mitigates this somewhat.

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 parameters, no output schema), the description covers all necessary context: prerequisites (account), what it returns (findings packet with citations, gaps, contradictions), limitations (not good for breaking news), performance expectations, and how depth levels affect behavior. It is complete for agents to select and invoke correctly.

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

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

Schema coverage is 100% (both parameters have descriptions), so baseline is 3. However, the description greatly enriches parameter meaning: it explains depth options in detail (quick=3, standard adds gap recovery and contradictions, thorough adds iterative hop and contradictions), and clarifies that the question can be broad/multi-part. This adds significant value beyond the schema.

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

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

The description clearly states it is a grounded multi-source research tool across structured data sources, decomposing questions into facets and routing to tools in parallel. It explicitly distinguishes from siblings like ask_pipeworx (single lookup) and mentions it is NOT open-web search, so the purpose is unambiguous and 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 states when to use: broad/multi-part questions over structured data, and when to use alternatives: single lookup or breaking/colloquial news should go to ask_pipeworx. Also provides account requirements and depth-level guidance, making the decision criteria very 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, and non-destructive behavior. The description adds valuable behavioral details: it returns top-N most relevant tools with full schemas and curated examples, ready to call directly without a second lookup. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences, starting with the core purpose, followed by usage guidance and return value details. No redundant or extraneous content. Every sentence earns its place.

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

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

Given the tool's complexity (discovery among many siblings) and the absence of an output schema, the description is complete. It explains what it does, when to use it, and what it returns (names, descriptions, schemas, examples). No gaps for an AI agent to misinterpret.

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% (all 6 parameters described in schema). The description does not add significant new meaning beyond the schema; it mentions accepting natural language queries and aliases, which are already documented. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific domains (SEC filings, FDA drugs, etc.), making the scope obvious. It distinguishes itself from sibling tools by being a discovery/lookup tool rather than a specific data source tool.

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

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

The description explicitly recommends using this tool when browsing or discovering available tools: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear context and excludes scenarios where the user already knows the target tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds what is returned but no additional behavioral context beyond annotations. 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?

Single sentence, front-loaded with purpose, no wasted words.

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

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

Output schema exists so return values are covered. Description lists typical outputs sufficiently for a simple lookup 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?

Single parameter registry_id is fully described in schema (100% coverage). Description adds origin context ('from echo_facility_search results') but does not add new meaning beyond schema.

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

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

Description uses verb 'Check' with specific resource 'facility's compliance record' and enumerates specific outputs (violation status, inspection dates, etc.), clearly distinguishing from siblings like echo_violations or echo_enforcement_actions.

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?

Implies prerequisite (registry_id from echo_facility_search) but no explicit guidance on when to use this vs alternatives like echo_enforcement_actions or echo_violations, which may overlap.

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 (readOnlyHint, idempotentHint) already declare safe behavior. Description adds value by listing specific returned fields (action type, penalty amounts, dates, settlement details), providing context beyond annotations.

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

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

Two short sentences, front-loaded with action, no superfluous 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?

Output schema exists so return value explanation is unnecessary. Description covers purpose and data returned. For a simple read-only tool, this is nearly complete, though no pagination or limit details are mentioned.

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

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

Only one parameter (registry_id) with 100% schema coverage. Description reuses 'facility' but adds no new semantic detail beyond what the schema ('EPA Registry ID') provides. Baseline score appropriate.

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

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

Clearly states verb 'Retrieve' and resource 'enforcement cases against a facility', with specific output fields. Distinguishes from sibling tools like echo_violations and echo_compliance_history by focusing on enforcement actions.

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?

Implies usage for retrieving enforcement cases for a facility via registry_id, but lacks explicit guidance on when to choose this over similar tools like echo_violations or echo_compliance_history. No direct mention of alternatives.

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

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

Annotations already indicate readOnly, idempotent, non-destructive behavior. The description adds context: case-insensitive starts-with vs contains match, prefix matching for NAICS, mention of return fields (compliance status, inspection counts, penalties). 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 well-structured with examples and front-loaded purpose, but slightly long at ~150 words. Every sentence adds value, though some redundancy in examples could be trimmed. Still concise for the complexity.

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

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

Given 6 parameters, 100% schema coverage, and presence of an output schema, the description covers all needed context: filter requirements, return fields, edge cases (large states, wildcard usage). Agent can accurately invoke 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%, but the description adds critical semantic details beyond schema descriptions: facility_name's default starts-with behavior and % wildcard usage, NAICS prefix match, and the requirement to pair state with another filter. These add significant value.

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

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

The description clearly states the tool searches EPA-regulated facilities by multiple criteria, distinguishing it from sibling echo_* tools which focus on compliance history, enforcement actions, etc. The verb 'Search' paired with resource 'EPA-regulated facilities' is specific and unambiguous.

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

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

Explicitly states when to use (search facilities), provides critical guidance on combining at least two filters, warns against bare state queries for large states, and gives concrete examples of good queries. This helps the agent avoid common errors.

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

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

The description adds behavioral details beyond annotations: it scans up to 1,000 facilities, returns only those in violation, and is a sample. Annotations already indicate read-only, open-world, idempotent, non-destructive, and the description reinforces and expands on these traits.

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, and each sentence adds value (filters, sampling behavior, return fields). No extraneous text.

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 presence of an output schema, the description covers return fields, sampling limitation, and required filters. It is sufficient for correct invocation without needing additional information.

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 clear descriptions. The tool description mentions the parameters in context (filterable by state and program) but does not add substantive new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds EPA-regulated facilities with violations, filterable by state and program. It distinguishes from sibling tools like echo_violations by specifying it returns facilities in violation and is a sample.

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 the limitation that EPA ECHO has no server-side violation filter, so the tool scans up to 1,000 facilities and returns a sample, not an exhaustive count. This provides clear context for when to use the tool, though it does not explicitly compare to alternatives.

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

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

Annotations already indicate safe, read-only operation. Description adds context on returned data (dates, types, status). No contradictions.

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

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

Two sentences, front-loaded, no fluff. Every word earns its place.

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

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

For a simple two-parameter tool with full annotations and output schema, description covers purpose and basics completely.

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

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

Schema covers both parameters well (100%). Description mentions 'program' filtering but does not add significant meaning beyond schema. Baseline 3 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 verb 'Get', resource 'violation details for a facility', and specifics about filtering and return fields. Distinct from siblings like echo_compliance_history or echo_enforcement_actions.

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 implies use for violation details but does not explicitly contrast with sibling tools or state when to use alternatives. No when-not-to-use guidance.

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

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

Description discloses behavior beyond annotations: fans out across multiple sources (SEC, XBRL, USPTO, news, GLEIF), specifies return fields (cik, filings, fundamentals, patents, news, LEI), notes patents soft-fail until May 2025, and explains input constraints. Annotations already declare readOnly, openWorld, idempotent hints, but description adds operational details.

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 detailed but front-loaded with examples and purpose. Every sentence adds value, though it could be slightly trimmed without losing information. Still efficient for the complexity.

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

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

Given the complexity of a multi-source profile tool and no output schema, the description covers return fields, limitations, fallbacks, and input handling. It is comprehensive and leaves little ambiguity for an AI agent to understand how to use it.

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

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

Schema coverage is 100%, but description adds meaning: type is limited to 'company', value can be ticker or zero-padded CIK, and explicitly says names are not supported. This clarifies the parameter semantics beyond the schema's enum and description.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' with concrete examples like 'Tell me about X', 'research Acme'. It distinguishes from siblings like compare_entities and resolve_entity.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also advises to use resolve_entity first if only a name is available. 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 declare destructiveHint=true and idempotentHint=true. Description adds context that it deletes 'sensitive data the agent saved earlier,' which goes beyond the raw annotation flags. 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?

Two sentences: first states the action, second provides usage context and sibling links. No fluff, every word adds value.

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

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

For a simple one-parameter destructive tool with annotations covering safety, the description fully clarifies purpose, usage scenarios, and relationship to siblings. Return behavior is implied (success/failure) and acceptable without 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% for the single parameter 'key', with schema description 'Memory key to delete'. Description does not add any additional semantic information about the parameter beyond what the schema provides.

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

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

Description explicitly states 'Delete a previously stored memory by key' with specific verb and resource. It clearly distinguishes from siblings 'remember' and 'recall' by positioning itself as the deletion tool.

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

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

Provides explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data.' Also references sibling tools, implying when not to use it (use remember/recall for storage/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, idempotentHint, and openWorldHint. The description adds that it fetches the page and extracts content, which explains the non-destructive, read-only nature. It does not disclose potential caveats like JavaScript rendering limitations or rate limits, but the added context is helpful.

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 concise sentences with no wasted words. It front-loads the main action and purpose, then adds use cases efficiently.

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

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

Given the tool has only 2 parameters, no output schema, and straightforward behavior, the description fully explains input, output format, and use cases. It is complete for an AI agent to decide when and how to invoke it.

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

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

Schema coverage is 100% with descriptions for both parameters. The description reinforces that 'url' should be a full URL and clarifies that 'max_links' has a default of 25 and maximum of 50, adding value beyond the schema.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying exactly what it does (fetches page, extracts title/description/links, emits standard format). It distinguishes from sibling tools like 'scan_competitor_ai_presence' and 'ai_visibility_check' by focusing on llms.txt generation.

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

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

The description provides explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor) but does not explicitly state when not to use it or mention alternatives. The use cases are clear, but exclusion guidance is missing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about return fields and default filtering to active subscriptions, which complements but does not contradict 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 two sentences, front-loading the purpose and usage guidance without any extraneous words, achieving high conciseness and structural efficiency.

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 the lack of an output schema, the description lists the return fields (id, type, etc.) and provides usage context, making it complete for a simple read tool with one optional parameter.

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

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

With 100% schema coverage, the input schema already describes the 'include_inactive' parameter. The description implicitly references it by mentioning 'active subscriptions', but does not add new semantic detail 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 'List the caller's active subscriptions' with a specific verb and resource, and the list of sibling tools includes 'subscribe' and 'unsubscribe', distinguishing this tool as a read operation to review existing 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?

The description explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear guidance on when to use it and linking to sibling tools for adding and canceling.

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 rate limiting (5 per identifier per day), free usage/no quota impact, the anonymous claim_token flow, and how to later retrieve resolution status. Annotations (all false) are consistent with this non-read-only, non-idempotent feedback submission, and the description adds substantial context beyond them.

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

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

The description is relatively long but every sentence earns its place: purpose, usage cases, exclusion, content guidance, token mechanics, and rate limits. It is front-loaded with the core purpose and proceeds logically, with no 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?

Covers all decision-relevant context: when to use, what to include, what response behavior to expect (claim_token), rate limits, and how to follow up. Although there is no output schema, the description adequately explains the return value and its subsequent use.

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

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

While the input schema already documents all parameters at 100% coverage, the description adds crucial semantics: how to use claim_token with an explicit call example and 'no other arguments' constraint, and guidance to refer to Pipeworx tools/packs rather than end-user prompts. This materially improves parameter use.

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

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

The description opens with a specific verb-resource pair ('Tell the Pipeworx team') and immediately enumerates the exact feedback categories (broken, missing, needs to exist). It is unmistakably distinct from the sibling tools, which are all research, lookup, or subscription 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 lists when to use the tool (bug, feature/data_gap, praise) and provides a clear exclusion: if the problematic tool came from a different MCP server, file elsewhere instead. This precision is exactly what an agent needs to route correctly.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable details: self-aggregating signal from CF analytics-engine, no PII, cached 5min-1h.

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

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

Four sentences front-loading what it does, then use cases, then technical notes. No fluff, every sentence adds value.

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

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

Covers purpose, usage, behavior, and parameter semantics well. Lacks explicit output structure (e.g., JSON format), but for a simple tool with no output schema, the description provides sufficient context.

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

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

Schema covers 100% of parameters. Description adds semantic value by explaining that shorter windows surface hot trends and longer windows show steady-state demand, beyond the schema description.

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

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

The description clearly states it returns top tools, top packs, and total call volume over a window. It distinguishes itself from siblings like discover_tools by focusing on trending data.

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

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

Lists three specific use cases (discovering hot data, confirming canonical tool, aligning use case). Could be improved by explicitly stating when not to use, but the use cases provide clear context.

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

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

Annotations include readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds depth: monotonicity checks, partition_sum validation, semantic anchor with Jaccard threshold, placeholder filtering, fill check against live CLOB depth. No contradiction with annotations.

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

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

Description is long but well-structured with sections for SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK. Every sentence adds value. Could be slightly more concise, but the depth justifies length. Front-loaded with main purpose.

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

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

Despite no output schema, description fully explains response structure: opportunities array with gap_pp, suggested_trade, reasoning; partition_check details; fill_check results. Covers edge cases (low similarity, placeholder filter, non-realizable signals). Complete for a complex arbitrage detection 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?

100% schema coverage with descriptions for both parameters. Description adds significant meaning: explains event slug format, topic as seed question, and usage context for each mode. Schema descriptions are adequate, and the description enriches them further.

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 tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Specifies three modes (no args, event, topic) with distinct scopes. Distinguishes from sibling tools like polymarket_fill_risk 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?

Explicit guidance on when to use each mode: event for a specific event slug, topic for cross-event scanning, no args for trending scan. Warns against trading when realizable_edge_pp <= 0. Refers to polymarket_fill_risk for custom sizing, providing clear exclusions and alternatives.

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

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

Annotations indicate readOnly and idempotent. The description adds extensive behavioral context including model formulas, Kelly sizing, caching, diagnostics, and tradeable-edge knobs. 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 overly verbose, with multiple paragraphs of technical detail and redundancy (e.g., segments explained twice). While well-structured, it could be condensed without losing essential information, which may impede quick comprehension by an AI agent.

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

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

Given the complexity of 9 parameters, three segments, diagnostics, and caching, the description covers all aspects thoroughly, including edge cases like empty segments and Fed bet handling. No output schema, but response structure is explained.

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

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

Schema description coverage is 100%, and the description enriches each parameter with context (e.g., slippage_pp explains Polymarket fees, min_partition_leg_kelly explains its role for partition arbs). This adds significant value beyond the schema.

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

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

The description states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, and explicitly mentions 'Built for what should I bet on today'. It distinguishes itself from sibling tools like polymarket_arbitrage by detailing unique segments and knobs.

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 and includes exclusions (e.g., Fed bets are surfaced but excluded from ranking due to unreliable signals). However, it does not explicitly differentiate between this and sibling tools like polymarket_arbitrage, though the segments imply scope.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds important behavioral details beyond annotations: limits on history depth (60-day TTL, dependent on snapshotting start), that decay numbers are from daily closes (not intraday), and the meaning of negative edge_pp_net values. 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 fairly long but well-structured: purpose first, then detailed response format (tracked, expired, snapshot_dates), then limitations. Uses inline code for field names. Could be slightly tighter, but every sentence adds value. Good front-loading.

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?

Although there is no output schema, the description thoroughly explains the response structure: three arrays with fields like trend, decay_pp_per_day, first_seen, lifespan_days, etc. It covers what to expect from each part of the output. For a time-series analysis tool, this is appropriately complete.

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

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

Schema coverage is 100% with descriptions for days (lookback, default 14, clamp 2-30) and window (24hr|1wk|1mo, default 1wk). The description mentions these parameters redundantly but adds no new semantic information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It uses specific verbs ('answers', 'track') and resource ('edge persistence and decay telemetry'), distinguishing it from siblings like polymarket_edges (current edges) and polymarket_arbitrage.

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

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

The description implies when to use this tool via the example comparing fresh vs. 3-week-old edges, and suggests that newer edges may be more informative. However, it does not explicitly state when not to use it or directly name alternatives, though sibling tools like polymarket_edges are implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description adds rich behavioral detail: walks the ladder, returns specifics (vwap_fill_price, slippage, verdict), explains basket risk (thin_legs, forced_directional_risk), and highlights real-world loss modes. No contradiction with annotations.

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

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

The description is dense and efficient, with key purpose upfront, then mode breakdowns, then usage guidance. Each sentence adds unique value. Slightly lengthy due to technical detail, but no filler. Could benefit from minor formatting for readability, but scores high for substance.

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?

Without an output schema, the description fully compensates by listing all return fields per mode, explaining verdicts, and covering risk scenarios. Complexity is high (two modes, multi-param), yet the description leaves no ambiguity for correct 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 the description adds meaning beyond the schema: explains mode selection (market vs event), clarifies auto side for basket, defines size_usd semantics differently for single-market vs basket, and provides example defaults and constraints. This helps an agent choose and fill parameters correctly.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, and the verb 'check' plus resource 'edge' is specific. This contrasts with sibling tools 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?

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when to use, the risk of not using (partial fills become unhedged directional positions), and names the dominant loss mode.

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 safe. The description adds rich behavioral detail: compatibility_warning conditions (non-equivalent bet shapes, semantically unrelated events), temporal_alignment field, and counters for skipped cross-type/subtype comparisons. There is no contradiction with annotations.

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

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

The description is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and uses bullet-point-like headers. Every sentence is informative, though slightly verbose. It could be slightly more concise without losing detail.

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

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

Since there is no output schema, the description thoroughly explains the response structure: venue leg-by-leg prices, top_spreads_pp, and safety fields (compatibility_warning, temporal_alignment, skipped counters). It covers when spreads are meaningful and when they are not, making the tool self-contained for an agent.

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

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

Schema coverage is 100%, with each parameter having a description. The description adds context by explaining the two operational modes, listing valid topic values, and providing example explicit tickers. It also clarifies that explicit parameters override the topic mapping.

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 cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and explains what the tool outputs and when it signals incompatibility.

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

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

The description provides explicit guidance: use topic mode for 10 macro shortcuts or explicit tickers for custom pairings. It warns that most pre-mapped topics return compatibility warnings and that temporal misalignment makes spreads meaningless. However, it does not explicitly contrast against sibling tools like polymarket_arbitrage or bet_research.

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

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

Annotations already indicate readOnlyHint=true and idempotentHint=true. The description adds 'scoped to your identifier', which is valuable behavioral context not in annotations. No contradictions.

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

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

Three sentences cover purpose, usage, and context with no fluff. Front-loaded with the core action.

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

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

For a tool with one optional parameter and no output schema, the description is fairly complete. It explains retrieval, listing, and scoping. Could mention behavior when key not found, but not critical.

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

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

Schema coverage is 100% and already describes the parameter ('Memory key to retrieve (omit to list all keys)'). The description reinforces this but does not add new semantics beyond pairing and scoping, 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 'Retrieve a value previously saved via remember, or list all saved keys', specifying the verb and resource. It differentiates from sibling tools 'remember' and 'forget' by focusing on 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?

Explicitly says when to use (look up context stored earlier) and when to omit key for listing. Mentions pairing with 'remember' and 'forget', giving clear context of 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 read-only, idempotent, nondestructive. Description adds behavioral details: returns specific fields (source, citation_uri, payload), the mark_read flag effect, and that polling works. No contradictions.

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

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

Concise at 4 sentences, front-loaded with main purpose, then filtering and key features. No redundant information.

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

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

Given no output schema, the description covers return fields, filtering, mark_read behavior, and even an alternative access method. All essential context is provided.

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

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

Schema coverage is 100%, baseline 3. Description adds value beyond schema by explaining the effect of mark_read and giving examples for type and since. This improves parameter understanding.

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

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

The description clearly states it 'pull fired events from your subscription feed,' a specific verb+resource. It distinguishes from siblings like list_subscriptions by focusing on events rather than 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?

Provides context for usage, mentioning polling suitability and an HTTP alternative for scripts/dashboards. Does not explicitly compare with all sibling tools, but the context is clear enough for typical use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable behavioral details: fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail until May 2025, and the return format with citation URIs. No contradictions.

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

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

The description is a single paragraph but dense with information. It front-loads the purpose and examples, then explains sources and parameter details. Every sentence adds value, though a more structured format (e.g., bullet points) could improve scannability.

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

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

Given the tool's complexity (multiple data sources, fallbacks, date parsing), the description addresses key aspects: sources, failure modes, return structure. No output schema exists, but it describes the return format sufficiently. Minor omission: does not mention pagination or rate limits.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description enriches this by explaining 'value' accepts ticker or CIK, 'since' accepts ISO date or relative shorthand with examples, and recommends '30d' for monitoring.

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

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

The description clearly states the tool provides a change feed for a company in a time window, with specific examples like 'What's new with X' and lists sources (SEC, GDELT/GNews, USPTO). It distinguishes itself from sibling entity_profile by noting it returns changes rather than a 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 guides when to use this tool versus entity_profile, stating 'Use entity_profile instead when you want the static profile'. It also provides example queries and typical usage ('Use "30d" or "1m" for typical monitoring').

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

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

Annotations indicate idempotent, non-destructive. Description adds details: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' 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?

Well-structured: first sentence states purpose, then usage condition, then behavioral details. Every sentence adds value; no wasted words.

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

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

Given no output schema, the description comprehensively covers storage behavior, scoping, persistence, and pairing with sibling tools. Complete for a write operation.

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 parameters. Description adds context beyond schema (usage context, scoping, pairing) but does not detail parameter values beyond 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 clearly states 'Save data the agent will need to reuse later' and specifies the resource (data) and verb (save). It distinguishes from siblings 'recall' and 'forget' by mentioning them.

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

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

Explicit guidance: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' Also explains persistence differences for authenticated vs anonymous sessions.

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

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

The description discloses that the tool cascades through multiple lookup endpoints, degrades gracefully when GLEIF/OpenFIGI unavailable, returns unresolved identifiers explicitly, and labels each identifier with its source. This goes well beyond the readOnly/idempotent annotations.

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

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

The description is long but information-dense, front-loaded with usage intent and example queries. It is structured with SUPPORTED TYPES and each sentence provides value, though it could be trimmed slightly.

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 having no output schema, the description covers input types, resolution behavior, fallback degradation, output labeling, and unresolved handling, making it highly complete for a complex tool.

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

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

The schema already documents type and value with examples, but the description adds semantics: ISIN resolves to the issuing legal entity via GLEIF, company input accepts ticker/CIK/ISIN/name, and drug accepts brand/generic. This enriches the parameter meaning significantly.

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 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input' and provides specific example queries. It distinguishes itself from siblings by focusing on name-to-ID resolution.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also lists supported types and input formats, but does not explicitly name alternative tools or exclusion 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. Description adds that it internally calls ai_visibility_check and returns ranked list with score, confidence, signal density, which is helpful beyond annotations.

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

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

Two sentences, no fluff. First sentence states purpose and method, second gives use case and output details. Efficient and well-structured.

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

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

Given 4 parameters (1 required) and no output schema, description covers purpose, usage, output format, and internal behavior. Sufficient for an agent to invoke correctly.

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

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

Schema covers all parameters (100% coverage). Description adds context that first entity is treated as subject for narrative, providing extra meaning beyond schema.

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

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

Description clearly states the tool compares AI visibility across multiple entities side-by-side, with specific verb 'Compare' and 'Probes', and distinguishes from sibling ai_visibility_check by mentioning 'multiple entities' and ranking.

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 for competitive AI-marketing audits and an example question, implying when to use. Lacks explicit mention of alternatives but is clear enough for 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, openWorldHint, idempotentHint, destructiveHint. Description adds significant behavioral details: fans out across deps.dev and bundlephobia, partial failure graceful degradation, bundlephobia first measurement can take 5-30s, and sources_failed list. No contradictions.

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

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

Description is front-loaded with purpose, then details, then caveats. Dense but every sentence adds value. Could be slightly more concise, but well-structured.

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

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

Given no output schema, description comprehensively details the return structure (summary block fields, per-advisory detail, links, alternative versions). Also covers failure modes and timing. For a composite tool with partial failure, this is fully complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value beyond schema: specifies that package accepts scoped names, version defaults to latest, and constrains ecosystem to npm. Gives concrete 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 clearly states it is a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying NPM-only scope and directing other ecosystems to deps.dev.

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 an agent asks 'is X safe/popular/small' or 'what does adding lodash cost me'. Also provides exclusions (NPM only, other ecosystems use deps.dev:version directly).

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

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

Annotations already mark the tool as read-only, open-world, and idempotent. The description adds substantial detail: it specifies the embedding model (BGE-base-en), chunking method (500-char overlapping windows), and a hard cap of 200K characters with truncation and flagging. All behaviors are disclosed without contradicting annotations.

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

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

The description is four sentences long, with the first sentence immediately stating the tool's core function. Every sentence adds necessary information (use case, return values, pairing, technical details). No redundant or extraneous content.

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 explains return values: 'top-N passages with character offsets and similarity scores.' It also covers the pairing with ask_pipeworx_grounded, technical constraints (200K cap, embedding model), and the intended workflow. For a tool with three parameters and no output schema, this is exhaustive.

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

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

Schema coverage is 100% with clear descriptions. The description adds context for each parameter beyond the schema: for 'text' it says 'the text you already pulled', for 'query' it provides example natural-language queries, and for 'limit' it explains the range and default. This adds meaningful value but is not essential since the schema is already strong.

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

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

The description clearly states the tool performs semantic search inside a fetched record, specifically targeting scenarios where the record is too large for the prompt. It distinguishes itself from the sibling tool ask_pipeworx_grounded by explaining the pairing and the value of character offsets.

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 when the record is too big to cram into the prompt.' It also provides practical guidance on pairing with ask_pipeworx_grounded and explains that it saves context by returning only relevant 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?

Annotations already indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: OAuth requirement, SMS rate limits (10/day), webhook auto-disable after 10 consecutive failures, and that anonymous/BYO cannot persist subscriptions. It does not contradict annotations, but it does not clarify idempotency behavior (description implies each call creates a new subscription).

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

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

The description is lengthy but well-structured: first sentence states the core action and return, then authentication, then supported types with examples, then delivery channels. It front-loads crucial info. A few sentences could be trimmed, but the density is 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?

The description thoroughly covers input parameters, but since there is no output schema, it only mentions 'Returns the new subscription id.' It lacks details on the full response structure (e.g., whether it includes status or other fields). For a creation tool, this is adequate but not fully complete.

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

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

Schema coverage is 100% with descriptions for each parameter, but the description adds significant value by providing concrete examples for each supported type (e.g., items:['5.02'] for sec_8k), detailed delivery channel options (email, sms, webhook with signing details), and constraints like phone verification and cap. This goes well 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 explicitly states it creates a proactive monitoring subscription, identifies the returned subscription id, and distinguishes itself from sibling tools like list_subscriptions and unsubscribe. The verb 'subscribe' combined with the resource 'alerts' is specific and non-redundant.

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 details when to use the tool (e.g., for specific event types like sec_8k, polymarket_edge) and provides examples. While it does not explicitly contrast with alternatives, the context of subscription management is clear, and siblings like list_subscriptions imply when to list rather than create.

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 the return format: example questions with exact tool and argument shapes. It also explains the effect of the optional topic parameter, providing useful behavioral context.

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

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

The description is detailed but well-structured, front-loading aliases and purpose. It avoids unnecessary words, though it could be slightly more concise. The structure aids quick comprehension.

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

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

Given no output schema, the description fully covers return values (categorized questions with tool arguments) and usage scenarios. For a simple tool with one optional parameter, it provides all necessary context for an agent to use it effectively.

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

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

Schema coverage is 100% with a clear description for the optional topic parameter. The description adds value by explaining the default behavior (full spread) and providing examples of topic values, going beyond the schema's list.

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: an onboarding entry point that returns category-bucketed example questions for Pipeworx. It distinguishes itself from sibling tools like ask_pipeworx by focusing on suggestions rather than direct queries.

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

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

Explicitly states when to use: 'FIRST when you do not yet know what Pipeworx can do' and how to call: 'with no arguments for the full spread, or pass topic to focus'. Provides clear alternatives and context.

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

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

Discloses that the row is deactivated not deleted, and historical events remain available via recent_alerts. This adds significant value beyond the annotations, which already indicate non-destructive 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?

Two sentences, front-loaded with the main action, no filler. Every sentence provides necessary information.

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

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

Simple tool with one parameter and no output schema. Description covers purpose, ownership, and behavioral outcome sufficiently for correct 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?

Only one parameter 'id', fully described in schema (100% coverage). Description adds no additional semantic detail beyond the schema's description that it is returned by subscribe.

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 'Cancel a subscription by id' with specific verb and resource. Ownership and deactivation behavior further differentiate it 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding the agent on when to use. No direct alternatives mentioned, but context is sufficient.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals critical runtime behavior: the two-pipeline routing, the verdict enum, and especially the distinction between could_not_verify (check did not happen, with verification_error) and unsupported (no source), which is essential for correct interpretation. 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?

At ~170 words, the description is longer than strictly necessary, but the example trigger phrases and the detailed caveats about error conditions earn their place. It is well-organized and front-loaded with purpose, though a bit expansive.

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

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

The tool has no output schema and only two parameters, so the description carries the full burden of explaining return values. It covers the verdict list, the actual value with citation, reasoning, and explicitly distinguishes could_not_verify from unsupported, which is critical for safe use. This is a complete and trustworthy 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 description coverage is 100%: claim and tolerance_pct are both well-described with examples and ranges. The description adds a brief reference to tolerance logic but no substantive new parameter semantics, so it meets the baseline of 3.

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

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

The description opens with natural-language trigger phrases and clearly defines the tool as claim verification against authoritative sources. It details two distinct processing paths (SEC EDGAR for company-financial claims, grounded pipeline for other factual claims), which distinguishes it from generic Q&A tools in the sibling list.

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

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

Explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct' and provides guidance on how different claim types are routed. It does not name alternatives or state when not to use it, so it falls short of a 5, but the usage context is clear.

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