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?

Beyond readOnly/openWorld/idempotent hints, the description discloses that the tool routes to 5,798 tools, fills arguments, returns pipeworx:// citations, may return a refusal, and cannot handle certain categories. These limitations clarify real behavior and complement the annotations. 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 opening line front-loads the key decision ('PREFER OVER WEB SEARCH'), followed by mechanism, examples, alternatives, and limitations in a logical order. Though lengthy, every sentence carries routing or behavior information; the web-search repetition is deliberate emphasis rather than filler.

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

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

For a routing tool with no output schema, the description is remarkably complete: it covers what it returns, stable citation URIs, refusal behavior, examples, exclusions, training-cutoff limits, and pointer to sibling versions. An agent has enough context to decide when to invoke it and 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 already documents all six properties (including aliases) at 100% coverage, so the baseline is satisfied. The description adds value by providing concrete example questions and trigger phrases that define what should go into the `question` parameter, lifting it above baseline.

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

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

The description states a clear verb and resource: it routes factual questions to a large corpus of verified sources and returns structured answers with citations. It explicitly names sibling alternatives for other cases (deep_research, entity_profile, recall, polymarket tools), making it easy to distinguish from siblings.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual/current/historical data, with trigger phrases and examples, and 'START HERE for most questions'. It also names when-not-to-use conditions and routes to specific siblings (deep_research, entity_profile, recall, polymarket) and web search for excluded topics.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds that it currently matches ask_pipeworx exactly (no active candidate) and that routing improvements may be enabled live, which is valuable behavioral context beyond the annotations. It falls back to nothing, clarifying it is a full working router.

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 moderately sized and front-loads the key identity (beta of ask_pipeworx) first. The sentence about candidate testing and retirement date adds context but is somewhat verbose for an MCP tool description. Overall it earns its place by explaining the current operational state.

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 it's a router with 100% schema coverage, no output schema, and read-only annotations, the description adequately explains what it does and its current relationship to ask_pipeworx. It doesn't explain the response format, but that's shared with ask_pipeworx and the description notes 'same response shape.' Missing some detail about what 'candidate routing improvements' means in practice.

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 already documents all six parameters including aliases. The description adds 'same arguments, same response shape' which is helpful, but it doesn't add new semantic meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states it is the beta version of ask_pipeworx, an identical universal router, and names the sibling it relates to. It distinguishes itself from the stable ask_pipeworx by its experimental routing intent, though it doesn't explicitly differentiate from ask_pipeworx_grounded.

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

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

The description explicitly says to 'Use it exactly like ask_pipeworx when you want the newest routing' and explains comparison against the stable router. This gives clear when-to-use guidance and names the alternative (ask_pipeworx) implicitly through the comparison context.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses exact output shapes, refusal reasons, the guarantee of using ONLY tool result content, and the additional LLM call cost. This gives the agent a detailed behavioral contract for a high-stakes tool, and nothing in the description contradicts the annotations.

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

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

The description is dense but every sentence earns its place: purpose, routing behavior, result format, refusal reasons, usage context, and cost trade-off are all covered without repetition. The most important differentiator — grounded extraction and refusal behavior — is front-loaded.

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

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

For a high-complexity tool with no output schema, the description fully compensates by specifying both success and refusal response shapes, when to prefer the sibling, and what makes this mode distinct. Combined with comprehensive annotations and full parameter coverage, nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents the single meaningful question parameter and its aliases. The description adds no extra parameter semantics, but it does not need to; the baseline of 3 is appropriate when the schema 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 clearly identifies a specific, distinctive behavior: a hallucination-resistant answer mode that extracts answers only from tool results, with explicit refusal when data is insufficient. It also differentiates itself from ask_pipeworx by naming it as the same-routing alternative with a stricter, grounded response guarantee.

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

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

The description explicitly states when to use this tool — 'whenever an answer will be quoted, cited, or acted on' and where fabrication is unacceptable — and contrasts it with ask_pipeworx, which should be preferred for casual lookups due to the extra LLM call cost. This gives an agent clear decision criteria rather than leaving the choice to inference.

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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, and the description does not contradict them. Beyond that, it adds substantial behavioral context: decomposition into facets, parallel routing to 5,798 tools, explicit gaps[] instead of invention, contradictions[], semantic excerpting of large records, the hop field and citation_uri fetchability guarantee, and expected latency ranges (15-60s, up to ~90s for thorough). This goes well beyond what annotations provide; a 4 feels right because descriptions could go further on failure/error behavior, but the transparency level is unusually high.

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

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

The description is dense and information-rich, but it is a single run-on paragraph without structural breaks. It front-loads the most critical info (account required, alternative tool), which is good, but the many clauses and parenthetical asides ('depth:"thorough" needs a paid plan') make it harder to parse. It earns its keep per sentence, but structure could be improved with bullet points or clear sections.

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 complex research tool with only 2 params, no output schema, and rich annotations, the description covers everything an agent needs: prerequisites (sign-in), pricing tier, alternatives, latency, return format (findings packet, gaps[], contradictions[], hop, citation_uri), and scope boundaries (structured data only, not open-web). The output format is not formally defined by a schema, so the description's explanation of the findings packet is essential and well provided.

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

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

Schema description coverage is 100%: the schema already documents both parameters and even the depth enum values in detail. The description adds real value beyond the schema by explaining what depth levels do in terms of hops, gap recovery, and contradictions scanning, and by clarifying that 'question' should be broad/multi-part. It doesn't dump the full semantic weight on the schema — it enriches it. Baseline 3 for high coverage, raised to 4 for genuine added depth 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 what the tool does: grounded multi-source research across 1,517 structured data sources in one call, decomposing questions into facets and routing to tools in parallel, returning a findings packet. It distinguishes itself explicitly from open-web search and from ask_pipeworx ('If you are not signed in, use ask_pipeworx instead'), so an agent can tell it apart from siblings.

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

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

The description gives explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with examples, and 'For a single lookup use ask_pipeworx instead.' It also states the account requirement and the alternative for unsigned-in users, which is exactly the kind of conditional routing guidance an agent 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=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?

Annotations already signal read-only, idempotent, open-world behavior, and the description adds substantial non-obvious context: parallel fan-out across sources, USPTO soft-fail until reactivated, fda_products being empty as an expected outcome, resolved:false for private companies, and semantics of sources_used/sources_failed. This goes well beyond the structured annotations and prevents misinterpretation of empty results. 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 long, but the density is warranted for a multi-source tool with many edge cases. It is front-loaded with usage examples and structured around input, sources, and returned sections. There is minor redundancy with the parameter schema—value shapes are repeated—but almost every sentence carries useful signal.

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 a complex multi-source fan-out, the description is unusually complete: it enumerates all returned sections, URI patterns, source-specific behavior, failure semantics, and expected empty-result cases. An agent has enough context to call the tool correctly and interpret its response without guessing.

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 documents both parameters at 100% coverage, and the description still adds real value: concrete ticker/CIK/name examples, zero-padding guidance, SEC EDGAR name-resolution behavior, and explicit interchangeability of 'company' and 'ticker' values. An agent can confidently know which value shapes are accepted and how names are resolved.

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

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

The description clearly defines a specific resource and deliverable: 'full cross-source profile of a US public company in ONE parallel call,' backed by concrete example queries. It also distinguishes itself from chained single-pack SEC/XBRL/news lookups. However, it does not explicitly name or differentiate against closely related siblings like compare_entities or resolve_entity, so it stops just short of full sibling discrimination.

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 an explicit routing rule: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also clarifies accepted input forms and the behavior for private companies. Missing are explicit when-not-to-use statements or named sibling alternatives such as resolve_entity for pure resolution or compare_entities for comparisons.

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 only cover readOnly, openWorld, idempotent, and non-destructive intent; the description adds a rich behavioral disclosure: compatibility codes, unclassified legs never paired, temporal_alignment null semantics, fee treatment, skipped comparison counters, and the explicit 'gross, not net tradeable edge' caveat. This goes far beyond what the annotations could convey.

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 a clear opening and uses labeled sections, examples, and inline code formatting. However, it is extremely long and repeats safety-related caveats across compatibility codes, per-entry flags, temporal alignment, and skipped legs; it is navigable but would benefit from trimming.

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

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

With no output schema, the description carries the full burden of explaining response shape and interpretation. It covers top_spreads_pp, compatibility_warning/codes, spread flags, skipped_unclassified, low_confidence_pairs, temporal_alignment semantics, fees_note, and skipped cross-type/subtype counters, so an agent can invoke and interpret the tool without additional information.

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

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

The input schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantic context by explaining that topic and explicit modes run the identical token-overlap matcher and that both modes produce the same safety disclosures, which the schema alone does not state.

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?

Opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' – a specific verb+resource+scope that immediately identifies the tool's purpose. The two-mode explanation and the gross-vs-net disclaimer also help distinguish it from single-venue or tradeable-arbitrage tools nearby in the sibling list.

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

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

The 'TWO MODES' section provides clear guidance on topic shortcuts versus explicit ticker/slug pairing, and the closing warning sets expectations that most pre-mapped topics return compatibility_warning today. It never explicitly names alternatives like polymarket_arbitrage for tradeable arbs, so the exclusion is only implicit rather than stated.

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

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

Annotations already 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 mark the tool read-only and idempotent, and the description adds substantial behavioral detail: graceful degradation if GLEIF/OpenFIGI fail, explicit `unresolved` fields, `figi_candidates` on ambiguous matches, and internal cascading across lookup endpoints. This far exceeds the safety profile encoded in 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 front-loaded with intent examples, a 'Use FIRST' directive, and organized SUPPORTED TYPES sections. It is dense and heavily parenthetical, especially for the company type, so it is not maximally scannable, but nearly every clause carries useful 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?

Even without an output schema, the description discloses returned identifiers (CIK, ticker, LEI, FIGI, RxCUI, ingredient/brand), the `unresolved` field, candidate disambiguation, accepted inputs, and failure behavior. There is no obvious missing context an agent would need to call this tool correctly.

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

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

Schema coverage is 100%, but the description adds meaning that the schema lacks: accepted input forms for `value` (ticker, CIK, ISIN, name, brand/generic), the warning to pass only the entity name for bonds, and the ISIN-to-LEI behavior. This materially improves 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 opens with concrete user phrasings and states a specific job: resolve a user-spoken name to canonical/official identifiers. It further sharpens the purpose with 'Use FIRST whenever you have a name but need an ID' and enumerates supported types, making it clearly distinct from sibling tools like entity_profile even though no sibling is named.

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 gives an explicit trigger condition: 'Use FIRST whenever you have a name but need an ID.' It also contrasts itself with manual work by saying it 'replaces 2-3 manual lookups,' and describes when enrichment can degrade, so the agent knows when results may be partial.

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.