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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavior beyond that: it discloses routing to 5,706 tools, argument filling, structured answer format, and stable pipeworx:// citation URIs, plus the 'fast call' nature. 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 longer than average but front-loaded with the most important directive ('PREFER OVER WEB SEARCH') and uses scannable use cases and examples. Some repetition of 'current' and the list of query phrases could be trimmed, but nearly every sentence earns its place.

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

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

For a broad, open-world question-answering tool, the description is remarkably complete: input expectation, output shape (structured answer with citation URIs), scope of sources, examples, boundary conditions, and clear escalation paths to siblings. No output schema exists, so the description appropriately explains what the agent can expect in return.

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

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

Schema description coverage is 100%, and the schema documents the question parameter and its aliases. The description does not add parameter-level semantics beyond offering example questions, but that is acceptable because the schema already carries the full burden.

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

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

The description states a clear purpose: it answers factual questions by routing to verified data sources and returns structured answers with citations. It explicitly distinguishes itself from web search and from the sibling tools ask_pipeworx_grounded and deep_research, so an agent can tell them apart without inspecting schemas.

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

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

Usage guidance is explicit and actionable: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and concrete step-up conditions for ask_pipeworx_grounded and deep_research. It also covers the breaking-news case, leaving little ambiguity about when to select this tool.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description goes further by revealing the experimental nature, the possibility of live candidate routing changes, the current inactive state, and the fact that it is a full working router with no fallback. This adds valuable context beyond the annotations and fully sets expectations.

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, each carrying essential information: identity, current state, usage directive, and clarification that it is not a fallback. It is front-loaded with the core purpose and structured to guide the agent efficiently without redundancy.

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

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

For a simple router tool with one required natural-language parameter, the description covers everything an agent needs: what it does, how it differs from its sibling, when to use it, and its current operational status. The lack of an output schema is mitigated by the statement that it shares the same response shape as ask_pipeworx, so no critical information is missing.

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 all six parameters are aliases for 'question', each documented in the schema. The description adds no parameter-specific meaning beyond what the schema already provides, so the baseline of 3 is appropriate per the rubric.

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

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

The description opens with 'Beta version of ask_pipeworx: identical universal router' which immediately states the resource and its nature. It explicitly differentiates from ask_pipeworx by calling out 'candidate routing improvements' and the experimental edge, making it impossible to confuse with the stable sibling.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and clarifies that the tool is currently identical to the stable version because no candidate is active. It also states the comparison against the stable router to decide merges, giving clear when-to-use context and naming the alternative.

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

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

Annotations already declare readOnly, idempotent, openWorld, not destructive. The description goes further by disclosing the internal routing, the refusal behavior with specific refusal reasons, and the extra LLM call cost. It also clarifies that it extracts only from tool results, which is a key behavioral guarantee.

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

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

The description is dense but well-structured. It front-loads the core purpose and then provides return structure and usage guidance. Every sentence is informative, with no filler.

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

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

The description fully specifies the return types (success with evidence and refusal with reasons), explains the cost, and gives explicit usage boundaries. For a tool with no output schema, this is comprehensive.

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 schema fully documents the single `question` parameter and its aliases. The description doesn't add parameter semantics beyond saying the question is in natural language, which is already implied by the schema. Thus baseline 3.

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

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

The description clearly states a specific verb (extract answers from tool results) and resource (tool data from 5,706 tools across 1493 sources), and distinguishes from sibling ask_pipeworx by the 'grounded' or hallucination-resistant aspect. It even names the routing behavior.

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 an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' Names the alternative (ask_pipeworx) and the cost tradeoff.

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?

Even though annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, the description adds substantial behavioral context: it returns verbatim evidence with citations, never invents findings, exposes gaps[], handles contradictions[], and explains the hop-based iteration for second-hop recovery. It also discloses the semantic excerpting behavior and latency expectations, which are valuable 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 dense but information-dense, covering account requirements, alternatives, behavioral details, and latency in a single paragraph. It is longer than ideal, but nearly every sentence carries operational value. Some redundancy exists (e.g., re-explaining depth hops after the schema already details it), but overall it is structured with the most critical info 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 research tool with no output schema, the description covers what an agent needs: what it returns (findings packet with evidence, confidence, source, citation), when to use it, how depth affects behavior, limitations (gaps[] for unanswered facets, not good for current news), and expected latency. It also explains citation_uri resolvability. This is a complete picture.

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

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

The schema already covers both parameters (question and depth) with detailed descriptions, so baseline is 3. The description adds depth-specific behavioral meaning—quick/standard/thorough facet counts and hop behavior—which goes beyond the schema's enum descriptions. This additional context earns 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?

The description clearly identifies the tool as grounded multi-source research across Pipeworx's 1,493 structured data sources, decomposing questions into facets and routing to 5,706 tools in parallel. It explicitly distinguishes itself from open-web search and from sibling tools like ask_pipeworx, making its purpose and scope 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 provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and for single lookups or breaking/current-news topics it directs users to ask_pipeworx instead. It also specifies the account requirements and depth-level behavior, so an agent knows exactly when to choose this tool 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?

The annotations are all false, so the description carries the full burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), that filing without an account returns a claim_token, how to use the token later to read status, and that the team reads digests daily. This is rich behavioral context beyond anything the annotations provide.

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

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

The description is a single dense paragraph, but each sentence adds essential context about when to use, what to include, rate limits, and claim token behavior. It is front-loaded with purpose. It could arguably be tightened, but the length is justified by the tool's nuanced usage rules.

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

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

Given the tool has 4 parameters (one nested), no output schema, and minimal annotation value, the description covers all necessary ground: return behavior (claim_token), rate limits, scope, and what content to include. An agent can confidently invoke this tool without external knowledge.

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

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

Schema coverage is 100%, but the description adds meaningful parameter guidance: it explains the claim_token flow with a concrete example, clarifies that message should be specific and 1-2 sentences, notes the 2000-char limit, and states context is optional. This enriches the schema's descriptions with lifecycle information and usage tips.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly identifies the tool as a feedback channel for the Pipeworx platform, distinguishing it from sibling tools like ask_pipeworx or research tools. The purpose is 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?

Provides explicit when-to-use guidance: '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 a critical exclusion: only for tools from this Pipeworx connection, not other MCP servers, and suggests filing there instead. This fully addresses selection vs. alternatives.

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

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

Annotations 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 cover safety (read-only, idempotent, non-destructive), and the description adds rich behavioral context: it explains that compatibility_warning can be non-empty even with matched_pairs>0, lists all compatibility codes, states that unknown legs are never paired, and details skipped counters. It also discloses that pre-mapped topics may not be tradeable, providing honest expectations. This far exceeds what annotations provide.

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

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

The description is front-loaded with the purpose, then organized into labeled sections: TWO MODES, RESPONSE, SAFETY FIELDS. Every sentence adds value—explaining modes, response fields, compatibility codes, and reliability caveats. Though long, it is dense and well-structured; 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?

For a tool with no output schema, the description thoroughly explains the response shape: each venue's leg-by-leg prices, top_spreads_pp, safety fields with codes, skipped counters, and temporal alignment. It also covers edge cases (unknown legs, non-equivalent bet shapes) and the practical caveat that pre-mapped topics may not be tradeable. This is complete for an agent to call 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% so the baseline is 3, but the description adds significant meaning: it explains that `topic` auto-fetches matching events on each venue, and that explicit parameters override the topic-mapped side. It also enumerates the valid topic values and provides example formats for the ticker and slug. This goes beyond the schema's brief descriptions.

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

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

The opening sentence states the exact purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It names the specific resource (spread between two venues) and describes the core functionality. It also distinguishes itself from other polymarket tools by its unique cross-venue focus.

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 clearly explains how to switch between the two modes: 'TWO MODES: (1) `topic` — 10 pre-mapped macro shortcuts... (2) explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings.' It warns that pre-mapped topics often produce compatibility warnings, helping the agent decide when to use explicit mode. It does not explicitly name sibling alternatives like polymarket_arbitrage, but the usage context is clear.

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

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?

Annotations already declare readOnlyHint and idempotentHint, but the description adds significant behavioral context: identifiers are 'labelled with the source that established it,' unresolved identifiers are 'stated explicitly under `unresolved` rather than omitted,' LEI/FIGI enrichment 'degrades gracefully,' and each call 'cascades through several lookup endpoints.' This goes well beyond the safety-only annotations and clarifies edge-case behavior.

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

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

The description is long but well-structured, starting with example queries and a core statement before diving into supported types. Each sentence carries relevant detail (e.g., source labelling, graceful degradation, ISIN mapping). It is denser than necessary but not bloated; the structure helps an agent parse it efficiently. A tighter version could trim some repetition, but it remains highly informative.

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

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

With no output schema, the description carries the burden of explaining return behavior. It details the fields returned for company (CIK, ticker, company_name, LEI with parents/children, FIGI) and drug (RxCUI, ingredient, brand, citation), discusses edge cases (unresolved identifiers, ISIN for non-US issuers), and explains graceful degradation. This is comprehensive for a tool with 2 parameters and 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%, but the description enriches both parameters. For 'value' it explains accepted formats: 'ticker (AAPL), CIK (0000320193), or name' for company, and 'brand or generic name' for drug. It also provides an ISIN example that resolves to legal entities, adding meaning not present in the schema's simple 'string' type. The 'type' enum is elaborated with detailed return fields for each option.

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: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries ('What's the ticker for…', 'find the CIK for…') and distinguishes its scope by noting it covers company and drug identifiers, setting it apart from siblings like entity_profile or validate_claim.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' giving direct when-to-use guidance. It also notes that it 'replaces 2-3 manual lookups,' implying efficiency benefits. It does not name specific alternative tools or state when NOT to use it, but the guidance is clear and actionable.

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

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

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?

Beyond annotations, the description discloses the two-path pipeline, the exact verdict types, and the critical distinction between could_not_verify (verification did not happen) and unsupported (no source exists). It also warns that could_not_verify must not be treated as evidence. This is rich behavioral context 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?

The description is long but every sentence earns its place: trigger phrases, use case, dual-path explanation, returned values, error semantics, and efficiency claim. It is well-structured with an IMPORTANT warning and front-loaded with the most relevant use signal. No dead weight.

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

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

No output schema exists, so the description takes full responsibility for explaining return values, which it does thoroughly with the verdict list, citation, reasoning, and error semantics. It also covers both pipeline paths and the caller-relevant distinction between could_not_verify and unsupported. The description is complete for a tool of this complexity.

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

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

The input schema already provides thorough descriptions for both parameters, including examples and the tolerance override behavior. The tool description adds little parameter-specific meaning beyond mentioning 'exact percent-delta math' in passing. With 100% schema coverage, the baseline of 3 is appropriate; the description does not need to compensate.

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

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

The description clearly identifies the tool as a 'natural-language claim verification against authoritative sources' with specific trigger phrases like 'fact check' and 'verify the claim that'. It explicitly distinguishes its scope (company-financial vs. any other factual claim) and names sibling alternatives, leaving no ambiguity about what the tool does.

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

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

It states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides clear routing guidance: company-financial claims go through SEC EDGAR/XBRL, while any other claim falls through to the grounded pipeline. This is explicit when-to-use advice with differentiation from alternatives.

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