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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral context beyond annotations: routing across 5,305 tools, returning citation URIs, being fast, and working on every tier. No contradictions with annotations; the tool's open-world nature is reinforced.

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

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

The description is longer than necessary, with some redundancy (e.g., 'Use whenever...' restates the earlier 'PREFER OVER WEB SEARCH' and the list of domains is partially repeated). However, it is well-structured: opening with a strong directive, then purpose, examples, and alternatives. It earns its length for a broad tool, but could be tightened to improve conciseness.

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

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

Despite having no output schema, the description clearly explains what to expect (structured answer with stable citation URIs). It covers purpose, usage scenarios, examples, and alternatives, making it sufficient for an agent to decide when to invoke this tool and what to provide. Given the tool's broad scope, this is 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% as all six parameters are aliases for 'question' with descriptions. The tool description adds value by providing concrete query examples ('current US unemployment rate', 'Apple's latest 10-K') that clarify the intended input format beyond the schema's generic description. Since the schema already documents all params well, the baseline is 3, and the examples push it to 4.

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

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

The description clearly states what the tool does: 'Routes the question to the right one of 5,305 tools across 1391 verified sources, returns the structured answer with stable pipeworx:// citation URIs.' It distinguishes itself from siblings by explicitly naming alternatives like ask_pipeworx_grounded and deep_research, so the purpose is unambiguous.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Use whenever...' It also says when to step up to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This clearly defines usage vs alternatives.

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

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds valuable context beyond these: it explains the beta nature, that candidate routing improvements are enabled live when under test, and the current state (no active candidate). It also discloses how results are processed ('compared against the stable router'). No contradictions with annotations.

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

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

The description is four sentences, front-loaded with the primary purpose ('Beta version of ask_pipeworx'), and each sentence adds critical information: purpose, current state, usage instruction, and clarification of full functionality. 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?

Despite lacking an output schema, the description covers the key aspects: tool family, exact behavior similarity to ask_pipeworx, current experimental state, and usage guidance. It fully contextualizes the tool for an agent deciding whether to invoke it, including safety profile (via annotations) and routing-specific details.

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

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

The input schema is fully documented with 100% coverage, listing all six parameters as aliases for 'question' with descriptions. The description mentions 'same arguments' as ask_pipeworx, but this adds little beyond the schema. Since schema coverage is high, a baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,305 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements. This is a specific verb+resource+scope that separates it from siblings.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that it is not a fallback ('Falls back to nothing') but a full working router, and notes that results are compared against the stable router. This provides clear context and differentiates its usage from ask_pipeworx.

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

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

The description goes well beyond the annotations by disclosing the extra LLM call cost, the explicit refusal mechanism with specific refusal reasons, and the constraint that answers are extracted only from tool results (no invention). This provides richer behavioral context than the readOnly/openWorld/idempotent hints alone, without contradicting them.

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

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

The description is front-loaded with the core purpose, then quickly covers execution model, return format, usage guidance, and cost tradeoff. Every sentence earns its place with no fluff or repetition. It is dense but highly readable.

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 fully specifies the success return shape (answer, evidence, confidence, source, etc.) and the refusal shape with enumerated refusal reasons. It also covers operational context (cost, relationship to sibling tool, high-stakes use cases), making it complete for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% and the schema already describes all aliases. The description adds meaning by explaining that the question is used for routing across 5,305 tools and filling arguments, implying the parameter is a high-level natural-language query whose semantics are resolved by the system, not a direct argument. This is useful beyond the schema's literal description.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts') and resource (the Pipeworx tool network). It explicitly differentiates from sibling ask_pipeworx by emphasizing grounded extraction and refusal behavior, which is critical given the sibling list includes ask_pipeworx and ask_pipeworx_beta.

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

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

The description provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and explains the cost tradeoff, giving the agent clear selection criteria.

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?

The description richly discloses behaviors beyond the annotations: account requirements, time expectations (15-60s, up to ~90s for thorough), return packet contents (verbatim evidence, confidence, source, fetched_at, stable citations), explicit gaps[] to avoid invented answers, contradiction scanning, semantic excerpting, and hop/citation_uri fields. No contradictions with the readOnly/openWorld/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 unusually long for a tool, but every sentence packs essential information: account prerequisites, alternatives, mode of operation, examples, output structure, timing, and limitations. It is front-loaded with the critical sign-in warning and remains structured and scannable despite its length.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: findings packet, gaps[], contradictions[], hop field, citation_uri, and semantic excerpting. It also covers operational context like latency and account tiers. The description is complete for a tool of this complexity.

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

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

Schema coverage is 100% and the schema already thoroughly explains both parameters, including depth values (quick/standard/thorough) and their facet counts, gap recovery, and contradiction scans. The description reinforces this but adds little beyond the schema; it does clarify that 'question' can be broad/multi-part and decomposition is the point, but that is already in the schema's question 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 performs 'grounded multi-source research across Pipeworx's 1391 STRUCTURED data sources' in one call, decomposing questions into facets and routing them in parallel. It distinguishes itself from siblings like ask_pipeworx by emphasizing this is not open-web search and is best for broad/multi-part questions over structured 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?

Explicit guidance is given on when to use deep_research (broad/multi-part questions over structured data) versus when to use ask_pipeworx (single lookups, breaking/current news, or when not signed in). It also notes the account requirement and paid tier for 'thorough' depth, leaving no ambiguity about 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, 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?

Description adds behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and impact on roadmap. No contradictions with annotations.

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

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

Description is concise (4-5 sentences), well-structured front-loading purpose and then adding usage guidelines and behavioral notes. No wasted words.

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

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

For a simple feedback tool, the description covers purpose, usage, constraints, and behavioral impact. No output schema but not needed for this tool; agent can infer success from typical feedback API. A note on return value would be slight improvement.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context on how to write the message (describe in terms of tools/packs, don't paste user prompt), which adds value beyond schema.

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

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

The description clearly states the tool's purpose: sending feedback about Pipeworx tools (bugs, features, data_gaps, praise). It distinguishes from sibling tools like ask_pipeworx which are for queries, not feedback.

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 (bug, feature/data_gap, praise) and what not to do (do not paste end-user prompt). Also mentions rate limit and quota, giving clear usage boundaries.

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?

Annotations already indicate readOnly=True and idempotent=True, so the description's claim about internal cascading (replacing 2-3 manual lookups) adds useful context beyond the annotations. It does not contradict annotations, and it helps set expectations about internal complexity.

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

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

The description is well-structured, starting with examples, then core purpose, then type-specific details. It is front-loaded with actionable guidance. While dense, every sentence adds value. Slightly verbose in places (e.g., repeating company details), but overall efficient.

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

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

Given lack of output schema, the description adequately explains return fields (ticker, CIK, company_name, citation for company; RxCUI, ingredient, brand, citation for drug). It also clarifies input flexibility. It could briefly mention response format (object vs string) but is otherwise complete for this tool's complexity.

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

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

With 100% schema description coverage, the baseline is 3. The description significantly enriches both parameters: for 'type' it lists supported values and what each returns; for 'value' it provides concrete examples (ticker, CIK, company name; brand/generic) and mentions auto-disambiguation. This adds meaning beyond the bare 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 defines the tool's purpose: resolving names to canonical IDs. It starts with example queries, explicitly states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input', and lists supported types with detailed outputs. This distinguishes it from sibling tools like entity_profile or compare_entities.

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

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

The description provides a strong usage guideline: 'Use FIRST whenever you have a name but need an ID.' It implicitly suggests this tool is a prerequisite for other tools that require IDs. However, it does not explicitly mention when not to use it or alternative tools for different contexts.

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?

Annotations provide readOnlyHint, openWorldHint, idempotentHint all true. Description adds significant detail: explains the internal routing logic, that it returns verdicts, actual values with citations, and reasoning. No contradiction with annotations.

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

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

The description is thorough but slightly verbose, listing example query phrases. However, it's well-organized with clear sections and front-loaded with the tool's purpose. Could be trimmed without losing meaning.

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

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

For a tool with 2 parameters and no output schema, the description fully explains the return values (verdict, actual value, citation, reasoning) and the two internal paths. Covers all essential information 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% with clear descriptions. The description adds value by explaining tolerance_pct overrides implied wording and default cap (5%), and gives natural-language examples for the 'claim' 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 provides specific verbs ('validate', 'fact check', 'verify') and resources ('natural-language claim verification against authoritative sources'). It distinguishes between two verification pipelines (SEC EDGAR vs grounded pipeline) and clearly separates from sibling tools by noting it replaces multiple sequential calls.

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

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

Explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' Also describes the two sub-use cases (company-financial vs other claims). No explicit when-not-to-use, but context is clear enough.

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