Alpaca

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds important behavioral details: default model (Workers AI Llama-3.3-70b free), optional Anthropic probing (BYO key, paid), and return structure. 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 concise (three sentences), front-loaded with the main action, and every sentence adds value. There is no redundant or irrelevant 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 4 parameters, no output schema, and annotations present, the description is complete: it explains what the tool does, all parameters, return format (score, confidence, signals, raw_response, combined view), and use cases. 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?

Schema description coverage is 100%, so baseline is 3. The description adds significant value beyond the schema by providing examples for 'entity', clarifying the role of '_apiKey', and explaining the 'models' parameter options. This raises the score to 4.

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

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

The description clearly states the specific verb 'probe' and resource 'LLMs for what they know... and score visibility (0-100) per model'. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on any entity's visibility scoring across multiple LLMs, not just competitors.

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: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It does not mention specific alternatives or when not to use, but the use cases provide clear context for when this tool is appropriate.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which are consistent. The description adds valuable behavioral context: uses IEX feed, includes pre-market and after-hours sessions, and specifies data shape. 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 concise (three sentences plus an example) with no filler. It front-loads the core functionality and quickly covers key details like timeframes, feed, and data fields.

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 sufficiently explains return structure (fields like t, o, h, l, c, v, vwap, trades). It covers input parameters, API key requirement, and limitations (max symbols, lookback shorthand). Complete for a data retrieval 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%, so baseline is 3. The description adds examples illustrating shorthand lookback usage and explains that multiple symbols are allowed (max 20). This provides practical context 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 clearly states it provides 'Historical US stock OHLCV bars with per-bar VWAP and trade count' and lists supported timeframes. It distinguishes from siblings like 'alpaca_snapshot' (real-time snapshots) and 'alpaca_intraday_vwap' (likely a different data product).

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

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

The description explains when to use (historical bars) and provides examples. It implicitly indicates not for real-time data, but does not explicitly exclude use cases 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?

The description details that it fetches today's 1-minute bars from 04:00 ET (including pre-market), computes cumulative VWAP, and compares to the latest trade. It also notes the data source (BYOK Alpaca, real-time IEX feed). This adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint), which already indicate safety.

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-organized paragraph. It starts with the main purpose, explains the computation, lists return fields, and ends with an example. Every sentence adds value with 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 the tool's moderate complexity, the description covers all essential aspects: what it does, how it works (data source, computation), inputs (symbols and API key with formatting), and outputs (listed fields). The rich annotations further complement the completeness. No output schema exists, but the description adequately explains return values.

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

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

Both parameters are fully described in the input schema with clear descriptions. The description repeats the schema content for _apiKey and symbols, adding no new meaning. With 100% schema coverage, a baseline of 3 is appropriate.

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

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

The description clearly states the tool computes the current session VWAP for US stocks and compares it to the latest trade. It specifies exact verbs (fetches, computes, returns) and the resource (VWAP for given symbols). The purpose is distinct from sibling tools like alpaca_bars or alpaca_snapshot.

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 that multiple symbols (comma-separated, max 20) can be queried in one call, and provides an example. However, it does not explicitly mention when not to use this tool or suggest alternatives for different timeframes or historical VWAP.

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, so the description's behavioral contribution is additive. It discloses that during extended hours the minute bar IS the live price, and specifies the data feed (real-time IEX). 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 a single paragraph that packs relevant details without excessive fluff. It begins with the core purpose and follows with specifics. It is slightly dense but remains efficient, earning a 4 rather than a 5 for slight 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 lack of an output schema, the description covers the returned data fields comprehensively (trade, bid/ask, OHLCV, change, minute bar with VWAP). It also explains the extended-hours behavior and max symbols. It is mostly complete, though it could mention error handling or rate limits.

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

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

Schema coverage is 100%, so the description doesn't need to explain parameters in depth. It adds minimal extra context beyond the schema, such as the example format for _apiKey and the number of symbols. This meets the baseline for high-coverage schemas but doesn't significantly enhance meaning.

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 provides a real-time US stock snapshot with extended-hours coverage, listing specific data points like OHLCV, previous close, and VWAP. It answers questions about pre-market prices and after-hours volume. However, it doesn't explicitly differentiate from sibling tools like alpaca_bars or alpaca_intraday_vwap, which slightly reduces clarity.

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 usage context by listing example queries it answers (e.g., 'pre-market price of OKTA'), implying when to use it. It also mentions the max 20 symbols. However, it does not provide explicit guidance on when not to use it or mention alternatives, so the usage guidelines are adequate but not detailed.

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, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context: it fills arguments automatically, routes across thousands of tools, and returns stable citation URIs. It does not disclose rate limits, auth requirements, or failure modes, but the additional context goes beyond 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 overly long and contains a garbled, repetitive tail: 'even if web search could also answer it. Examples: "current US unemployment rate"...' repeats content already presented earlier. The front-loading is good, but the second half is redundant and corrupted, making the description noticeably bloated and poorly 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?

For a complex tool with many siblings, the description covers the main use case well: it lists domains, trigger phrases, examples, and cites the output format. However, it lacks explicit routing guidance between ask_pipeworx and its close siblings like deep_research or ask_pipeworx_grounded, and the garbled tail weakens the overall completeness. No output schema exists, so the description bears more responsibility, but it still provides the essential invocation 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 schema covers 100% of parameters, all of which are aliases for the single `question` parameter. The description adds value by providing numerous natural-language examples and trigger phrases that illustrate what the input should look like, such as 'current US unemployment rate' and 'Apple's latest 10-K'. This is above the baseline 3 that high schema coverage alone would warrant.

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

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

The description clearly states a specific verb and resource: it routes the question to one of 5,710 tools across 1,494 verified sources and returns a structured answer with pipeworx:// citations. It explicitly positions itself over web search, which helps distinguish it from that alternative. However, it does not differentiate itself from closely named siblings like ask_pipeworx_grounded or ask_pipeworx_beta, so it falls short of a 5.

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 strong when-to-use guidance: 'PREFER OVER WEB SEARCH', trigger phrases like 'what is', 'look up', 'get the latest', and explicit instruction to 'START HERE for most questions'. It gives clear context but does not state when not to use it or name alternative tools like deep_research or ask_pipeworx_grounded, so it lacks explicit exclusions.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable behavioral context: it is a full working router with 'no active candidate right now,' meaning current behavior exactly matches ask_pipeworx. It also discloses the experimental nature and the comparison process, going beyond annotations without contradicting them.

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

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

The description is four sentences and covers beta status, current parity, usage directive, and fallback behavior without wasted words. It front-loads the key concept 'Beta version of ask_pipeworx' and each sentence adds distinct information.

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

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

Given no output schema, the description references 'same response shape' as ask_pipeworx, which is sufficient for an agent familiar with the stable tool. It clearly states it 'Falls back to nothing' and is a full router, preventing misconceptions. It could be more explicit about the exact input format, but the alias parameters and 'same arguments' pointer are adequate.

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 description coverage is 100%, but every parameter is only described as 'Alias for question,' providing minimal semantic value. The description points to 'same arguments' as ask_pipeworx, which is useful but doesn't explain parameter intent beyond what the schema's alias descriptions already convey. This meets the baseline for high schema coverage but doesn't add much.

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 is a 'Beta version of ask_pipeworx' and a 'universal router' with 'same 5,710 tools, same arguments, same response shape.' This identifies the core function and distinguishes it from the stable ask_pipeworx sibling, though it relies on the reader knowing what ask_pipeworx itself 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?

Explicitly instructs 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router. This gives a clear condition for choosing this tool. It doesn't explicitly state when not to use it, but 'when you want the newest routing' implies the alternative is the stable version.

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/idempotent annotations, it discloses the extra LLM call cost, the refusal mechanism with specific refusal reasons, and the hard constraint that answers use ONLY what the tool result contains. This is rich behavioral context not available from annotations alone.

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: differentiator, routing behavior, extraction constraint, return contract, refusal reasons, use cases, and cost tradeoff. The most important differentiator 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?

With no output schema, the description fully covers the response shape, refusal reasons, cost impact, and selection criteria. Combined with 100% schema coverage of parameters, an agent has everything needed to both select and invoke 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 description coverage is 100%, so the parameters are already fully documented and the baseline is 3. The description adds no parameter-level detail beyond the general notion of a question being routed; it focuses on behavior and response semantics instead.

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 specific function: a hallucination-resistant answer mode that routes through tools, fetches data, and extracts the answer using only the tool result. It names the exact output contract and distinguishes itself from sibling ask_pipeworx by name and behavior.

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

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

It gives explicit when-to-use guidance: whenever an answer will be quoted, cited, or acted on and facts must not be invented, with concrete domains like financial verdicts, legal claims, and medical lookups. It also names the alternative and the condition for choosing it: prefer ask_pipeworx for casual lookups.

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 covers behavioral details beyond annotations: resolver contract with confidence levels, parent event extractor, news fallback, safety short-circuits, closed market handling, wide spread warnings, and cancellation rule parsing. 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 lengthy but well-structured with labeled sections (RESOLVER CONTRACT, SAFETY, etc.) and example breakdowns. Every sentence adds value, though it could be slightly more concise. The structure aids readability despite the length.

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

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

Given the complexity (3 params, no output schema, rich behavioral details), the description is exceptionally complete. It covers all aspects: input variations, fan-out logic, response shapes, resolver behavior, parent events, news fallback, safety mechanisms, and risk rules. Without an output schema, it effectively describes return structure.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful context: examples for the 'market' parameter, effects of 'depth' (quick vs thorough), and specific guidance for 'include_raw' (when to use true). This extra clarity justifies a 4.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, question). It distinguishes from siblings like polymarket_edges and polymarket_arbitrage by focusing on a single bet research rather than edge scanning or arbitrage.

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

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

The description explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. While it doesn't explicitly mention when not to use it or alternatives, the provided sibling list implies differentiation. Clear context for usage is provided.

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), the description adds key behavioral details: data sources (SEC EDGAR for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results by primary metric, and citation URIs. 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 thorough but front-loaded with example queries. Every sentence adds value, though could be slightly trimmed without losing clarity. Structure is logical: examples, preference guidance, type-specific details, return format.

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 adequately explains return format (paired data + citation URIs, sorted). For a comparison tool, this is sufficient context. Could specify exact fields, but not necessary given clear purpose.

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 significant meaning: 'type' enum explained with data sources, 'values' format clarified (tickers/CIKs for company, names for drug) and constraints (2–5 items). This goes beyond schema definitions.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one call, with specific examples like 'compare X and Y' and 'which is bigger'. It distinguishes itself from sequential single-pack lookups, making the purpose unambiguous.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear when-to-use guidance. It implies alternatives (e.g., entity_profile for single entities) and covers comparison scenarios thoroughly.

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 it read-only and idempotent, and the description adds substantial context: account/plan requirements, parallel decomposition across 5,710 tools, findings-packet fields, explicit gaps[], never-invented behavior, contradictions[], hop and citation_uri semantics, semantic excerpting, and latency. No contradiction with annotations.

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

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

The description is dense and front-loaded with the most critical constraint: account/plan requirement. It is longer than ideal and partially repeats depth behavior already in the schema, but the complexity of the tool justifies most of the length.

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

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

With no output schema, the description fully covers what a caller gets back: findings packet fields, gaps, contradictions, hop, citation URI, and timing. It also covers prerequisites, exclusions, and alternatives, so an agent has enough context to invoke and interpret results correctly.

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

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

The schema already documents both parameters fully, so the baseline is 3. The description adds value with concrete example questions, clarifies that broad/multi-part phrasing is expected, and ties the thorough depth to paid access and response-time expectations.

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 specific action: grounded multi-source research across 1494 structured data sources in one call, and explicitly says this is NOT open-web search. It names the key alternative ask_pipeworx and differentiates deep_research for broad/multi-part questions versus single lookups.

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 concrete when-to-use guidance: broad/multi-part questions over structured data, and explicitly says to use ask_pipeworx for a single lookup or when not signed in. This is direct routing that leaves little 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns top-N tools with full schemas and examples, ready to call directly, which goes 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?

Description is front-loaded with the core purpose and provides a comprehensive list of use cases. Somewhat lengthy due to examples, but efficient overall.

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 what is returned (tool names, descriptions, schemas with examples) and that results are immediately callable. Complete for a discovery 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% and all parameters are described. Description adds that multiple aliases (task, q, description, search) are accepted and provides examples, enhancing understanding.

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

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

The description clearly states the tool finds tools by describing data or task. It lists extensive examples (SEC filings, financials, etc.) and distinguishes from siblings by its meta-nature.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-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?

Beyond annotations (readOnlyHint, idempotentHint, openWorldHint, non-destructive), the description details the data sources fanned out (SEC, XBRL, USPTO, news, GLEIF), the exact return fields (cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents soft-fail, news fallback chain, LEI), and the input format constraints. 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 dense paragraph that front-loads usage examples followed by detailed behavior. While informative, it could be more structured (e.g., bullet points for return fields) to improve scanability. However, every sentence adds value, and the length is justified by the tool's complexity.

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

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

No output schema exists, so the description fully compensates by listing all return components (cik, company_name, recent_filings, fundamentals, patents, news, LEI) with details like sorting and fallback. Covers edge cases (patents soft-fail, unsupported name input) and references sibling tools for complementary actions.

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 critical meaning: explains type parameter limits to 'company' (though enum only has that value), and value parameter accepts ticker or zero-padded CIK but not names. Provides clear examples and links to resolve_entity for name handling. Augments schema significantly.

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

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

The description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call' with specific examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from sibling tools by explicitly preferring over chaining single-pack lookups and referencing resolve_entity for name resolution.

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

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

Explicitly states when to use (holistic view, e.g., user asks for company profile) and when not to use (names not supported, must use resolve_entity first). Also mentions patents soft-failing, setting proper expectations. Provides clear alternative for unsupported input types.

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, idempotentHint=true, readOnlyHint=false. Description adds context on use cases but does not reveal additional behavioral details beyond what annotations convey. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose, no unnecessary words. Efficient and clear.

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 and no output schema, the description covers the key behavioral aspects and use context. Lacks a formal description of what happens if the key doesn't exist, but that is minor.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. The description only mentions 'by key' without adding new meaning, so 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?

The description clearly states the action: 'Delete a previously stored memory by key.' It mentions pairing with 'remember and recall,' but does not explicitly differentiate from them, which would require a 5.

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 provides when to use: 'when context is stale, the task is done, or you want to clear sensitive data.' Also mentions alternatives ('Pair with remember and recall'), but does not state when not to 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, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool fetches the page, extracts title/description/links, and emits standard format, which is consistent and provides extra behavioral context.

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

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

Three sentences, each essential: first states purpose, second explains process and output, third lists use cases. No wasted words, front-loaded with key 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 simple tool with 2 parameters, high schema coverage, and annotations covering safety, the description fully explains the input, process, output format, and use cases. 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?

Schema description coverage is 100% for both parameters ('url' and 'max_links'). The description does not add significant meaning beyond the schema; it only provides usage context.

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 a clear action ('generate'), resource ('llms.txt file'), and context ('for any URL'). It distinguishes from sibling tools like 'scan_competitor_ai_presence' by focusing on file creation, not just analysis.

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

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

Explicitly lists three concrete use cases (client indexing, own project drafting, competitor auditing) and implies when to use it. However, it does not explicitly mention when not to use or compare directly to 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 already declare readOnlyHint=true and destructiveHint=false. The description adds value by specifying the exact fields returned (id, type, params, created_at, last_fired_at, fire_count) and implies no side effects, which exceeds what annotations provide.

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

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

The description is two sentences with no wasted words. The first sentence states the core purpose and output, and the second provides usage guidance, making it front-loaded and 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 tool's simplicity, complete annotations, and no output schema needed, the description fully informs the agent about what the tool does, what it returns, and when to use it. No gaps are present.

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?

There is only one optional parameter (include_inactive) with a clear description in the schema (100% coverage). The tool description does not repeat this, but the schema already handles it adequately, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource. It also lists returned fields, distinguishing it from sibling tools like 'subscribe', which creates subscriptions, and 'unsubscribe', which cancels them.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear context on when to use this tool versus alternatives.

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

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

The annotations are all false hints, so the description carries the burden. It discloses side effects and nuances: filing without an account returns a claim_token for later status checks, rate-limited to 5 per identifier per day, free and doesn't count against tool-call quota, and that the team reads digests daily. 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 packed with necessary operational details. Each sentence adds value (types, scope boundaries, claim token mechanics, rate limits, quota exemption). However, it is a dense wall of text that could be tightened; the roadmap sentence is motivational rather than essential.

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 feedback tool with no output schema, the description is remarkably complete: it explains purpose, categories, scope restrictions, message guidance, claim token workflow, rate limits, and cost implications. It also warns against pasting user prompts. This gives the agent all needed context to invoke correctly.

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

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

Schema covers 100% of parameters, so baseline would be 3. The description adds meaningful usage context beyond the schema, especially for claim_token: 'Filing without an account returns a `claim_token`; pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' to read resolution status. This clarifies the token's lifecycle, which the schema's description does not explain.

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.' It clearly enumerates feedback types (bug, feature/data_gap, praise) and explicitly differentiates from siblings by scoping to 'tools served by this Pipeworx connection'.

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).' Also gives a crucial exclusion: if the tool came from a different MCP server, file it there instead, and advises describing issues in terms of Pipeworx tools/packs rather than pasting user prompts.

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

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

Adds value beyond readOnlyHint/idempotentHint by explaining data source (CF analytics-engine), no PII, caching policy (5min-1h), and output shape (pack, tool, count). 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?

Front-loaded with return value, followed by bulleted use cases and implementation details. Every sentence earns its place; no filler.

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

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

For a simple tool with 1 optional param and no output schema, the description covers purpose, usage, data source, privacy, caching. 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?

Schema description already covers window parameter semantics fully (enum values and behavior). Description repeats this without adding new detail. 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 returns top tools, packs, and call volume over a configurable window. It lists three concrete use cases that distinguish it from sibling tools like ask_pipeworx or discover_tools.

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

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

Explicitly lists three scenarios (discovering hot data sources, confirming canonical tools, aligning use case). Lacks explicit when-not-to-use or alternatives, but the guidance is clear and context-rich.

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 true, and destructiveHint false. Description adds extensive behavioral context: internal algorithms (monotonicity, partition checks, semantic anchor, partition filter, fill check including book depth analysis). No contradictions.

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

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

Description is long but well-structured and front-loaded with main purpose. Every sentence adds value (modes, algorithms, warnings, fill check). Could be slightly more terse, but given complexity, it's efficiently written.

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 explicitly states response structure (opportunities array with fields, partition_check object in event mode). Covers edge cases (similarity filter, partition filter, fill check). References sibling tool for custom sizing. Complete for a complex arbitrage detection tool.

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

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

Schema coverage 100% with both parameters described. Description adds meaning beyond schema: explains the mode each parameter triggers, provides example inputs (slugs, seed questions), and clarifies the use of each mode (e.g., event for specific market, topic for cross-event). No enums needed.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) and is distinct from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly instructs when to use each parameter: no args for trending scan, event for specific market, topic for cross-event scanning. Recommends event mode for specific markets and explains cross-event catches patterns single-event misses. Also warns against trading when fill check indicates low realizable edge.

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

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

The description discloses many behavioral traits beyond annotations: caching behavior (1h KV-level), response structure with diagnostics (fed_candidates, _diagnostics), and details of model families and conditions. Annotations are consistent (readOnlyHint=true, etc.), adding confidence.

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 clear sections and details. Each sentence adds value, though some could be slightly more concise. Front-loading the main purpose helps.

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 the response structure (by_segment, fed_candidates, _diagnostics) and the meaning of each field. It is complete for the tool's complexity.

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

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

All 9 parameters have schema descriptions (100% coverage). The tool description adds context by explaining how parameters like min_partition_leg_kelly and category_filter fit into the algorithm, providing additional 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 explicitly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, with a clear use case ('what should I bet on today'). It distinguishes itself from siblings like polymarket_arbitrage by detailing unique model families and segments.

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 indicates when to use (for discovering opportunities without paging hundreds of markets) and describes tradeable-edge knobs for filtering. However, it lacks explicit 'when not to use' guidance or direct comparisons to 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?

The description adds significant detail beyond annotations, including data source (daily snapshots), output structure (tracked, expired, snapshot_dates), limits (60-day TTL, decay from daily closes, not intraday). It fully discloses behavior and constraints, with no contradiction to annotations.

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

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

The description is fairly well-structured with clear sections for purpose, args, response, and limits. However, it is somewhat verbose, particularly in the response description, and could be tightened without losing 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 the tool's complexity and lack of output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates with fields) and constraints (limits). It provides all necessary context for an agent to understand and use the tool effectively.

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

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

Schema coverage is 100% with both parameters documented. The description's mention of args adds minimal value (defaults and ranges already in schema). Baseline 3 is appropriate as the parameter semantics are adequately covered by the schema.

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

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

The description clearly states it provides 'Edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on historical tracking rather than current snapshots.

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 through the question it answers, but it does not explicitly state when to use this tool over alternatives, nor does it provide when-not-to-use or exclusions. The guidance is implicit and lacks direct comparison with 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 already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds operational details: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, forced_directional_risk), and explains that partial basket fills create directional risk. 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 verbose but well-organized: bold labels, separate sections for single-market and basket, and bullet-like outcome fields. Every sentence provides essential information. Slightly longer than necessary but justified by the tool's complexity.

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

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

No output schema exists, yet the description enumerates key return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict, theoretical_sum, realizable_sum, per-leg detail, thin_legs, etc.). It covers behavior, prerequisites, and risk implications, making it fully self-contained.

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

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

Schema coverage is 100%, so baseline 3. The description clarifies parameter roles beyond schema: e.g., for basket mode, 'size_usd' is settlement notional (shares per leg). It explains defaults and mode-dependent behavior for 'side' and 'market'/'event'. This adds meaningful context.

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes two modes (single-market and basket) and provides specific verbs like 'check' and 'walks the ladder.' Sibling tools like polymarket_arbitrage generate signals, while this validates fill risk, so it is well-differentiated.

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 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why: theoretical overround is not capturable on thin books and partial basket fills convert arb into unhedged directional positions. No alternatives are mentioned, but the use case is precise.

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 rich behavioral detail: compatibility_warning and compatibility_codes can be non-empty even when pairs are returned, unknown legs are never paired, skipped counters reveal dropped comparisons, and pre-mapped pairings are not verified by a shared resolution source. This gives the agent a strong mental model of the tool's output semantics and reliability.

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

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

The description is long but densely packed with non-redundant safety and mode information. It is front-loaded with the core purpose and modes, then flows into response shape, safety fields, and caveats. While every sentence earns its place, the sheer length and uppercase emphasis edges it from 'concise' to 'comprehensive'.

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 takes on the burden of explaining return fields and edge cases. It covers top_spreads_pp, compatibility_warning/codes, skipped_unclassified, low_confidence_pairs, temporal_alignment, and skipped counters, plus a warning about the rarity of real spreads. This is as complete as an agent needs for correct invocation and interpretation.

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

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

The schema already covers all three parameters at 100%, so the baseline is 3. The description adds meaningful semantics by explaining the mode relationship ('topic' auto-fetches, explicit params override) and providing the exact shortcut list. This goes beyond the schema's one-line descriptions and clarifies how parameters interact.

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

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

The opening sentence states a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It further distinguishes itself from siblings by focusing on cross-venue comparison and detailing two concrete modes, making it clear what the tool does and how it differs from related 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 clearly explains when to use 'topic' shortcuts versus explicit ticker/slug pairings, including override behavior. It includes a practical caution that pre-mapped topics often return compatibility warnings and are 'not tradeable', but it does not explicitly name alternative tools or exclusion conditions, so it stops short of full 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=true and idempotentHint=true. Description adds scoping detail (anonymous IP, BYO key hash, or account ID) and pairing behavior, enhancing transparency beyond annotations.

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

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

Two sentences, front-loaded with purpose, no wasted words. Efficient and well-structured.

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

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

Tool is simple with one parameter; description covers retrieval and listing. However, no output schema and no mention of what happens if key not found, which is a minor gap.

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

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

Schema has 100% coverage with one parameter. Description adds meaning by explaining that omitting the key lists all saved keys, which is not evident from schema alone.

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 saved value or lists all keys, using specific verbs and resource, distinguishing it from siblings 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?

Explicitly describes when to use (look up context) and when to omit the key argument. Pairs with remember and forget, but doesn't explicitly state when not to use it or alternative 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 mark it as read-only, idempotent, and non-destructive. The description adds valuable details: events are persisted, mark_read flags read status, unread_only filter, and return structure (source, citation_uri, raw payload). 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?

Four sentences, front-loaded with main purpose. Every sentence provides distinct value (filtering, mark_read, polling, alternative access). No waste.

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, it describes return contents. Covers filtering, pagination, read tracking, and alternative access method. Fully sufficient for a read-only polling 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 covers 100% of parameters with descriptions. The description adds context for mark_read (flag to avoid showing same events) and mentions filtering by type and since, but doesn't add new info beyond schema for limit and unread_only. Slightly 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 clearly states it pulls fired events from the subscription feed, specifying return fields (source, citation_uri, raw payload) and filter options. This distinguishes it from sibling tools like 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?

The description notes that polling works fine and provides an alternative access URL for scripts/dashboards. It explains mark_read behavior but doesn't explicitly state when not to use this tool versus alternatives.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds important behavioral details: fans out to multiple sources, fallback from GDELT to GNews, soft-fail for USPTO, returns structured changes with sources and URIs. 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 front-loaded with example queries, but is slightly lengthy. However, every sentence provides necessary information, so it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (multiple sources, fallback logic, parameter details) and the presence of comprehensive annotations, the description covers all critical aspects. No output schema exists, but the description mentions the return structure (changes grouped by source, total_changes count, URIs).

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

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

Schema has 100% description coverage, but description adds value: explains that since accepts ISO date or relative shorthand, gives examples, recommends typical monitoring values. Value parameter is clarified to accept ticker or CIK.

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

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

The description provides specific verb phrases ("What's new with X", "latest on Y") and lists the resources (SEC EDGAR, GDELT, GNews, USPTO). It clearly distinguishes from sibling tool entity_profile by stating when to use the alternative.

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 this tool (e.g., recent changes queries) and when to use entity_profile instead (static profile). Also gives guidance on using the since parameter with recommended values ("30d" or "1m").

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

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

Adds behavioral context beyond annotations: key-value store, scoped by identifier, persistence rules (24 hours for anonymous). No contradictions with annotations. Could mention behavior on key overwrite or error cases, but still strong.

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. Front-loaded with core purpose, then usage guidance, then pairing details. No wasted words. Ideal length for quick comprehension.

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

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

Covers purpose, usage, persistence, and pairing. Missing details like overwrite behavior or error handling, but for a simple memory tool with good annotations, it is sufficiently complete.

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

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

Schema coverage is 100%, but description adds naming conventions for keys ('subject_property', 'target_ticker') and clarifies value as 'any text'. This provides richer semantics beyond the schema descriptions.

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

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

The description states a specific verb ('save') and resource ('data'), and clearly distinguishes from siblings ('recall', 'forget'). It also provides concrete examples of what to store (e.g., 'resolved ticker'), making the purpose highly specific and actionable.

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

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

Explicitly tells when to use the tool ('when you discover something worth carrying forward') and explicitly pairs it with alternatives ('Pair with recall to retrieve later, forget to delete'). Also covers scoping and persistence details for different user types.

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

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

Beyond the annotations (readOnly, idempotent, openWorld), the description exposes behavior such as graceful degradation of LEI/FIGI enrichment, cascade through multiple endpoints, and explicit reporting of unresolved identifiers. This significantly enhances the agent's understanding of what to expect and how the tool behaves under partial failures.

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

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

The description is long but densely informative, with a front-loaded purpose and structured details. While every sentence contributes value, it is somewhat verbose and could be organized more tightly. However, given the complexity of two entity types and multiple identifier sources, the length is mostly justified.

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 what the tool returns: canonical identifiers labelled with sources, an explicit `unresolved` field for missing identifiers, and example citations. It also covers fallback behavior and edge cases like ISINs. This makes the tool's behavior predictable and complete for an agent.

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

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

The existing schema provides 100% coverage for both parameters (type and value), so the baseline is 3. The description adds meaningful semantics beyond the schema, such as the ISIN-to-LEI mapping for company type, acceptance of ticker/CIK/name, and brand/generic names for drugs. This extra context helps with correct parameter formatting and edge cases.

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

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

The description clearly states the tool resolves a user-spoken name to canonical/official identifiers, with a specific verb ('resolve') and resource ('entity identifiers'). It provides multiple examples and distinguishes itself from sibling tools by emphasizing that it produces input IDs for other tools. The 'Use FIRST' phrase directly positions this as the go-to tool for name-to-ID lookup.

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 guidance on when to use the tool ('Use FIRST whenever you have a name but need an ID') and describes the supported types (company, drug). It also explains how it replaces multiple manual lookups. However, it does not explicitly state when not to use it or mention alternatives, so it falls 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive traits. The description adds behavioral context: each entity is probed with ai_visibility_check, results are ranked, and the output includes score, confidence, and signal density. 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 two substantial sentences plus a tagline, every sentence adds value, and it is front-loaded with the primary action. No filler.

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

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

With 4 parameters, no output schema, and no nested objects, the description adequately explains input (entities, optional context/models/key) and output structure (ranked list with fields). It could mention potential limitations like probe cost or rate limits, but overall it is sufficient.

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 burden is lower. The description adds context that the first entity is treated as 'subject' for narrative purposes, but does not significantly enhance understanding of parameters like models or _apiKey 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check probes, and returns a ranked list with scores. This distinguishes it from sibling tools like ai_visibility_check (single entity) and compare_entities (generic).

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

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

The description provides a concrete use case: 'competitive AI-marketing audits' and gives an example question. It implies when to use but doesn't explicitly state when not to use or mention alternatives. The guidance is clear but could be more exhaustive.

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

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

The description goes beyond annotations (readOnlyHint, idempotentHint) by detailing partial failures, the 5-30s delay for bundlephobia first measurement, and the graceful degradation with a sources_failed field. It also lists exact return fields, providing comprehensive behavioral context.

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

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

The description is well-structured and front-loaded with the core purpose. While comprehensive, it is slightly verbose but each sentence adds value. A minor trim could improve conciseness, but it 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 lacking an output schema, the description thoroughly explains the return structure (summary block, advisories, links, alternative versions) and handles edge cases (partial failures, timeouts). It is fully complete for the tool's complexity.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description notes version defaults to latest and that scoped packages work, but adds little beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages, combining data from deps.dev and bundlephobia. It specifies the verb ('check'), resource ('npm package'), and scope, distinguishing it from siblings like scan_competitor_ai_presence.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also notes the NPM-only limitation and directs users to deps.dev for other ecosystems, effectively defining when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint. Description adds significant behavioral details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag. 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?

A single paragraph of four sentences, each delivering essential information. Front-loaded with the core action. No fluff 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?

Given three parameters, no output schema, and rich annotations, the description covers behavior (embeddings, windowing, truncation), constraints (200K char cap), output format (passages with offsets and similarity scores), and usage context (reducing prompt size, pairing with another tool). Complete for its role.

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 description adds value by explaining the limit default (1-20, default 5), providing example queries for the query parameter, and clarifying that text has a max of 200K chars. These details go beyond the schema descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' specifying the action (search), resource (inside a fetched record), and scope (semantic). It distinguishes from siblings by highlighting the advantage of reducing context usage and pairing with 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?

Explicitly says 'Use when the record is too big to cram into the prompt' and describes the benefit of offsets for verification. Mentions pairing with ask_pipeworx_grounded as an alternative workflow, but lacks explicit when-not scenarios.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds important behavioral traits: OAuth requirement, SMS verification process, 10/day cap for SMS, webhook auto-disable after 10 failures, and signing details. 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 compact (3 sentences) yet packs all essential information: purpose, types, parameters, delivery channels, constraints. Well-organized with clear sections and no redundant content.

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

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

Given no output schema, the description includes the return value ('new subscription id'). It covers prerequisites, type-specific params, delivery options, and usage limits. Fully sufficient for an agent to invoke correctly without needing 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?

With 100% schema coverage, baseline is 3. The description amplifies meaning by providing concrete examples for each parameter type (e.g., sec_8k with ticker and items, polymarket_edge with topic and min_spread_bps) and details for delivery channels (webhook signing secret, SMS verification). Significant added value.

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

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

The description clearly states that the tool 'creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id.' It lists supported types and delivery channels, distinguishing it from sibling tools like 'list_subscriptions' and '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?

The description provides explicit context on when to use (proactive monitoring) and prerequisites (requires Pipeworx OAuth account). It covers usage constraints like SMS verification and daily cap, though it does not explicitly state when not to use or name alternatives.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by detailing the output format (category-bucketed example questions with tool+argument shape) and the effect of the 'topic' parameter, 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 front-loaded with the core intent and efficiently conveys purpose and usage. It is somewhat lengthy with multiple examples, but each sentence adds value. Could be more concise, but still 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 simple tool with one optional parameter, no output schema, and rich annotations, the description is complete. It covers purpose, when to use, parameter behavior, and output format, leaving no gaps for the agent.

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

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

Schema coverage is 100% with a single parameter 'topic' fully described. The description restates the same allowed values and behavior (omit for full spread) without adding new information beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states it is the onboarding entry point that returns category-bucketed example questions, with a specific verb ('returns') and resource ('example questions'). It distinguishes itself from siblings like 'ask_pipeworx' and 'discover_tools' by focusing on suggesting what to ask, not asking itself.

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, or to learn how to call the meta-tools', providing clear context for when to use. It does not explicitly state when not to use, but the guidance is sufficient.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false, but description adds key details: ownership check, deactivation (not deletion), and preservation of historical events, enhancing transparency.

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 wasted words. Key information is front-loaded and each 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?

For a single-parameter tool with no output schema and informative annotations, the description is complete: it covers ownership, deactivation, and historical data retention.

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

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

Schema coverage is 100% and the single parameter 'id' is well-described in the schema. The description adds minimal extra meaning beyond referencing the parameter, meeting 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 clearly states 'Cancel a subscription by id,' using a specific verb and resource. It distinguishes from siblings like subscribe and list_subscriptions.

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

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

Description explicitly states ownership enforcement ('you can only cancel your own subscriptions') and notes deactivation behavior. Lacks explicit alternatives but provides clear context.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral details: the dual-pipeline routing, the specific verdict list, the distinction between 'could_not_verify' (check failed) and 'unsupported' (no source), and the explicit warning not to treat 'could_not_verify' as evidence. This substantially aids the agent's interpretation and is not redundant 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 efficiently structured: it opens with natural-language trigger examples, then states the core purpose, followed by routing logic, return value summary, and critical caller warnings. Every sentence carries essential information, and the use of em-dashes and parentheticals keeps it dense yet readable. No filler.

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

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

Given the tool's complexity, the description covers all necessary aspects: return value components, verdict types, citation format, error semantics, and performance benefit ('replaces 4–6 sequential calls'). Since there is no output schema, the description fully compensates by explaining what the tool returns and how to interpret edge cases like 'could_not_verify' and 'unsupported'.

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 describes both parameters (claim as a natural-language factual claim, tolerance_pct as max deviation). The description adds context about the percent-delta math and default tolerance behavior, but does not materially enhance understanding of the parameters beyond what the schema provides. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description explicitly states the tool performs natural-language claim verification against authoritative sources, with specific trigger phrases. It clearly distinguishes itself by describing the two routing paths (SEC EDGAR for financial claims, grounded pipeline for others) and lists the exact verdict types returned, making its purpose specific and unique among 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 an explicit trigger condition: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies how different claim types are routed and warns about the interpretation of 'could_not_verify'. However, it does not name alternative tools or explicitly state when not to use it, so it falls 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.