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 readOnly/openWorld/idempotent/non-destructive, so the bar is lower. The description adds meaningful behavioral context: works on every tier, one fast call, returns stable citation URIs, routes to live news. It doesn't cover rate limits or auth, but that's acceptable given annotations. No contradiction.

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

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

Though long, every sentence earns its place: purpose, triggers, examples, hierarchy, excuses. The description is front-loaded with the key directive (PREFER OVER WEB SEARCH) and organized logically.

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 open-ended query tool, the description covers scope, input style, output format (citations), special cases (breaking news), and tier/performance expectations. With rich annotations and schema, nothing critical is missing.

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

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

Schema coverage is 100% with all aliases documented. The description provides illustrative examples but does not add technical detail beyond the schema. Since the schema already explains the parameter well, a baseline of 3 is appropriate; not higher because description repeats the same conceptual 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 uses a clear verb ('Routes', 'returns structured answer') and resource (a meta-tool that dispatches to 5,462 tools). It explicitly names alternates (ask_pipeworx_grounded, deep_research) and provides concrete examples, fully distinguishing it from siblings.

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

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

Gives explicit when-to-use triggers ('what is', 'look up', 'get the latest') and when-to-step-up guidance for grounded/deep_research, plus special handling for breaking news. This is exemplary usage guidance beyond just 'use for factual questions'.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds that no candidate is currently active, making it identical to ask_pipeworx, and clarifies it does not fall back to anything—it is a full working router. This extra context about the experimental state and lack of fallback is valuable 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?

The description is a few sentences long, front-loaded with the main purpose, and each sentence provides essential context (beta status, current state, usage direction, no-fallback guarantee). Slightly verbose but efficient for the information conveyed.

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

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

For a tool with no output schema and 6 alias parameters, the description fully explains what it does, its current state, how it relates to ask_pipeworx, and the response shape by referencing the stable version. It is complete for an agent to select and invoke it correctly.

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

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

Input schema covers all parameters with clear descriptions (each alias points to 'question'), and the question parameter itself lists all aliases. The description adds no additional parameter-level meaning, so baseline of 3 is appropriate given 100% schema coverage.

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

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

The description clearly states it is a beta version of ask_pipeworx, identical in functionality (same 5,462 tools, arguments, response shape) but with candidate routing improvements. It distinguishes itself from the stable sibling and specifies its role as a universal router.

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

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

It explicitly says to use it exactly like ask_pipeworx when wanting the newest routing, and notes results are compared against the stable router. While it doesn't explicitly exclude use cases for ask_pipeworx_grounded, the context of experimental edge vs stable provided enough 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds substantial behavioral detail: it describes the refusal mechanism with specific refusal_reason enums (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), the structured return format on success, and the extra LLM call cost. This goes well beyond the annotations, giving agents a clear picture of the tool's behavior under various conditions.

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 appropriately sized given the tool's complexity, front-loading the core purpose ('Hallucination-resistant answer mode') before detailing the return format, refusal reasons, and cost trade-off. Each sentence earns its place: purpose, mechanism, output schema, refusal behavior, use cases, and cost comparison. It is dense but well-structured and not padded.

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

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

Since there is no output schema, the description fully explains the return structure, including the success shape and refusal shape with refusal_reason values. It also covers the high-stakes context, the relationship to ask_pipeworx, and the performance/cost trade-off. No critical information is missing for an agent to decide whether to invoke it and interpret the result.

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

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

Schema coverage is 100%, with all six parameters documented as aliases for 'question', and the question parameter has a clear natural language description. The tool description does not add additional parameter-level semantics, but given complete schema coverage, the baseline of 3 is appropriate. The description does not need to compensate for missing schema info.

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 'Hallucination-resistant answer mode for high-stakes reads' and specifies that it 'EXTRACTS the answer using ONLY what the tool result contains.' This clearly states the tool's function and differentiates it from sibling ask_pipeworx by emphasizing groundedness and evidence. It also explicitly contrasts with ask_pipeworx, making the purpose unmistakable.

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

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

The description gives explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also states when not to use it: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.' This provides clear when-to-use and when-not-to-use instructions, fully satisfying the dimension.

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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses extensive behavioral traits: account requirements, paid depth levels, structured-data-only scope, gap[] handling, iterative re-querying behavior, contradictions[] in standard/thorough, citation fetchability guarantees, semantic excerpting, and latency expectations. It also warns about empty gaps for current-news topics. This is far beyond what annotations provide and contains 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?

The description is long but well-structured, front-loading the account requirement and core capability before diving into nuances. Each section (use cases, iteration, citations, limitations) earns its place for a tool with this complexity. However, some redundancy exists (e.g., 'this is NOT open-web search' and later re-emphasizing structured-only), and a few sentences could be tightened without losing meaning.

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

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

Despite lacking an output schema, the description fully documents expected outputs (findings packet, evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[]) and covers edge cases like unavailable data, current-news limitations, and latency. It explains prerequisites (account, paid tier) and second-hop behavior. Given the tool's complexity, this is a complete and self-sufficient description.

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

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

The input schema covers both parameters at 100%, so the baseline is 3. The description adds significant meaning beyond the schema by explaining the depth enum's trade-offs ('quick=3 (single hop)', 'standard=5 (default; adds a gap-recovery hop...)', 'thorough=8 (paid; ...iterative hop)') and the question parameter's suitability for broad/multi-part queries. This elaboration justifies a score above baseline, though not 5 because the schema already provides clear 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 what the tool does: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call' with decomposition and parallel routing. It explicitly differentiates from siblings by saying 'this is NOT open-web search' and contrasting with ask_pipeworx. The verb+resource+scope is specific and unambiguous.

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

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

The description provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and provides direct alternatives for other cases: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also gives account-tier exclusions: 'If you are not signed in, use ask_pipeworx instead'. This fully covers usage scenarios and alternatives.

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

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

Annotations 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?

Beyond annotations, the description discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota impact ('Free; doesn't count against your tool-call quota'), and operational context ('The team reads digests daily and signal directly affects roadmap'). These behavioral traits are not present in annotations and significantly aid the agent.

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

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

The description is longer than average, but every sentence adds critical value: use cases, exclusions, behavioral expectations, and rate limits. It is front-loaded with the core purpose and structured logically. While slightly verbose, it avoids redundancy and remains readable.

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

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

Given the tool's moderate complexity (3 params, nested object) and no output schema, the description covers all needed angles: purpose, when/when not to use, parameter behavior, rate limits, and impact. The absence of output schema is immaterial because the description clearly indicates this is a submission tool, not a retrieval tool. It is fully complete.

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

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

The schema already provides 100% coverage with detailed parameter descriptions (e.g., 'bug = something broke or returned wrong data'). The description adds extra pragmatic guidance, such as 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which enriches the meaning beyond schema alone. Since the schema covers the basics, this is a solid 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly names the resource (Pipeworx team) and the actions (report bug, feature, data gap, praise), and it distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than queries.

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

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

The description provides explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection... if the tool came from a different MCP server... file it with that server instead.' This is exceptional 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?

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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds extensive behavioral context: response fields (leg-by-leg prices, matched spread, top_spreads_pp), safety fields (compatibility_warning conditions, temporal_alignment, skipped counters), and limitations of pre-mapped topics. 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 structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the core purpose. However, it is verbose with multiple sentences and lists. Could be slightly trimmed without losing clarity, but overall well-organized.

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 (cross-venue spread, multiple modes, safety checks) and lack of output schema, the description thoroughly covers parameter usage, response structure, edge cases (compatibility_warning conditions, temporal_alignment), and limitations. An agent has enough information to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds additional meaning beyond the schema: it explains the two modes, lists the 10 topic shortcuts, and clarifies that explicit tickers override mapped sides. This adds value but the schema already provides good basics.

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 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb (retrieve/compute spread) and resource (cross-venue spread), and distinguishes from sibling single-venue tools like 'polymarket_arbitrage' by highlighting the cross-venue 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?

The description explains two modes (topic shortcuts vs explicit tickers) and provides guidance on when each is appropriate. It warns that pre-mapped topics often return warnings, indicating caution. However, it does not explicitly name alternative tools or state when not to use it, though the context is sufficient for an agent.

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?

Annotations already declare readOnly, idempotent, and non-destructive, but the description adds valuable behavioral context: internal cascading through multiple lookup endpoints, auto-disambiguation, and specific citation URI formats. This goes beyond the structured 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 packed with useful information, starting with realistic user queries, then the core purpose, and then detailed type-specific behavior. Every sentence earns its place; it is front-loaded and 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?

With no output schema, the description thoroughly explains what each entity type returns (ticker, CIK, company_name; RxCUI, ingredient, brand) and includes citation URIs. It also addresses the internal lookup cascade and the tool's role as a first step, making it complete for agent use.

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 both parameters are described, meeting the baseline. The description adds extra meaning by detailing accepted input forms for each type (ticker, CIK, name; brand/generic) and the return fields, which enhances understanding beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples ('ticker', 'CIK', 'RxCUI'). It distinguishes itself from siblings like entity_profile by focusing on ID resolution and explicitly saying 'Use FIRST whenever you have a name but need an ID.'

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 provides explicit when-to-use guidance ('Use FIRST whenever you have a name but need an ID') and explains it replaces 2-3 manual lookups. It does not explicitly mention when not to use or name alternative tools, but the context is clear enough.

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

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?

The description adds significant behavioral context beyond the annotations: it explains the dual path for financial vs. other claims, the return format (verdict, actual value with citation, reasoning), and that it replaces multiple sequential calls. Annotations already indicate safe read-only, idempotent behavior, and the description aligns with 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 appropriately sized for the complexity, front-loaded with natural language triggers and examples. Every sentence earns its place, though it could be slightly more concise without losing meaning.

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

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

Given the absence of an output schema, the description thoroughly explains return values and behavior. It covers parameters, usage, internal routing, and what to expect, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving examples (e.g., 'Apple's FY2024 revenue was $400 billion') and explaining tolerance_pct's use for hallucination detection, going beyond the property descriptions.

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

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

The description clearly states the tool is for natural-language claim verification against authoritative sources, with specific verb phrases like 'Is it true that…' and 'fact check'. It distinguishes between company financial claims (SEC EDGAR + XBRL fast path) and other factual claims (grounded pipeline), differentiating it from sibling 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and provides examples. However, it does not explicitly state when not to use the tool or mention alternatives, though the sibling list suggests alternatives like 'ask_pipeworx' or 'deep_research'.

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