Defillama

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

Annotations already declare safety (readOnlyHint, idempotent, non-destructive). The description adds transparency about external API calls to Anthropic when providing an API key, and notes that the default model is free. This adequately discloses behavioral traits 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 three sentences, front-loaded with the core purpose, followed by essential details (default, key usage, output structure). Every sentence adds unique value with no 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?

Despite no output schema, the description outlines the return shape (per-model object with score, confidence, signals, raw_response plus combined view). For a probe tool with 4 parameters and these annotations, this covers the necessary context for an agent to use it correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining default model behavior, when the API key is needed, and that context helps disambiguate entities. This exceeds merely restating schema fields.

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

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

The description uses specific verbs ('probe', 'score') and clearly identifies the resource ('LLMs for what they know about a business/brand/product/topic') and output ('score visibility 0-100'). It distinguishes from siblings by focusing on AI visibility scoring, which is unique among the listed 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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use different models. It does not explicitly contrast with sibling tools, but the use cases are specific enough to guide 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=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining the routing behavior (5,462 tools, fills arguments), the stable pipeworx:// citation URIs, and the 'one fast call' performance trait. It doesn't disclose latency bounds or rate limits, but with strong annotations and added context, a 4 is appropriate.

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 and front-loaded with the most important directive ('PREFER OVER WEB SEARCH'), followed by domain list, examples, and alternatives. Every sentence contributes a distinct piece of guidance—no redundancy. At ~150 words, it's appropriately sized for the breadth of use cases it covers.

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 6-param, 1-required tool with no output schema and rich annotations, the description fully covers purpose, usage, examples, and alternative tools. It even mentions return value characteristics (structured answer with citations), which exceeds what is required. No gaps are apparent.

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

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

Schema description coverage is 100% (all 6 params are clearly documented as aliases for the 'question' string). The description itself adds little param meaning beyond the schema, though it does provide example questions that illustrate expected input. Baseline 3 is correct when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: answering natural language questions about current/historical data across domains like SEC filings, FDA, FRED, etc., routing to 5,462 tools, and returning structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying when each should be used.

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

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

The description explicitly says to prefer this over web search for factual questions, calls it the 'default entry point' and 'START HERE', and gives specific 'step up only when needed' guidance for ask_pipeworx_grounded (hallucination-resistant single answer with verbatim evidence) and deep_research (broad/multi-part). It also clarifies that breaking-news questions are handled internally. This is explicit when/when-not guidance.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable context about the experimental nature, live candidate routing improvements, and the fact that it is a working router with no fallback. 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 concise and front-loaded with purpose, then explains current status and usage. Each sentence adds distinct information, though it could be slightly tighter given the detail about candidate retirement dates.

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, the description explains its beta status, current behavior, and relationship to ask_pipeworx. Although no output schema exists, referencing 'same response shape' as the stable sibling is sufficient. It provides a complete picture for an experimental router.

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

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

The input schema covers all 6 parameters with descriptions, including the main 'question' field and its aliases. The description only says 'same arguments' without adding further parameter-specific meaning, so it relies on the schema's 100% coverage.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements.

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

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

Explicitly tells the user to use it exactly like ask_pipeworx when they want the newest routing, and notes that results are compared against the stable router. It also clarifies that with no active candidate, it currently matches ask_pipeworx exactly.

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

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

The description goes well beyond the readOnly/idempotent annotations by disclosing the closed-world extraction guarantee, exact refusal conditions with specific reasons, and the return payload structure. It also notes the extra LLM call cost. No contradiction with any annotation is present.

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

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

The description is information-dense yet well-structured, front-loading the core purpose and differentiator. Every sentence serves a distinct role: purpose, method, return format, refusal conditions, usage guidance, and trade-off. There is no redundant or filler 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?

Given the complexity of routing across 5,462 tools and the absence of an output schema, the description fully compensates by detailing the return fields, refusal reasons, and appropriate use cases. It also contrasts with siblings and explains the cost implication, making it a complete guide for 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 all parameters documented as aliases for the natural-language question, so the baseline is 3. The description adds no new parameter-specific details beyond the schema, but it does mention that the tool fills arguments for the underlying routed tool, which is a minor contextual addition.

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

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

The description clearly identifies this as a hallucination-resistant answer mode that extracts answers strictly from tool results, distinguishing it from the sibling ask_pipeworx by its grounded, evidence-based behavior. The verb 'extracts' and resource 'answer mode' are specific, and the scope is precise.

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

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

Explicit usage guidance is provided: use for high-stakes, quotable, or actionable answers where invention is unacceptable, and prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This directly addresses when to use vs. alternatives, including a clear trade-off.

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 read-only, idempotent, non-destructive. The description adds extensive behavioral context: resolution process, classifiers, fan-out examples, response shapes, safety (low-confidence short-circuit), and cancellation rules. No contradictions; it complements annotations well.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). Each sentence adds value; nearly no fluff. Could be slightly more concise but remains 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?

Despite no output schema, the description thoroughly covers return shapes, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and internal mechanisms (fallback for GDELT 429). Very complete for a 3-parameter, no-output-schema 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%. The description adds meaning beyond schema: explains market parameter accepts slug/URL/text, depth defaults to thorough, include_raw default false with use cases. This significantly 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: research Polymarket bets by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + comparison). This verb+resource combination is specific and distinguishes it from sibling tools like polymarket_edges.

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

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

The description explicitly says to use for 'should I bet on X', etc., and provides detailed guidance on interpreting results (e.g., check market_match_confidence). However, it does not explicitly state when not to use or directly contrast with siblings, though context implies its role.

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 the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: for companies, it pulls LATEST 10-K data from SEC EDGAR with correct handling of off-calendar fiscal years; for drugs, it pulls FAERS data. It also mentions sorting by primary metric and returning citation URIs. This goes well beyond the annotations, though it does not cover potential limitations like data freshness or rate limits.

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

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

Despite covering many details, the description is concise (about 150 words) and front-loaded with the most important information (trigger phrases and when to prefer it). Every sentence adds value without redundancy, achieving high information density.

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 financial metrics, and citation output—the description is remarkably complete. It covers what data is fetched, how results are sorted, and the output format (paired data + URIs). There is no output schema, but the description adequately prepares the agent for what to expect.

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 has 100% description coverage, but the description enriches it significantly: it explains exactly what data is retrieved for each type (revenue, net income, cash, debt for companies; adverse events, approval counts, trials for drugs), and clarifies that values should be tickers/CIKs for company and drug names, with an explicit 2-5 range. This adds substantial meaning beyond the schema.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs, using specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from sibling tools like entity_profile by emphasizing it replaces multiple sequential lookups, making its purpose unmistakable.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear guidance on when to use it. It also lists trigger phrases such as 'compare X and Y', 'X vs Y', 'which is bigger', and 'rank these companies', making usage context very clear.

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

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

The description adds rich behavioral context beyond the readOnly/openWorld/idempotent hints: account requirement, parallel tool routing, response structure (verbatim evidence, confidence, source, fetched_at), explicit gaps[] never-invented behavior, second-hop iteration for standard/thorough, contradictions[] scanning, and semantic excerpting of large records. This fully informs the agent of the tool's operational traits 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 long but densely packed with unique, actionable details. Each sentence contributes distinct information (account, alternatives, behavior, depth semantics, citation reliability, excerpting, latency). Slight deduction for the unwieldy parenthetical-heavy structure which could be better segmented, but is generally well-organized and front-loaded.

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

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

Given no output schema, the description fully explains return behavior: findings packet with verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], hop field, and citation_uri resolvability. It also covers edge cases (breaking news yields mostly empty gaps, large records excerpted semantically) making the tool's behavior fully predictable 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%, but the description materially enhances parameter understanding: it elaborates depth values with facet counts ('quick=3, standard=5... thorough=8'), the gap-recovery hop, contradictions scan, and mentions that question accepts broad/multi-part queries. This exceeds the schema's minimal descriptions, adding real semantic 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 uses a specific verb+resource combination: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call'. It clearly differentiates from siblings by naming ask_pipeworx for single lookups and breaking news, setting deep_research apart as the structured multi-facet research tool.

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

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

Explicit guidance is given: 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. The description also covers account requirements, depth selection guidance, and expected latency, making it clear when this tool is appropriate versus 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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's additional context (returns TVL per chain, purpose) is useful but not critical. No contradictory statements. The description adds moderate value beyond annotations by clarifying output granularity.

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

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

The description is two sentences, front-loading the core action ('Compare total value locked') and adding purpose ('to identify where capital is concentrated'). Every word earns its place; no fluff or repetition.

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

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

Given zero parameters and an output schema likely defining return values, the description is complete for this tool. It explains the tool's functionality and utility without requiring additional 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?

The tool has zero parameters, and schema description coverage is 100% (empty schema). Baseline score of 4 applies because no parameter documentation is needed. The description implicitly confirms no input is required, which matches the schema.

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

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

Description clearly states the tool compares total value locked across all blockchains and returns TVL per chain to identify capital concentration. Verb 'compare' and resource 'total value locked across blockchains' are specific, and the tool is distinct from siblings like defi_protocol_detail (focuses on protocols) or defi_tvl_protocols (aggregates protocol-level TVL).

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

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

The description implies usage for comparing chain-level TVL and identifying capital concentration, but does not explicitly state when to use this tool versus alternatives (e.g., defi_protocol_detail for protocol-level data). No exclusions or prerequisites are mentioned, leaving some ambiguity for an AI agent choosing among sibling tools.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already indicate safety. The description adds behavioral context by specifying the returned data categories (TVL history, blockchain breakdown, token info), which 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?

Single sentence, no extraneous words, front-loads the main purpose. 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?

With an output schema present, the description does not need to explain return values. The description covers all relevant aspects: it's a single-protocol query returning specific data types. No gaps given the tool's simplicity.

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% (1 parameter with example values). The description does not add further details about the 'protocol' parameter, relying solely on the schema description. No additional semantics provided.

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

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

The description uses a specific verb ('Get') and resource ('detailed metrics for a specific DeFi protocol'), and lists concrete data types (TVL history, breakdown by blockchain, token information). This clearly distinguishes it from siblings like defi_tvl_protocols or defi_protocol_fees.

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

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

The description explicitly states the tool is for a single protocol and shows examples like 'aave', 'uniswap'. While it doesn't explicitly state when not to use, the sibling context suggests alternatives for chain-level or fee-focused queries. Could include an exclusion for multi-protocol comparison.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns fee trends for profitability analysis, which is useful behavioral context beyond annotations.

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

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

Two succinct sentences, front-loaded with the core action ('Check daily fees and revenue'), with no unnecessary words.

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

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

Given the tool's low complexity (2 parameters, rich output schema), the description is fully adequate. Annotations and schema cover the rest.

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 parameters are well-documented in the schema. The description repeats the purpose ('fees and revenue') but does not add new parameter-level details.

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

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

The description uses specific verbs ('Check daily fees and revenue') and a resource ('DeFi protocol'), clearly distinguishing it from sibling tools like defi_chain_tvl or defi_yields.

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

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

No guidance on when to use this tool versus alternatives (e.g., defi_protocol_detail, defi_yields). The agent is left to infer context from the tool name alone.

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. Description adds context about returning supply per chain for tracking adoption, which is consistent but not deeply informative. No contradiction.

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

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

Two concise sentences with no redundancy. Front-loads the key action and result.

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 parameterless tool with an output schema, the description fully explains what it does and what it returns. No gaps.

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

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

No parameters in schema; schema coverage 100%. Description adds no parameter info but does not need to. Baseline 4 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?

Explicitly states it retrieves stablecoin market cap and distribution across blockchains, with a clear verb 'Get' and resource. Differentiates from sibling tools focused on TVL or specific protocols.

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

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

No guidance on when to use this tool versus alternatives (e.g., defi_chain_tvl for general TVL). Does not specify use cases or exclusion 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 mark as read-only, idempotent, etc. Description adds return fields (name, TVL, blockchain, category) and implies non-destructive search. No contradictions, but missing details like data freshness or pagination.

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

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

Two concise sentences, front-loaded with purpose and output. No filler or redundancy.

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

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

With optional params, rich annotations, and an output schema, the description covers core functionality. Could mention result limits or ordering, but overall sufficient for a straightforward search 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 already fully describes both parameters (substring match for search, category examples). Description only restates 'by name or category', adding no new semantics. Baseline 3 due to high schema coverage.

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

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

Description uses specific verb 'Search' with clear resource 'DeFi protocols' and purpose 'to compare total value locked'. Lists returned fields. Distinct from siblings like defi_chain_tvl (by chain) and defi_protocol_detail (single protocol).

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 clearly implies usage: search by name or category for TVL comparison. No explicit when-not or alternatives, but context is sufficient for an agent to infer appropriate use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows the tool is safe and non-destructive. The description adds that it returns APY, TVL, and project details, but does not disclose additional behavior like data freshness or pagination. With annotations covering the core traits, the description adds minimal extra value.

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

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

The description is two sentences, front-loaded with the action, and contains no extraneous words. Every sentence serves a clear 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?

Given the tool's simplicity (3 optional parameters, output schema present), the description covers the essentials. It could mention that all parameters are optional, but that is inferable from schema. The description is complete enough for a look-up 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 description coverage is 100% with each parameter having a clear description. The tool description rephrases the filtering concepts but adds no new semantic information beyond the schema. 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 verb 'find' and the resource 'yield opportunities across DeFi pools'. It specifies filter criteria (project name, minimum TVL, minimum APY) and what is returned (APY, TVL, project details). This distinguishes it from sibling tools like defi_chain_tvl or defi_protocol_fees.

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

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

The description implies usage for finding yields with filters, but does not explicitly state when to use this tool vs alternatives. Among siblings, there are other DeFi tools, but no guidance is provided. The context is implied but not explicit.

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?

Gives valuable behavioral context beyond annotations: returns top-N relevant tools with full schemas ready to call, no second lookup. Annotations (readOnlyHint, idempotentHint) are consistent and description adds detail.

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

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

Description is packed with useful information but longer than necessary; however, it is front-loaded with the core purpose and well-structured. 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?

Completely describes the tool's role, return format (top-N tools with schemas), and workflow context. No output schema, but description compensates fully.

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

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

Input schema provides 100% coverage with full descriptions for all 6 parameters. Description restates that query accepts aliases but adds no new semantic meaning beyond the schema.

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

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

Description clearly states it finds tools by describing data/task, lists example domains, and differentiates as a discovery tool from siblings. The verb 'Find' and resource 'tools' is specific.

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

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

Explicitly advises to call this FIRST when many tools are available and you want the option set. Lacks explicit 'when not to use' alternatives, but context is clear.

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

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

Describes multi-source fan-out behavior (SEC, XBRL, USPTO, news, GLEIF), including that patent data soft-fails due to USPTO API sunset and uses GDELT→GNews fallback. Annotations already indicate readOnly, openWorld, idempotent, non-destructive, and description adds these operational details without contradiction.

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

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

The description packs substantial information in a single paragraph but front-loads example queries for rapid understanding. Could be more structured (e.g., bullet points), but every sentence earns its place. Nearly optimal for the content density.

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?

Excellent coverage given no output schema: describes return fields (cik, recent_filings with URIs, fundamentals with sorting, patents, news, LEI), notes limitations (US public companies only, names unsupported, patent soft-fail), and explains fallback behavior. Fully equips the agent to use the tool correctly.

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

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

Schema already provides 100% coverage with descriptions for both parameters. The description adds value by clarifying that value can be ticker or zero-padded CIK (not names) and recommending resolve_entity for names, which aids agent understanding beyond schema constraints.

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 holistic cross-source profile of US public companies, with example queries. It specifies the returned data (CIK, filings, fundamentals, patents, news, LEI). This distinguishes it from sibling tools like deep_research (broader) or resolve_entity (name resolution only).

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 instructs to use resolve_entity if only a name is available, providing clear when-to and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true and readOnlyHint=false. Description adds 'sensitive data' context but no additional behavioral details (e.g., idempotency, missing key behavior). No contradiction.

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

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

Two sentences with no wasted words. First sentence states core action, second provides usage context.

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

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

For a simple tool with one parameter, clear annotations, and no output schema, the description covers purpose, usage, and when to use. Complete for the complexity level.

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

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

Schema coverage is 100% with parameter description 'Memory key to delete.' Description repeats this without adding new semantic information. Baseline 3 applies.

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 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes itself from siblings by naming them explicitly.

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 (stale context, task done, clear sensitive data) and suggests pairing with remember and recall. Lacks explicit when-not but context is clear.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description confirms fetching, extracting, and emitting markdown, adding context on output format and standard. No contradictions; adequate disclosure.

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 efficient sentences: purpose, process, use cases. No fluff, front-loaded with key information. Every sentence serves a 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?

Describes output as a single text blob in standard llms.txt format. Lacks details on error handling or fetch failures, but sufficient for a simple tool with good annotations.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds minimal new meaning (e.g., 'site-root/llms.txt' hint) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool generates an llms.txt file for any URL, using specific verbs like 'generate', 'fetches', 'extracts', 'emits'. The tool's purpose is distinct from siblings, no ambiguity.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitors. It provides clear context but does not mention when not to use or alternatives.

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

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

Annotations provide read-only, idempotent, non-destructive hints. Description adds that it returns specific fields and that it only returns active by default. No contradiction.

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

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

Two sentences: first states purpose, second gives usage guidance and return fields. Minimal waste, front-loaded.

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

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

No output schema but description lists return fields. Covers the single parameter and usage context. Complete for a simple list tool.

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

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

Schema coverage is 100% with one parameter fully described. Description does not add meaning beyond the schema for the 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?

Clear verb ('List') and resource ('subscriptions') with scope ('caller's active'). Distinguishes from siblings like subscribe/unsubscribe.

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

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

States when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Implies not for adding/cancelling but no explicit when-not or 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?

Adds significant behavioral context beyond annotations: 'Rate-limited to 5 per identifier per day', 'Free; doesn't count against your tool-call quota', and describes the team's off-cycle review process ('reads digests daily'). It also warns against pasting end-user prompts, which is a useful operational 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?

Every sentence earns its place: lead sentence explains purpose, then usage triggers, an exclusion, and critical tips (not pasting prompts, rate limits, quota). Dense but not bloated, and the most critical information is front-loaded.

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

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

For a simple 3-parameter feedback tool with no output schema, the description covers purpose, scope, constraints, rate limits, and content guidelines. No other critical aspects (e.g., return value) are needed for the user to successfully 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?

The 100% schema coverage already documents all parameters, so baseline is 3. The description adds extra guidance on how to craft the message (e.g., 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which gives practical semantics for the 'message' and 'context' parameters 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 begins with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which uses a specific verb and resource, immediately clarifying the tool's purpose. It clearly distinguishes itself from sibling research and AI tools by focusing on feedback submission.

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

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

Explicitly states when to use: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives an exclusion: do not use for tools from other MCP servers, and directs users to file with the appropriate server, providing clear 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds valuable context: self-aggregating, no PII, cached (5min-1h), and derived from CF analytics-engine. It does not contradict annotations.

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

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

The description is four sentences, efficient, and front-loaded with the core functionality. It earns its place by providing multiple use cases and behavioral notes. 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, the description explains return values (top tools, top packs, total call volume) and caching behavior. It is complete for a simple trending tool, though explicit mention of response format would improve completeness.

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

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

Schema coverage is 100% with description for the 'window' parameter. The description adds extra semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand', enriching the agent's understanding beyond the enum values.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' over a window, with specific use cases listed. It distinguishes from siblings by focusing on trending data, not search or retrieval.

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

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

The description provides three explicit use cases ('discovering what data sources are hot', 'confirming a popular tool', 'seeing whether your use case aligns'), offering clear context for when to use the tool. However, it does not explicitly state when not to use it or mention alternatives among siblings.

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

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

Annotations indicate safe, read-only, idempotent behavior. The description adds critical behavioral context: details of each mode, partition checks, Jaccard similarity threshold, placeholder filters, and fill check logic with trading advice. 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 clear sections and front-loaded purpose. It is relatively long but each sentence adds value, covering modes, filters, and edge cases. Slightly dense but 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?

No output schema, but the description explains the response structure (opportunities[], partition_check, fill_check) with key fields. Covers all important aspects: modes, filtering, edge cases, and trading guidance. Complete for a complex tool.

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

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

Schema coverage is 100% with both parameters described. The description greatly enriches meaning: explains event and topic modes with examples, describes what each returns, and provides context like semantic anchor and partition filter that goes beyond schema descriptions.

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

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

The description specifies it finds arbitrage on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) and differentiates from siblings like polymarket_fill_risk by noting that fill_check prices against live CLOB depth and directing to the sibling for custom sizing.

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: call with NO args for trending scan; recommend event mode for specific markets with examples; use topic for cross-event scanning. It also explains when not to trade (when realizable_edge_pp ≤ 0) and refers to polymarket_fill_risk for custom sizing, giving clear alternatives.

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

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

The description extensively discloses behavioral traits beyond annotations. It explains the five model families, caching strategy (1h at KV level), response structure (by_segment with diagnostics), and details on edge computation (net of slippage, Kelly fractions). It also notes that Fed bets are excluded from ranking, providing rich context for the agent.

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 and has a logical structure. However, it is quite long and dense with technical jargon and nested parentheses, which could be more concise. It earns points for being comprehensive but loses some for verbosity.

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

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

Given the complexity (9 parameters, no output schema), the description is exceptionally complete. It explains the response structure, diagnostics, caching, and Fed note. Without an output schema, it compensates fully by describing what the agent can expect, making the tool safe 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 description coverage is 100%, so the baseline is 3. The main description adds marginal value by grouping parameters into tradeable-edge knobs and explaining their interplay, but the schema descriptions are already thorough. No additional meaning beyond what the schema provides.

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

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

The description clearly states the tool's function: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets) and action (scanning and returning opportunities), and distinguishes it from siblings like polymarket_arbitrage by focusing on edge detection 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?

The description provides context for when to use the tool, e.g., 'what should I bet on today' and how it avoids paging through hundreds of markets. It implies alternatives (other Polymarket tools) but does not explicitly state when not to use it. The detailed explanation of parameters like tradeable-edge knobs gives implicit guidance.

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

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

The description extensively explains the tool's behavior, including the structure of the response (tracked[], expired[], snapshot_dates[]), meaning of fields (trend, decay_pp_per_day, lifespan_days, negative values), and limitations (history depth, decay computed from daily closes). This adds significant value beyond the annotations (readOnlyHint, etc.) and fully informs the agent.

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 a clear purpose, then detailing response fields, and ending with limitations. It is somewhat verbose but every sentence adds value, especially given the lack of an output schema. Could be slightly more concise, 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 the complexity of the tool (tracking edge persistence over time), the description covers all critical aspects: current edges, expired edges, snapshot dates, trend and decay computation, limitations. Without an output schema, the description fully compensates by explaining the return structure and semantics, making it complete for an agent to understand and invoke correctly.

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

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

The schema covers both parameters with clear descriptions. The description repeats the defaults and adds clamp details ('days' clamp 2-30) but does not substantially enhance agent understanding beyond the schema. With 100% schema coverage, the baseline is 3; the description provides marginal extra 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 explicitly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes this tool from siblings like polymarket_edges by focusing on historical telemetry rather than raw current data.

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

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

The description provides guidance on when to use the tool (e.g., to assess edge persistence, compare with competition clock via median lifespan) and includes important LIMITS (history bounded by 60-day TTL, daily closes). It does not explicitly contrast with alternative tools, but the context from siblings and the purpose make the appropriate use case clear.

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

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

Annotations declare readOnlyHint and idempotentHint, which the description supports by describing a check operation. Beyond annotations, the description details behavioral traits: walking the ladder, returning fields like slippage, shares filled, and verdicts, and warns about partial basket fills converting arbs into unhedged directional positions. No contradictions.

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

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

The description is dense but efficiently structured: single-market and basket modes are clearly separated, return values are enumerated, and the mandatory usage note is front-loaded. Every sentence adds unique value, and the description is front-loaded with the key 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?

Given the tool's complexity (two modes, multiple return values, and no output schema), the description fully covers expected behavior, return fields, risks, and when to use it. It leaves no critical gaps for an AI agent to misunderstand.

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

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

All 4 parameters are described in the input schema (100% coverage), and the description adds significant context: explains how size_usd is interpreted differently per mode, side defaults, and the requirement that one of market or event must be provided. 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 starts with 'Realizable-vs-theoretical edge check against live CLOB order-book depth,' clearly stating the tool's purpose. It distinguishes between single-market and basket modes, and the use case is specific enough to differentiate it from 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?

The description explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' providing clear when-to-use guidance and reasoning (theoretical overround not capturable on thin books, partial basket fills causing unhedged positions). This fully addresses usage guidelines.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds extensive behavioral details: compatibility_warning conditions, temporal alignment, skipped cross types, and response structure, far exceeding what annotations provide.

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

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

Description is well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and every sentence adds value. Slightly verbose but justified given complexity; no filler.

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

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

No output schema, but description thoroughly explains response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal alignment). Covers all necessary context for an agent to understand inputs and outputs.

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. Description adds further context: lists all topic shortcuts, explains override behavior, and clarifies that explicit tickers override topic mapping. This enriches understanding beyond schema.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket, specifies two modes (topic and explicit), and describes output. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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 topic mode vs explicit tickers, and warns that most pre-mapped topics return compatibility warnings, guiding against misuse. Provides clear context for when the tool is appropriate.

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 and idempotent. Description adds valuable context: scoping by identifier, safe retrieval, and pairing with other tools. 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?

Every sentence adds value: action, examples, scoping, tool pairing. Front-loaded and efficient, no superfluous 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?

Covers key aspects: retrieval, listing, scoping, pairing. Lacks details on return format and behavior when key is missing, but acceptable given simple parameter set and annotations.

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

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

Schema coverage is 100% with clear parameter description. The description repeats the same info (omit key to list) and adds no new syntactic 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?

Description clearly states the tool retrieves a value by key or lists all keys if omitted, with concrete examples (ticker, address, research notes). It explicitly distinguishes from remember and forget.

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?

Describes when to use (look up stored context) and offers clear instruction on key omission for listing. Mentions pairing with remember and forget, but lacks explicit 'when not to use' or alternatives among siblings.

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

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

Beyond annotations (readOnly, idempotent), the description explains the return fields, filtering, and the mark_read side effect (marks events as read). This adds behavioral context for subsequent calls.

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 and front-loaded: first sentence defines purpose, then details content, filters, mark_read behavior, and alternative access. 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 return fields, filtering, mark_read behavior, and alternative access. No output schema but description compensates. Could mention ordering (most recent) but overall complete for a read-only feed 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% (all 5 parameters documented). The description adds little beyond schema for parameters, reiterating type, since, and mark_read. It does add output context but not parameter semantics.

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

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

The description clearly states 'Pull fired events from your subscription feed.' This specific verb-resource pair distinguishes it from siblings like list_subscriptions, which lists subscriptions themselves.

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

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

No explicit when-to-use or when-not-to-use guidance. It mentions an alternative access method (GET endpoint) but not alternative tools. Usage is implied but not differentiated from related tools like list_subscriptions.

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

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

Beyond annotations (readOnly, idempotent, openWorld), the description reveals multi-source fan-out, fallback logic (GDELT→GNews), and a soft-fail condition (USPTO PatentsView sunset). It also describes the return structure (changes[], total_changes, 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, well-structured paragraph that front-loads example queries and efficiently covers purpose, sources, parameters, and alternative tool. No redundant or unnecessary sentences.

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 adequately covers return structure and key behaviors (source fallback, soft-fail). However, it omits details on pagination, maximum result count, or potential timeouts, which would be helpful for a data-fetching tool. Annotations somewhat compensate (openWorldHint implies no strict 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 clear descriptions for all three parameters. The description adds value by explaining the 'since' parameter's dual date formats and the purpose of 'type' and 'value' in context. Slight deduction because schema already does most of the work.

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 within a time window, aggregating from multiple sources (SEC, GDELT/GNews, USPTO). It distinguishes itself from the sibling entity_profile by stating when to use the latter instead.

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 offers explicit guidance: example queries ("What's new with X"), supported date formats (ISO or relative), source fallback behavior, and a direct reference to entity_profile for static profile needs.

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

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

Annotations already provide readOnlyHint=false, destructiveHint=false, idempotentHint=true. Description adds scoping by identifier, persistent vs. 24-hour retention, and storage format. 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?

Five sentences, each adding value: purpose, usage, scoping, retention, pairing. No wasted words, well-structured and front-loaded.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, when to use, behavioral details, and pairing. Complete for an agent to use correctly.

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

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

Schema coverage is 100% with good descriptions. The description reinforces by providing naming conventions (e.g., 'subject_property') and clarifying value as any text, adding marginal 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: 'Save data the agent will need to reuse later' with specific examples (ticker, address, preference). It distinguishes from siblings by mentioning recall and forget as partner tools.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward.' Provides context (across conversations/sessions) but lacks explicit 'when not to use' guidance.

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

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

The description adds substantial behavioral context beyond the annotations: it mentions auto-disambiguation, internal cascading through multiple lookup endpoints, and citation URIs. These details inform the agent about complexity and output specifics that the annotations do not cover.

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: example queries up front, a clear purpose statement, and a concise breakdown of supported types. Every sentence is informative and necessary, avoiding redundancy while covering essential details.

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

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

Given the absence of an output schema, the description fully covers return values for both entity types, input variants, and the internal cascading behavior. It provides sufficient context for accurate tool invocation in all supported cases.

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

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

Despite 100% schema coverage, the description enriches parameter meaning with concrete examples (AAPL, CIK format, 'ozempic'), input flexibility, and exact per-type outputs. This adds significant value over the bare schema and justifies a top score.

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 resolves user-spoken names to canonical/official identifiers, with specific example queries and two supported types (company, drug). It distinguishes itself by serving as the first step when an ID is needed, though it does not explicitly name sibling alternatives.

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 a strong directive ('Use FIRST whenever you have a name but need an ID') and explains supported types and their outputs. However, it lacks explicit when-not-to-use guidance or direct comparisons to alternative tools, which would warrant a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructive hint. The description adds behavioral detail: it probes each entity with ai_visibility_check, ranks results, and returns a ranked list with score, confidence, and signal density. 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 three sentences, front-loaded with the core purpose, then method, then use-case, then output. Every sentence adds value, no redundancy. Highly concise 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 the tool's complexity (4 params, no output schema, but uses an internal sub-tool), the description covers what it does, how it works, what it returns, and when to use. The output is described sufficiently for the agent to understand the result format.

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 all parameters are documented. The description adds important nuance: the first entity is treated as the 'subject' for narrative, which is not in the schema. This aids correct invocation.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score, and identifying most/least recognized. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying the internal probing mechanism and competitive audit use case.

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-case context ('competitive AI-marketing audits') with a concrete example. While it does not explicitly list when not to use or alternatives, the sibling context implies a single-entity check would use ai_visibility_check instead. This is clear enough for an AI 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?

Beyond annotations (readOnly, openWorld, idempotent), description adds that it fans out to two services, bundlephobia first measurement may take 5-30s, and partial failures degrade gracefully with sources_failed reported. 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 moderately long but every sentence serves a purpose. Front-loaded with core function. Could be slightly more concise, but no extraneous 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 and tool complexity (composite multi-service check), description fully explains what returns: summary block, per-advisory detail, links, recent alternatives. Also covers error handling and timing.

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

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

Schema coverage is 100% but description adds value: scoped packages accepted, version defaults to latest if omitted, and explicitly lists what each parameter does in the context of the tool.

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 it's a composite check for npm package evaluation combining deps.dev and bundlephobia data. Distinguishes from siblings by specifying npm-only scope and alternative tools for other ecosystems.

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 (agent asks about safety, popularity, size; cost of adding a package) and when not (PyPI/Maven/Cargo/Go use deps.dev:version directly). Also notes partial failure behavior.

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, idempotentHint=true, destructiveHint=false. The description adds substantial behavioral context: embedding model (BGE-base-en), similarity cosine, 500-char overlapping windows, 200K char cap with truncation and flagging, and character offsets for verification. 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 three sentences long, which is appropriate for the detail provided. It front-loads the primary action and then elaborates. Every sentence adds meaningful information, though a slight trim could improve conciseness.

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

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

Despite no output schema, the description fully explains return values (top-N passages with offsets and similarity scores). It covers input limits (200K chars), embedding details, and pairing with other tools. For a tool with three parameters, this is highly 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 description coverage is 100% (all three parameters have descriptions). The description adds extra context for 'text' (max ~200K chars) and 'query' (natural-language examples), enhancing understanding beyond the schema. However, since baseline is 3 due to high coverage, the added value warrants a 4.

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

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

Description clearly states the tool performs semantic search inside a fetched record, provides a concrete example (SEC 10-K), and distinguishes from siblings like ask_pipeworx_grounded. The verb 'search' plus resource 'within a source' 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 ('record is too big to cram into the prompt') and mentions a sibling tool (ask_pipeworx_grounded) as a pairing alternative. It also explains the benefit: saves context and returns 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 indicate readOnlyHint=false (mutation), idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds valuable context: returns subscription id, requires OAuth, always-on feed, optional channels with constraints (SMS cap, webhook auto-disable), and one-time webhook secret. 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 information-dense but well-structured: begins with main purpose, then lists types with examples, then delivery channels with constraints. Every sentence adds value; there is no redundancy or fluff.

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

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

Given no output schema, the description still explains the return value (subscription id). It covers prerequisites, all parameter details, delivery options, and behavioral nuances (webhook auto-disable, SMS cap). This is sufficient for an AI agent to correctly 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 goes beyond schema by providing concrete examples for each type (e.g., items:['5.02'] for sec_8k) and explaining delivery channel behaviors (email templated, SMS must match verified phone, webhook HMAC signing). This adds significant meaning for 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 creates a subscription to a live-data event stream, specifies the verb 'subscribe' and resource 'alerts', and lists supported types and delivery channels. It distinguishes from sibling tools like list_subscriptions or unsubscribe by emphasizing creation and proactive monitoring.

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 prerequisites (Pipeworx OAuth account) and detailed examples for each subscription type and delivery method, aiding correct invocation. However, it does not explicitly state when to use this tool versus alternatives like recent_alerts or list_subscriptions, slightly limiting guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds context about the return format (category-bucketed example questions with exact tool+argument shape) and mentions live catalog of thousands of tools, which 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 a single paragraph that efficiently front-loads common user queries and sequentially explains purpose, behavior, and usage. It is dense but not verbose, earning its place with every sentence.

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 fully explains the return structure (category-bucketed example questions) and covers the tool's purpose, parameter, and recommended usage order. Combined with thorough annotations, it provides complete contextual information for an onboarding tool.

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

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

Schema coverage is 100% with one optional parameter described. The description elaborates by listing allowed focus areas (finance, pharma, etc.) and clarifies that omitting the parameter gives a cross-category spread, adding meaning beyond the schema.

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

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

The description clearly states the tool returns category-bucketed example questions to help users get started with Pipeworx. It uses specific verbs and distinguishes itself from sibling tools like ask_pipeworx and discover_tools by positioning itself as the onboarding entry point.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you,' providing clear context for when to use it. It also explains optional topic filtering. However, it does not explicitly exclude any scenarios, so it stops short of a 5.

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

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

Description adds value beyond annotations: discloses soft-delete behavior and ownership constraints. Annotations already show non-destructive, non-read-only, but description clarifies the nature of the operation.

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

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

Two sentences, front-loaded with core action, no unnecessary words. Every sentence contributes essential 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?

For a single-parameter tool without output schema, description covers all key aspects: action, prerequisites (ownership), side effects (deactivation), and data persistence.

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 id with description. Description adds that id comes from subscribe, providing context. Schema coverage is 100%, baseline 3, and description adds marginal 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?

Description clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools 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?

Explains ownership enforcement and what happens to the subscription (deactivated, not deleted). Implicitly guides when to use: to cancel own subscriptions. Could mention exclusion criteria but not necessary.

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, openWorld, idempotent, non-destructive. Description adds context: uses SEC EDGAR for financial claims, grounded pipeline for others, returns verdicts and citations. No contradiction with annotations.

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

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

Single well-structured paragraph with examples and routing logic. Detailed but not overly verbose; could benefit from bulleted list for verdict types.

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?

Coverage is complete given complexity: explains return values (verdict, value, citation, reasoning), parameter usage, and two-case routing. No output schema, but description suffices.

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?

Both parameters are documented in schema; description adds nuance for tolerance_pct (default, range, use for hallucination detection). Schema coverage is 100%.

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: verifying factual claims against authoritative sources. It provides example queries and distinguishes between company-financial claims and other claims, making its purpose unambiguous.

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

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

Explicitly states when to use ('whenever the agent needs to check factual correctness') and differentiates between claim types. Lacks explicit exclusions or comparisons to siblings like deep_research, but guidance is strong.

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