Alphavantage

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds important behavioral details: the scoring range (0-100), per-model return structure, cost implications for Anthropic, and the free default model. This complements the annotations without contradiction.

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

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

The description is two well-structured sentences with no wasted words. It front-loads the primary purpose and then efficiently covers key details (default model, API key requirement, return format). Every sentence adds value.

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

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

Despite lacking an output schema, the description fully explains the return format ('per-model {score, confidence, signals, raw_response} + a combined view'). Given 4 parameters with 100% schema coverage and clear annotations, the description provides all necessary contextual information for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value beyond the schema by explaining the default model, the pass-through nature of _apiKey, and the disambiguation role of context. It also clarifies the optional vs required parameters in practice.

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

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

The description uses a specific verb 'Probe' and clearly identifies the resource ('one or more LLMs') and the outcome ('score visibility 0-100'). It distinguishes itself from sibling tools by focusing on AI brand visibility checks, which is unique among tools like ask_pipeworx or deep_research.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to use the _apiKey parameter. While it doesn't state when not to use it or list alternatives, the context from sibling tools and annotations makes the usage clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context: it routes to one of many tools, fills arguments, returns structured answers with pipeworx:// citation URIs, and can answer questions that web search could also answer. This adds value beyond the annotations by disclosing the routing behavior and citation output.

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

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

The description is dense and front-loaded, starting with the most important guidance ('PREFER OVER WEB SEARCH') followed by the problem domain, routing behavior, trigger phrases, examples, and fallback routing. It is longer than ideal, but every section earns its place by either clarifying purpose or preventing misuse. Minor redundancy in the enumeration of domains and trigger phrases prevents a 5.

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

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

Given the tool has no output schema, the description does a good job explaining what the return looks like ('structured answer with stable pipeworx:// citation URIs'). It covers the input semantics completely with one required free-text question parameter. Minor gaps: it doesn't explicitly mention pagination, timeout, or error conditions, but these are less critical for a routing tool whose parameter surface is a single question string.

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

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

Schema description coverage is 100% with the question parameter fully described and aliases enumerated. The description adds semantic value by explaining what kind of questions are appropriate ('anything requiring authoritative structured data with citations') and providing examples. The description could not add much more because the schema already exhaustively documents the parameters.

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 ('routes the question'), a resource ('5,798 tools across 1517 verified sources'), and a clear scope ('current or historical data... authoritative structured data with citations'). It distinguishes itself from web search and sibling tools like deep_research and ask_pipeworx_grounded, so an agent can tell when to use it.

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 'PREFER OVER WEB SEARCH', provides trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), gives concrete examples, and names alternatives with conditions: 'use ask_pipeworx_grounded' for hallucination-resistant single answers and 'use deep_research' for broad multi-part questions. This is explicit when/when-not/alternatives guidance.

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

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

The description is highly transparent beyond the annotations: it discloses that candidate routing improvements are enabled live when under test, that none is currently active, and that this is a full working router that 'falls back to nothing.' This is valuable behavioral context that annotations (readOnlyHint, idempotentHint) do not capture, and no contradiction with annotations exists.

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

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

The description is dense but every sentence earns its place: it states what the tool is, its experimental nature, current state, usage instruction, and reassurance that it is fully functional. The key information is front-loaded with the 'Beta version of ask_pipeworx' phrase.

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 (a beta router with live-testing behavior) and simple one-parameter schema, the description covers selection and invocation well. It is slightly incomplete on return-value details because it only says 'same response shape' as ask_pipeworx, requiring the agent to look up that sibling for the concrete shape. Still, the core behavior and current state are fully conveyed.

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

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

Schema description coverage is 100%, with all six parameters documented as aliases for question. The description mentions 'same arguments' as ask_pipeworx but does not add any new parameter-level meaning beyond the schema. Per the baseline, 3 is appropriate when the schema already fully documents the parameters.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and as a universal router with identical tools, arguments, and response shape. It distinguishes it from the stable ask_pipeworx sibling, but does not state in standalone terms what action the router performs (e.g., 'answers natural-language questions by routing to 5,798 tools'), relying instead on the reader's familiarity with ask_pipeworx.

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 it: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies the current state (no candidate active, matches stable version exactly) and contrasts with the stable router for result comparison. This leaves no ambiguity about choosing between the beta and stable versions.

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

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

The description goes well beyond the annotations by detailing the exact success and refusal response shapes, the refusal reason enum, the single-source grounding constraint, and the cost tradeoff. This gives the agent a precise behavioral model of the tool's failure modes and output guarantees.

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

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

The description is dense but every sentence adds functional value: behavior, return contract, refusal semantics, usage triggers, and cost comparison. It is front-loaded with the defining characteristic and wastes no words.

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

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

For a complex tool with no output schema, the description fully covers input expectations, routing behavior, grounding constraints, result shape, refusal reasons, and when to choose a cheaper sibling. An agent has everything needed to invoke it correctly and interpret its output.

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 schema already documents the sole semantic parameter 'question' with aliases and natural-language guidance. The description does not need to add parameter detail, and it doesn't, so the 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 states a specific, distinctive purpose: a hallucination-resistant grounded answer mode that only extracts answers from tool results. It explicitly contrasts itself with ask_pipeworx, making the differentiation clear without opening the schema.

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

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

It gives explicit when-to-use guidance: use when answers will be quoted, cited, or acted on, and for high-stakes domains like financial, legal, or medical facts. It also names the alternative and when to prefer it ('prefer ask_pipeworx for casual lookups') and discloses the extra LLM call cost.

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 readOnlyHint/idempotentHint annotations: Pipeworx fronts no key, free-tier keys are refused because Alpha Vantage meters free tier by source IP rather than by key, and the call goes through a gateway. This explains a likely failure mode and is not contradicted by any annotation.

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 front-loaded sentences: purpose, returned data, and the critical auth caveat plus alternative. Every sentence earns its place, and the caveat is placed after the core purpose rather than burying it. No fluff or redundant detail in the description itself.

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

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

For a simple two-parameter tool with a rich output schema and readOnly/idempotent annotations, the description covers purpose, return contents, auth constraints, failure mode, and alternatives. Nothing needed to invoke this tool correctly 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 description coverage is 100%, so the baseline is 3. The main description largely restates the _apiKey requirement already detailed in the schema and gives an example symbol that is also in the schema examples. It adds no new parameter 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 opens with a specific verb and resource: 'Get annual and quarterly balance sheets for a symbol.' It further enumerates the returned metrics (total assets, liabilities, equity, cash, debt), which clearly distinguishes it from siblings like av_income_statement and av_earnings. The example 'AAPL' reinforces scope.

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

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

The description explicitly states the auth prerequisite (own PAID Alpha Vantage key via _apiKey) and names a keyless alternative, sec-xbrl, for US company financials. The 'Keyless alternative' sentence gives the agent a concrete fallback when no paid key is available, and the schema description reinforces this with finnhub for quotes.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context: it discloses the paid-key requirement, the gateway-level rejection of free-tier keys due to Alpha Vantage's IP-based metering, and the 'compact' vs 'full' history scope.

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 and front-loaded with the core purpose. The key-related warning is long but genuinely important for avoiding failed calls. It does not repeat every schema detail, though some of the key explanation is duplicated from the _apiKey schema description.

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 presence of an output schema, full parameter documentation, and annotations covering safety, the description is largely complete. It covers data scope, return fields, and the critical authentication constraint. A small gap is not mentioning rate limits or whether prices are adjusted for splits/dividends, but these are not essential for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents symbol, _apiKey, and outputsize well. The description adds little beyond what the schema says, so it meets the baseline but does not meaningfully expand parameter 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 states a specific verb and resource: 'Get daily stock price history for a symbol' and enumerates the returned fields (open, high, low, close, volume). This clearly differentiates it from siblings like av_quote or av_earnings.

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

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

The description clearly explains the key requirement, why free keys fail, and points to a keyless alternative (sec-xbrl). It does not explicitly compare itself to av_quote or other price-related siblings, but the scope is clear enough for an agent to choose it for daily history.

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

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

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds important context beyond that: the call goes through a gateway, Alpha Vantage meters free tier by source IP, and free keys are refused. This is exactly the kind of behavioral information an agent needs but cannot infer from 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 purpose and outputs, then supplies the critical authentication caveat and alternative. The auth explanation is somewhat long, but every part serves a real purpose: it prevents an agent from wasting a call with a free key and routes to a viable fallback.

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

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

With an output schema present and only two well-documented parameters, the description covers the core purpose, return values, auth requirements, and an alternative. It does not mention pagination or date-range behavior for the quarterly earnings, but nothing essential seems missing for selecting and invoking this tool correctly.

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

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

Schema description coverage is 100%: both symbol and _apiKey are already well documented in the input schema. The description reinforces the paid-key constraint and the alternative tool, but it does not add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get quarterly earnings data for a symbol.' It also lists the returned metrics (reported EPS, estimated EPS, surprise amount, surprise percentage), which clearly distinguishes this tool from sibling Alpha Vantage tools like av_balance_sheet, av_income_statement, and av_quote.

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: a paid Alpha Vantage key is required, a free key will be refused, and sec-xbrl is named as the keyless alternative for US company financials. This gives an agent actionable routing information for 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 the annotations (readOnly, idempotent, non-destructive), the description discloses important runtime behavior: Pipeworx does not provide a key, free-tier keys are refused through the gateway, and Alpha Vantage meters free access by source IP. It also states exactly what data the call returns, adding practical 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 well-structured sentences: the first states the tool's purpose and main output, the second covers the critical key requirement and failure mode, and the third provides a keyless alternative. No redundancy and the most important constraint is front-loaded.

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

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

The description is complete for an agent deciding whether and how to call this tool: it names the data returned, the required key type, the failure mode, and an alternative. Since an output schema exists, the lack of detailed return-value enumeration is not a 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 description coverage is 100%, and both parameters are already documented in the schema. The description restates that a paid user-provided key is required and gives an example symbol, but it does not add substantial parameter semantics beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Get annual and quarterly income statements for a symbol,' and lists the exact metrics returned. This clearly distinguishes it from siblings like av_balance_sheet and av_earnings based on the financial statement type.

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 clear context for when this tool is appropriate: when income statement data is needed and a paid Alpha Vantage key is available. It explicitly names a keyless alternative (sec-xbrl) and explains why a free key will fail, but it does not explicitly contrast this tool with sibling Alpha Vantage tools such as av_balance_sheet or av_earnings.

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 establish readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds valuable operational context: Pipeworx fronts no key, free-tier keys are refused at the gateway because Alpha Vantage meters by source IP. This is a real behavioral warning that prevents failed calls.

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

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

The description is front-loaded with the main purpose, followed by the return fields and the critical auth caveat. It is three sentences with no filler; even the longer third sentence earns its place by explaining a non-obvious failure mode and providing a fallback tool.

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 two-parameter, read-only tool with full schema coverage and an output schema, this description is complete: it lists return fields, explains the key requirement and failure mode, and names an alternative. An agent has what it needs to decide whether to call this tool and what inputs to provide.

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

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

Schema description coverage is 100%, and the schema already documents both symbol and _apiKey thoroughly, including the paid-key restriction and the free-key failure mode. The description mostly restates this rather than adding new parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Get company fundamentals for a symbol,' then lists the exact return fields (sector, market cap, P/E ratio, EPS, dividend yield, 52-week range, analyst ratings). This gives an agent a clear sense of what the tool does and is enough to differentiate it from sibling av_* tools like av_quote or av_daily even without naming 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 clearly states the paid-key requirement, explains why free keys will not work, and names sec-xbrl as a keyless alternative for US company financials. It does not, however, give explicit when-not-to-use guidance relative to specific av_* siblings such as av_daily or av_quote, so it stops just short of full exclusionary 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 cover read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: the authentication reality (paid key required, free-tier refused through the gateway due to IP metering) and the exact output fields. It doesn't fully explore error behavior or latency, but the key caveat is a meaningful behavioral disclosure.

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

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

The description is front-loaded with the core purpose and output, followed by the critical key caveat and alternatives. It is a bit long due to the detailed explanation of why free keys fail, but every sentence adds necessary information. Overall well-structured and reasonably concise for the complexity.

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

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

Given the rich annotations, complete input schema, and presence of an output schema, the description covers the remaining essential context: what the tool returns, the paid-key constraint, and alternatives when no key is available. An agent has enough information to decide whether and how to call this tool correctly.

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

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

Schema description coverage is 100%, with both 'symbol' and '_apiKey' well documented. The description reinforces the key requirement and gives one example symbol but does not add meaning beyond the schema's own detailed parameter descriptions. Baseline 3 applies because the schema carries the burden.

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

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

The description starts with a specific verb and resource: 'Get real-time stock price for a symbol.' It also lists the returned fields (current price, change, percent change, trading volume), which clarifies what the tool does. However, it does not explicitly contrast itself with the similar sibling av_daily, so it lacks direct sibling differentiation.

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 conditions: it requires a paid Alpha Vantage key and explains why a free key will be refused (source-IP metering). It also names alternatives with a clear condition: 'If you have no paid key, use sec-xbrl (keyless US financial statements) or finnhub (quotes) instead.' This is strong when-to-use and when-not-to-use guidance.

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

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

The description extensively covers behavioral aspects beyond annotations, including safety (low-confidence resolutions, closed markets, wide spreads), resolution rule risk, parent event extraction, and news fallback behavior. No contradictions with annotations (readOnlyHint, etc.). Highly transparent.

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 very detailed but somewhat lengthy. It uses sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.) for structure, but could be more concise for a quick reference. Loses some points for verbosity.

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

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

Given the tool's complexity (multiple classifier categories, fan-out patterns, response shapes, safety mechanisms), the description covers virtually all necessary context. No output schema, but response shapes are explained adequately 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% (3 parameters described), but the description adds meaning beyond the schema by explaining market input types, depth default, and include_raw's impact on response size. This adds value for agent usage.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It lists supported input types (slug, URL, question text) and describes the output (evidence packet + comparison). However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, lacking direct sibling distinction.

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 clear usage context with example queries ('should I bet on X', 'what does the data say about Y'). It implies when to use but does not explicitly state when not to use or provide direct alternative tool names. Overall, context is strong.

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, so the description's job is to add context. It specifies data sources (SEC EDGAR, FAERS), handling of fiscal years, and result sorting. 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?

Extremely concise yet packed with information. Every sentence adds value. Front-loads common query patterns and key guidance. No wasted words.

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

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

Given no output schema, the description adequately explains the return value (paired data + citation URIs) and the data sources. Covers all necessary aspects for a comparison 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?

Input schema coverage is 100%, baseline is 3. The description adds meaning by explaining what data is pulled for each type (e.g., 'for company: latest 10-K revenue + net income') and how results are sorted, which goes beyond the schema's enum and array 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's purpose: side-by-side comparison of 2-5 companies or drugs using common query patterns like 'X vs Y'. It distinguishes itself from sequential single-entity lookups, which is the main 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 says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', guiding the agent to choose this tool over single-entity tools like entity_profile for comparison tasks. Context about what data is pulled for each type further clarifies usage.

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 read-only/open-world/idempotent annotations, the description discloses gap reporting (gaps[] never invented), contradiction scanning, citation_uri fetchability, semantically excerpted records, parallel tool routing, and expected latency. This is substantial behavioral context that annotations alone do not provide.

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

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

The description is long but dense with relevant operational details: sign-in requirement, sibling fallback, source scope, return contents, depth behavior, citation semantics, excerpting, and timing. It front-loads the account gate and tool-selection advice. Minor formatting quirks and a wall-of-text style keep it from being perfectly concise.

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

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

For a complex tool with no output schema, the description covers what the agent needs: what the tool accepts, what it returns, how gaps and contradictions are handled, how citations behave, how long it takes, and which accounts/depths are allowed. No critical selection or invocation information appears missing.

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

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

Schema coverage is 100% and the depth enum already has a detailed description, so the baseline is 3. The description adds extra meaning by clarifying that thorough requires a paid plan, that standard/thorough add contradiction scans, and that the tool decomposes the question into facets. It does not fully re-document the question parameter but reinforces how it is used.

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 names a specific verb and resource: grounded multi-source research across Pipeworx's structured data sources, returning a findings packet with evidence and citations. It explicitly distinguishes itself from open-web search and names ask_pipeworx as the tool for single lookups, so an agent can tell it apart from siblings.

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

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

It gives explicit conditions: account required, fall back to ask_pipeworx if not signed in, best for broad/multi-part questions, single lookup should use ask_pipeworx. It also explains depth-tier selection (quick/standard/thorough) including the paid requirement for thorough.

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, destructiveHint), the description adds that the tool returns the top-N most relevant tools with full input schemas and examples, ready to call directly without a second lookup. This provides useful behavioral context about the output format and immediate usability.

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

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

The description is dense and front-loaded with the essential purpose. The long list of examples could be trimmed, but it effectively communicates the breadth of coverage. Every sentence adds value, and there is no fluff.

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

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

The description covers the tool's purpose, when to use it, what it returns (top-N tools with schemas), and that no follow-up lookup is needed. Given the complexity of the tool and the absence of an output schema, this is sufficient for an agent to use it correctly.

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

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

Schema coverage is 100% with all 6 parameters described. The description adds minimal extra meaning beyond the schema (e.g., mentions aliases briefly). The baseline of 3 is appropriate as the schema already does the heavy lifting.

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

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

The description uses a specific verb-resource combination ('Find tools by describing the data or task') and lists concrete examples like SEC filings, FDA drugs, etc. It clearly distinguishes from sibling tools by positioning itself as a discovery tool, not a data-retrieval tool.

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

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

The description explicitly states when to use this tool ('Call this FIRST when you have many tools available and want to see the option set') and implies when not to (if you already know the tool). It could be more explicit about exclusions, but the guidance is clear and actionable.

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

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

The description goes far beyond the readOnly/openWorld/idempotent annotations: it discloses that the tool fans out across many sources in parallel, that USPTO data soft-fails due to an API sunset, that an empty section means "no data" rather than a bug, and that a private company yields resolved:false with notes. These are exactly the behavioral traits an agent needs to interpret results correctly.

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

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

The description is long, but the tool is genuinely complex with many return sections, source services, and edge cases. It is front-loaded with usage signals and the "always prefer" instruction, and the dense semicolon-separated list of outputs earns its place. It could still be tightened with clearer visual structure, so it falls just short of a 5.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: it enumerates the result fields, notes source-specific failure modes, explains what empty sections mean, and specifies behavior for private companies. An agent has enough context to invoke the tool and interpret its output correctly in edge cases.

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

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

Schema description coverage is 100%, and both parameters are already well documented in the schema, including the fact that type/value are interchangeable and that value can be a ticker, CIK, or company name. The description repeats these examples and adds no genuinely new parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it builds a "full cross-source profile of a US public company in ONE parallel call." It is clearly differentiated from the family of single-source SEC/XBRL/news lookups by explicitly saying to prefer this tool over chaining those lookups. The opening query examples also make the intent immediately recognizable.

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

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

It gives explicit when-to-use guidance: when the user asks for a holistic view or a briefing, and it instructs to "ALWAYS PREFER" this over chaining single-pack lookups. It also notes that private companies return resolved:false with a notes line, implying the tool is for public companies, and says person/place support is coming soon, setting expectations about unsupported entity 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 destructiveHint=true and idempotentHint=true. The description adds behavioral context about clearing sensitive data and stale context, which enhances 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 with no wasted words. The action and usage are front-loaded, making it easy for an AI agent to quickly grasp the tool's purpose.

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

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

For a simple tool with one required parameter and no output schema, the description is fully adequate. It covers purpose, usage context, and relationships to sibling tools.

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 description doesn't need to add much. It doesn't elaborate on the 'key' parameter beyond what's in the schema, which is acceptable given the parameter's straightforward nature.

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') and the resource ('a previously stored memory by key'). It distinguishes itself from siblings by mentioning pairing with 'remember' and 'recall'.

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 three clear scenarios for when to use the tool: 'when context is stale, the task is done, or you want to clear sensitive data'. It also hints at alternatives by naming related tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds that it fetches the page and extracts title/description/key links, making the behavior transparent. 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 (two sentences plus a bullet list) and front-loaded. Every sentence adds value without redundancy.

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

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

With 2 parameters and 100% schema coverage, the description is sufficient. It explains the output format (single text blob) even without an output schema, and the use cases cover the tool's applicability.

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 explains both parameters. The description mentions 'any URL' and implies default max_links (25, max 50) but doesn't add significant semantic value beyond what the schema provides.

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

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

The description uses specific verbs ('generate', 'fetch', 'extract', 'emit') and clearly identifies the resource ('llms.txt file'). It distinguishes this tool from siblings by focusing on AI indexing, which is unique among the listed tools.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing...'). While it doesn't mention when not to use it, the context is clear and sufficient for most agents.

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

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

Description mentions it returns specific fields and defaults to active subscriptions. Annotations already indicate read-only, idempotent, non-destructive; description adds field list and default behavior without contradiction.

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

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

Two sentences, front-loaded with main action, no wasted words.

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

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

For a simple list tool, the description plus annotations fully cover purpose, usage, safety, and return structure. Output schema is not needed as fields are listed.

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 for the single optional parameter, so baseline is 3. Description implies 'active' as default but does not add new meaning beyond the schema parameter description.

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 explicitly states 'List the caller's active subscriptions' with a clear verb and resource. The sibling tools include subscribe and unsubscribe, making this distinct.

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?

Directly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel.' This differentiates from subscribe/unsubscribe, though it lacks explicit when-not contexts.

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?

Despite all annotations being false (offering no safety hints), the description fully discloses behavioral traits: rate limiting (5/day/identifier), no quota cost, daily digest processing, and the claim_token flow for follow-up. It also clarifies that feedback should describe Pipeworx tools, not end-user prompts, which shapes expected behavior.

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

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

The description is a dense block of text, but every sentence earns its place with specific details. It could benefit from bullet points for scannability, but the content is compact and front-loaded with the core purpose.

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

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

With no output schema, the description adequately explains return behavior (claim_token, status on resolution). It covers all parameters, usage constraints, and exclusions. For a feedback tool of this complexity, nothing essential 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%, so the schema already thoroughly documents parameters. The description adds value by explaining the claim_token lifecycle (filing without an account returns a token; later pass it back to read resolution) and by summarizing the type enum in prose, reinforcing schema semantics without redundancy.

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

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

The description opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It immediately distinguishes this feedback tool from all siblings, which are analytical or research tools, by framing it as a reporting channel for Pipeworx-specific issues.

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

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

Usage guidance is explicit and actionable. It enumerates concrete scenarios (bug, feature/data_gap, praise) and provides a clear exclusion: do not report tools from other MCP servers, with a rationale and alternative action. This is above and beyond typical 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?

Description adds details beyond annotations: no PII, derived from analytics engine, caching behavior (5min-1h). This provides rich behavioral context without contradicting annotations.

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

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

The description is concise, front-loaded with purpose, and well-structured. Each sentence adds value without redundancy. It uses bullet-like format for use cases.

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 low complexity (1 optional param, no output schema), the description fully covers what the tool does, what it returns, data source, and 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 coverage is 100% with a description for the window parameter. The description adds meaning by explaining the effect of different windows (hot now vs. steady-state), enhancing beyond the enum values.

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

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

The description clearly states the tool returns trending tools, packs, and call volume. It specifies the data items and uses specific verbs like 'Returns' and 'discovering', 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?

Three explicit use cases are listed, explaining when to use the tool. The window parameter guidance is given. However, it does not mention when not to use or provide alternatives, missing some usage 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?

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: Jaccard similarity filter, partition placeholder filter, fill check with depth analysis, and response structure. 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 comprehensive but verbose. It is front-loaded with the main purpose and then details each mode. Every sentence adds value, though some technical details could be more condensed 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 tool's complexity (multiple modes, fill check, semantic filtering) and no output schema, the description sufficiently covers behavior, safety, and expected results. It includes response structure and trade avoidance conditions. An output schema would further improve completeness.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description adds context: input examples for event slugs, acceptance of full URLs, and explanation of how topic seed question is used. Slightly more detail than 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?

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes three modes (no-args trending scan, event-specific, cross-event topic), specifying the verb 'Find' and resource 'Polymarket', and differentiates from siblings 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?

Explicit guidance on when to use each parameter: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also explains when not to trade (realizable_edge_pp <= 0). Provides clear context for each mode.

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 extensive behavioral detail beyond annotations: three model families with signal sources, caching, diagnostics structure, fed note, and calculation methodology (Kelly, slippage, edge). The description carries the full burden well.

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

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

While every sentence adds value, the description is very long and dense. It front-loads purpose well but then dives into extensive technical detail that could be structured more concisely.

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 9 parameters, no output schema, and complex behavior, the description covers all needed aspects: model families, edge calculation, knobs, diagnostics, and caching. No gaps for agent usage.

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 detailed parameter descriptions in the input schema itself. The description adds minimal parameter-specific value beyond reiterating knobs, 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?

Description clearly states the verb (Scan/discover opportunities) and resource (Polymarket markets where Pipeworx data disagrees with market price). The opening line immediately signals purpose: 'Scan top Polymarket markets and return opportunities' with the use case 'what should I bet on today'.

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 frames usage as discovery without paging hundreds of markets, and explains the caching behavior. It lacks explicit when-not-to-use guidance or direct sibling comparisons to tools like polymarket_arbitrage, but the purpose is clear enough for agents to decide.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds rich behavioral details: history depth bounded by 60-day snapshot TTL, decay based on daily closes (not intraday), and gaps in snapshots meaning no scans. 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 detailed and front-loaded with the core question, but it is somewhat verbose. However, every sentence adds value for a complex telemetry tool, so it remains 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?

Without an output schema, the description fully explains return structures (tracked[], expired[], snapshot_dates[]) and covers edge cases like gaps and TTL limits. 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?

Schema coverage is 100% with parameter descriptions. The description adds minor context (e.g., clamping range for days) but largely repeats schema info. 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: providing edge persistence and decay telemetry from daily snapshots. It answers the specific question of how long an edge has existed and whether it is shrinking, distinguishing itself from related tools like polymarket_edges.

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

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

The description provides context for when to use the tool (to differentiate between fresh and aged edges) but does not explicitly state when not to use it or list alternative tools. The context from sibling names partially covers alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds detailed behavioral traits: walks ladder, returns specific fields (top_of_book, vwap, slippage, etc.) and risk warnings. 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?

Description is long but well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET). Every sentence adds value, though slight redundancy could be trimmed. Suitable for complexity.

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

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

No output schema, but description comprehensively lists return fields for both modes, covers special cases (thin legs, forced directional risk), and gives actionable warnings. Complete for its 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?

Schema coverage is 100%, baseline 3. Description adds context beyond schema: explains defaults, how size_usd is interpreted differently for buys vs sells and basket mode, and clarifies 'auto' side logic for baskets.

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 does a realizable-vs-theoretical edge check against live order-book depth. It distinguishes single-market and basket modes and explicitly differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use it.

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 to use before acting on polymarket_arbitrage signals or trades above ~$500. Warns about partial basket fills converting arb to unhedged directional position, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already mark the tool read-only and idempotent, but the description adds substantial behavioral context: compatibility codes, unverified pairing, gross-vs-net spreads, Kalshi fee disclaimer, skipped counters, and null temporal-alignment semantics. This goes far beyond what annotations or the schema could convey.

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

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

The description is long but well structured into labeled sections (RESPONSE, SAFETY FIELDS, codes, fees, skipped counters). Each sentence carries a distinct caveat or field definition; minor tightening is possible, but the complexity justifies the length.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility fields, temporal_alignment null behavior, unmatched leg handling, and fee disclaimers. A caller has enough context to invoke the tool and interpret its response.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds valuable semantics about mode selection, how explicit ticker/slug overrides the topic-mapped side, and that both modes run the same matcher, though it leaves some combination edge cases implicit.

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?

States a specific function: cross-venue spread between Kalshi and Polymarket for the same resolving question. The description clearly distinguishes it from adjacent siblings like polymarket_arbitrage by naming the two venues and the matching/subject-alignment concern.

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

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

Provides clear context with TWO MODES: topic shortcuts for pre-mapped macros versus explicit ticker/slug pairings, and explains override semantics. It warns that pre-mapped topics are often not tradeable, but it does not explicitly contrast this tool with sibling tools or state when to prefer an alternative.

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

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

Annotations already provide readOnlyHint, destructiveHint, idempotentHint; description adds scope detail and listing behavior. 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 action, concise but includes pairing info and scoping. Could be slightly more 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?

Complete for a simple tool: explains behavior, scoping, and related tools; no output schema needed.

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 parameter description; description adds nuance about omitting key to list all keys, which is not explicitly in schema property description.

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?

Cleary states 'Retrieve a value previously saved via remember, or list all saved keys' with specific verb and resource differentiation from remember and forget 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?

Explicitly says 'Use to look up context the agent stored earlier' and pairs with remember/forget for save/delete, also notes scoping.

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 readOnly, openWorld, idempotent, and non-destructive. The description adds important behavioral detail: setting mark_read:true flags returned events as read, affecting subsequent calls. This goes beyond annotations without contradiction.

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

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

The description is three concise sentences, front-loaded with the core action. Every sentence adds value (return fields, filtering, side effect of mark_read, alternative access). No extraneous words.

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

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

With five parameters fully described in the schema, no output schema, the description covers return fields, filtering, side effects, and alternative access. This is complete for an agent to 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 parameter descriptions. The description adds minor contextual details (e.g., 'ISO timestamp' for since, 'Max events 1-200 default 50' for limit) but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed, lists key return fields (source, citation_uri, raw payload), and mentions filtering capabilities. It distinguishes itself by noting an alternative REST endpoint, providing unique context.

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 (polls work fine, returns recent alerts) and mentions an alternative method (GET endpoint). It does not explicitly contrast with sibling tools like list_subscriptions but provides sufficient guidance for typical 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 indicate read-only, idempotent, non-destructive. The description adds details on fan-out behavior, fallback from GDELT to GNews, soft-fail for USPTO, date handling, and return structure, without contradiction.

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

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

The description is a single, information-dense paragraph that front-loads example queries and is efficient. Could be slightly more structured but remains concise.

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 covers return structure (changes[], total_changes, citation URIs), all parameters, behavioral nuances, and clearly differentiates from sibling tools, making it 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?

Schema coverage is 100%, but the description adds extra context, e.g., for 'since' it explains relative shorthand and suggests '30d' or '1m' for typical monitoring, enhancing the schema's information.

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 change feed for a company across multiple sources (SEC, GDELT/GNews, USPTO) in one parallel call, and distinguishes itself from entity_profile which provides static profiles.

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 example queries and explicitly recommends using entity_profile for static profiles instead. It could be more explicit about when not to use this tool, but the context is clear.

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

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

Description adds valuable context beyond annotations: it clarifies the write nature (consistent with readOnlyHint=false), idempotency is implied (overwriting same key is safe), and non-destructive. It reveals scoping and expiration behavior, which annotations do not cover. 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?

Four sentences, each carrying essential information: core function, usage trigger, storage mechanism, persistence rules, companion tools. No redundant words. The most critical info ('Save data') is first.

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 key-value store with no output schema, the description covers all necessary context: what it stores, when to use, scope, persistence, and related tools. No gaps given 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% with descriptions for both parameters. The description adds example key formats ('subject_property', etc.) and clarifies value as free-text, which enhances meaning. Baseline 3 is elevated to 4 because the examples provide practical guidance beyond schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb and resource ('save key-value pair' is implied). It distinguishes clearly from siblings by naming 'recall' and 'forget' as companion tools, making 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?

Explicit guidance on when to use: 'Use when you discover something worth carrying forward' and what kinds of data (resolved ticker, target address, etc.). It also explains scope ('scoped by your identifier') and persistence differences between authenticated and anonymous sessions, and pairs with recall/forget.

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

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

The description goes well beyond the annotations: it discloses graceful degradation of LEI/FIGI enrichment, ambiguous-name behavior returning figi_candidates instead of asserting, explicit `unresolved` fields, source labels, and internal cascading lookups. This is rich behavioral context that the annotations alone don't provide.

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

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

The description is long, but nearly every sentence carries operational detail, and it is front-loaded with examples and the 'Use FIRST' directive. It could be more scannable with bullets or section breaks, but it is 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?

For a tool with no output schema, the description explains what gets returned, what happens when resolution is ambiguous, what happens when upstream sources fail, and how identifiers are labelled. This is sufficient for an agent to invoke it correctly and interpret results.

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?

Even though schema coverage is 100%, the description adds real semantic value: it explains that non-equity instruments resolve here, what input format is expected for bonds, that trailing security-class words should be omitted, and clarifies that ISINs resolve to legal entities. This materially improves the agent's ability to call the tool correctly.

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

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

The description clearly states a specific verb ('resolve') and resource: mapping user-spoken names to canonical/official identifiers that other tools require. It distinguishes itself from siblings by stressing it is the ID-lookup tool used before other tools, with explicit supported entity types.

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

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

It explicitly says 'Use FIRST whenever you have a name but need an ID,' which gives clear when-to-use guidance. It doesn't explicitly name alternatives or situations where a sibling tool like entity_profile should be used instead, so it earns a 4 rather than a 5.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining that it probes each entity with 'ai_visibility_check', ranks results, and returns a list with score, confidence, and signal density. This behavioral context goes beyond the annotations without contradicting them.

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

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

The description is four sentences long, with the most important information front-loaded. Each sentence adds distinct value: purpose, method, use case, and output. There is no unnecessary repetition or fluff.

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

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

Despite lacking an output schema, the description explicitly defines the return value as a 'ranked list with score, confidence, signal density per entity', which is sufficient for an agent. The tool's complexity (4 parameters, one required) is well-covered by the schema and description together.

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

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

The input schema already describes all four parameters with 100% coverage. The description adds important semantic context for the 'entities' parameter, clarifying that the first entry is treated as the 'subject' and the rest as competitors. This extra detail justifies a score above the baseline of 3.

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

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

The description uses a specific verb ('Compare AI visibility'), identifies the resource ('multiple entities side-by-side'), and clearly states the outcome ('ranks by score, surfaces most/least recognized'). It differentiates itself from its sibling 'ai_visibility_check' by emphasizing the multi-entity comparison aspect.

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

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

The description explicitly states the tool is 'useful for competitive AI-marketing audits' and provides an example question, giving clear context for when to use it. It implies it should be used instead of the single-entity 'ai_visibility_check' when comparing multiple entities, but does not explicitly list alternatives or 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 indicate read-only, open-world, idempotent, non-destructive. Description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will list timeouts. 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 detailed but every sentence provides value. Well-structured: purpose, usage, output, caveats. Could be slightly more concise, but it's clear and informative.

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

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

Given the tool's complexity (composite call, multiple data sources, partial failures), the description covers key aspects: output format, ecosystem, limitations, and graceful degradation. No output schema, but return values are described adequately.

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 for both parameters. Description adds minimal extra context (e.g., scoped packages accepted, version defaults to latest). This is baseline for high schema coverage.

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

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

The description clearly states the tool's purpose: a composite check for 'should I add this npm package' across deps.dev and bundlephobia. It specifies the output summary block and ecosystem (NPM). No sibling tool has similar purpose, so differentiation is strong.

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 to use when an agent asks about safety, popularity, size, or cost. It also mentions ecosystem limitation (NPM only) and fallback for other languages. Does not explicitly state when not to use, but context is clear.

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

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

Description adds behavioral details beyond annotations: uses BGE-base-en embeddings + cosine over 500-char overlapping windows, 200K char cap with truncation flag, and passages carry offsets for verification. No contradiction with annotations.

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

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

Six sentences in a single paragraph, each serving a purpose: main action, examples, use case, pairing advice, technical details, constraints. No redundancy.

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

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

For a semantic search tool with good annotations and full schema coverage, the description covers purpose, usage context, alternative, behavior, output elements (passages with offsets and scores), and constraints (char limit, truncation). Missing output schema is compensated by clear 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?

Schema coverage is 100%, so baseline is 3. Description adds minimal extra context: explains text as previously fetched document, gives query examples. Implementation details (embeddings, windows) are not parameter-specific.

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 semantic search inside a fetched record, giving concrete examples like SEC 10-K body or article. It distinguishes from siblings by emphasizing it's for large documents that don't fit the prompt, and pairs with ask_pipeworx_grounded for grounding.

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: 'when the record is too big to cram into the prompt' and provides an alternative workflow with ask_pipeworx_grounded. Clearly explains the value proposition.

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 behavioral traits beyond annotations: persistent nature, OAuth requirement, delivery channel limitations, webhook auto-disable, and signing secret. Annotations indicate idempotency and open world hint, but the description does not explicitly address idempotency or extra response fields, though the open world hint is consistent with possible undocumented response fields.

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

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

The description is dense with information but remains front-loaded with the main purpose. It uses a clear list-like structure for types and delivery channels, though slightly verbose. No redundant sentences.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description covers all essential aspects: subscription types, parameter syntax, delivery options, constraints, and post-creation behavior. Missing explanation of return value format beyond ID is acceptable without an output schema.

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

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

The input schema has 100% coverage with descriptions for all parameters and nested fields. The description adds significant value with concrete examples for each subscription type and detailed delivery channel options (e.g., webhook HMAC signing, SMS verification), going well beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription, lists supported event types with examples, and mentions it returns a subscription ID. It differentiates from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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 specifies when to use (to create persistent subscriptions), prerequisites (Pipeworx OAuth account), and delivery options with constraints (SMS cap, phone verification). It implicitly distinguishes from siblings by focusing on creation, but does not explicitly state when not to use or direct to alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so the safety profile is clear. The description adds valuable behavioral context: the tool returns categorized examples with exact tool calls, drawn from a live catalog. This explains what the agent will receive 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 longer but well-structured: starts with example queries, explains output, then usage, then when to use. It is front-loaded with the core purpose. Minor redundancy (e.g., listing all categories) could be trimmed, but overall it is appropriately sized and 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 simplicity (1 optional param, no output schema), the description is fully complete. It explains the input, output (category-bucketed examples with tool calls), usage modes, and when to use. No gaps remain for effective utilization.

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 of the `topic` parameter. The description adds meaning by explaining that omitting the parameter gives a cross-category spread and by listing example values like 'finance', 'pharma'. This provides practical guidance beyond the enum-like list.

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 an onboarding entry point, lists example queries, and explains it returns category-bucketed example questions with tool+argument shapes. It distinguishes from siblings like ask_pipeworx by positioning itself as the first tool to use when the agent doesn't know what Pipeworx can do.

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 when to use this tool: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the two usage modes (no arguments or with topic). It does not explicitly state when not to use, but the guidance is clear and actionable.

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

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

Goes beyond annotations by disclosing that the row is deactivated, not deleted, and that historical events remain available via 'recent_alerts'. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). Adds significant 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, front-loaded with the main action, no wasted words. Every sentence adds value.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage condition, behavioral side effects, and links to related tool 'recent_alerts'. Fully sufficient for correct selection and invocation.

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

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

Schema coverage is 100% with clear description. The description adds extra context that the id is 'returned by subscribe', which helps the agent understand parameter provenance. This exceeds the schema's 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 the action ('Cancel a subscription by id.'), specifying the verb (cancel) and resource (subscription). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by implication, and adds ownership enforcement detail.

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

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

Provides clear usage context: ownership is enforced, so only own subscriptions can be canceled. This tells the agent when it's appropriate to use. Does not explicitly mention alternatives or when not to use, but the condition 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 declare readOnly, openWorld, idempotent, non-destructive. The description adds crucial behavioral context: the meaning of could_not_verify (check did not happen, not evidence), unsupported (no source found), return of citations and reasoning, and the two routing paths. This goes well beyond annotation hints.

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

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

The description is long but every sentence carries information: examples, purpose, routing logic, return values, and critical edge-case semantics. It is front-loaded with the core purpose and well-organized, though slightly dense for a casual reader.

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, but the description fully explains the verdicts, the difference between could_not_verify and unsupported, the citation and reasoning, and the two processing pipelines. It covers potential pitfalls and the tool's scope, making it complete for its 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% with full descriptions for both claim and tolerance_pct. The description does not add extra parameter-specific meaning beyond the schema; it only references the verification process generally. 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 identifies the tool as a natural-language claim verification against authoritative sources, with explicit verbs ('verify', 'fact check', 'confirm or refute'). It distinguishes itself from siblings by focusing on fact-checking and even differentiates two internal paths (SEC EDGAR for financial claims vs grounded pipeline for others).

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains when the structured financial path applies versus the general grounded path, and notes that it replaces 4–6 sequential calls, giving strong contextual guidance.

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