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 and idempotentHint=true, and the description adds valuable context: it routes to a dynamic pool of tools, fills arguments, returns pipeworx:// citation URIs, and works on every tier. It does not contradict annotations and goes beyond them to explain the routing mechanism and speed of a single call.

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

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

The description is longer than average but every sentence serves a purpose—establishing preference, listing use cases, giving examples, and distinguishing from siblings. It is front-loaded with the 'PREFER OVER WEB SEARCH' directive and structured logically with 'START HERE' and 'Step up only when needed' transitions.

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

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

For a broad query tool with no output schema, the description is remarkably complete: it explains the routing behavior, citation URIs, and example queries across domains. It also relates to sibling tools and covers fallback scenarios, making it fully adequate for an agent to select and invoke the tool.

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

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

Schema description coverage is 100% as the 'question' property lists aliases (query, q, prompt, text, input) and the required parameter is clear. The description does not add additional parameter-level semantics beyond examples, so with high schema coverage 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 clearly states the tool answers factual questions about current/historical data by routing to 5,344 tools across 1,393 sources, returning structured answers with citations. It uses specific verbs like 'routes', 'returns', 'fills arguments' and explicitly positions itself as the default entry point, distinguishing it from siblings like ask_pipeworx_grounded and 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?

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases like 'what is', 'look up', 'find'. It also names alternatives for specific cases—ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions—giving clear exclusions.

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

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

Annotations already declare readOnly, non-destructive, and idempotent hints, so the safety bar is lowered. The description adds rich behavioral context: the live nature of candidate routing experiments, that no candidate is currently active, and that it falls back to nothing (full working router). This exceeds annotation coverage and provides clear expectations.

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

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

The description is composed of four sentences, each carrying essential information: identity, current state, usage, and contrast with the stable version. While somewhat more verbose than the minimal high-quality example, every sentence earns its place 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?

Given the tool's experimental nature, the description fully covers what it is, its current behavior, how to use it, and what to expect in terms of response shape. It also clarifies it is a full working router, not a proxy, which is essential context for an experimental tool 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?

Schema coverage is 100% with the question parameter and its aliases fully documented. The description only says 'same arguments' which adds no new parameter-level meaning beyond the schema, 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 clearly states what the tool does: it is the beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by noting the experimental routing improvements, and even its current exact match state.

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

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

It explicitly says to use it like ask_pipeworx when you want the newest routing, and implies the alternative of using the stable router. It also notes that results are compared against the stable router to decide merges, providing clear context for when to select this beta tool.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description reveals extraction-only behavior, evidence verbatim quote, and refusal reasons including not_in_source, no_tool_match, tool_error, data_truncated, llm_error. It also discloses the extra LLM call cost and outcome structure.

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

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

The description is information-dense but well-structured: purpose, process, output contract, use cases, and cost tradeoff each get one focused segment. No sentence is redundant.

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

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

Given the absence of an output schema, the description fully specifies return values on success and failure, and covers behavioral constraints and routing. It also positions this against ask_pipeworx, making selection context 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% with the single question parameter and alias list thoroughly documented. The description doesn't add parameter-specific details but doesn't need to; the schema fully covers meaning, so baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and details the extraction process, clearly distinguishing from ask_pipeworx by emphasizing grounded answers and explicit refusals. It names the exact function and scope, differentiating it from siblings by comparing routing and cost.

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

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

Explicitly tells when to use: 'whenever an answer will be quoted, cited, or acted on' and lists example domains. It also provides an exclusion: 'prefer ask_pipeworx for casual lookups' due to extra LLM call, and references same routing as ask_pipeworx.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds no extra behavioral context (e.g., rate limits, authentication details) beyond the safety profile, which is acceptable given the annotations.

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

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

The description is a single concise sentence that front-loads the purpose and key return fields. No wasted words; efficient and clear.

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

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

Given the tool's simplicity (2 required parameters, rich annotations, and an output schema indicated by context signals), the description covers all necessary context: what it does, what it returns, and an example. 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 clear descriptions for both parameters (symbol, _apiKey). The description reiterates the symbol usage with an example but adds no new semantic information beyond the schema, warranting the baseline score.

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 gets balance sheets for a symbol, returning specific fields like assets, liabilities, equity, cash, and debt. It distinguishes from sibling tools (e.g., av_earnings, av_income_statement) that focus on other financial data.

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

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

The description implies usage for balance sheet data but does not specify when to use quarterly vs annual periods or when to prefer this over alternatives like av_overview. No explicit guidance on context or exclusions.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds value by detailing the output fields (OHLCV) and the range of data ('recent days or full 20+ year history'), which are not captured in annotations. This is useful context beyond structured 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 two sentences, front-loaded with the action verb 'Get', and includes a concrete example. Every word adds value, with no redundancy or filler.

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

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

Given the existence of an output schema (covering return values), annotations (covering safety and idempotency), and fully described parameters, the description is largely complete. It covers the essential purpose, example, and data range. Minor omission: no mention of market coverage (e.g., US stocks only) but not critical for core functionality.

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 parameter descriptions are fully provided in the schema. The description adds an example symbol and clarifies 'full 20+ year history' for outputsize, but does not introduce new parameter semantics beyond what the schema already offers. Baseline of 3 is appropriate.

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

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

The description clearly states it retrieves daily stock price history for a symbol, with an explicit example ('AAPL') and specifies the returned fields (open, high, low, close, volume). This distinguishes it from sibling tools like av_quote (current price) and av_balance_sheet (financial statements).

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?

While the purpose implies usage for obtaining historical daily prices, there is no explicit guidance on when to use this tool vs. alternatives (e.g., av_quote for current price, av_earnings for earnings data). The description neither states when-not nor names specific 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 mark it as readOnly and idempotent. The description adds beyond annotations by specifying the exact return fields (reported EPS, estimated EPS, surprise amount, surprise percentage). This provides valuable behavioral context without contradicting the annotations.

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

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

The description is a single, information-dense sentence with no unnecessary words. It front-loads the purpose and includes concrete examples and expected output.

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 existence of an output schema, the description sufficiently explains the tool's inputs and outputs. It could mention the data source (Alpha Vantage), but the _apiKey parameter makes that implicit. Overall adequate for the tool's simplicity.

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

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

Schema coverage is 100% with both parameters documented. The description adds an example symbol and hints at output fields, but does not elaborate on the _apiKey parameter beyond its basic description. The value added is marginal 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 action ('Get'), the resource ('quarterly earnings data'), and provides a concrete example symbol. It distinguishes itself from sibling tools like av_balance_sheet and av_income_statement by focusing specifically on earnings data.

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

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

The description implies usage when quarterly earnings data for a symbol is needed, but does not explicitly discuss when not to use it or mention alternative tools. The context is clear enough for most cases.

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 a safe read operation (readOnlyHint, idempotentHint, not destructive). The description adds behavioral context by naming the specific financial metrics returned and the time frame (annual/quarterly). No contradictions with annotations.

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

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

The description is a single sentence that efficiently conveys the core purpose, scope, and output. No redundancy or unnecessary words.

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

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

For a simple tool with two parameters and an output schema, the description adequately specifies the inputs (symbol example) and outputs (key metrics). It covers the essential aspects needed for an 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 the description does not need to add parameter details. It mentions the symbol example but does not add new meaning beyond the schema. The description compensates slightly by describing the return values, but that is not directly parameter semantics.

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

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

The description clearly states the verb 'Get', the resource 'income statements', and specifies the scope ('annual and quarterly') and key metrics returned ('revenue, gross profit, operating income, net income, and EBITDA'). It effectively distinguishes from siblings like av_balance_sheet and 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 implies usage for retrieving income statement data for a given symbol and lists the returned metrics, making the context clear. However, it lacks explicit when-to-use or when-not-to-use guidance, especially in comparison to sibling tools for balance sheets or 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 declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. Description adds value by listing the specific returned fields (sector, market cap, ratios, etc.), which is not in the schema. 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?

Single sentence that efficiently conveys purpose and output content. No redundant words; every part earns its place.

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

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

For a simple 2-parameter tool with output schema present, the description covers the main return values. Minor gaps like error handling or data freshness are not critical given the low complexity and annotations.

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

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

Input schema documents both parameters with descriptions (symbol example, _apiKey purpose). Schema coverage is 100%, so description adds no extra parameter semantics beyond the example usage in the 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 uses clear verb 'Get' and resource 'company fundamentals' with specific data fields listed (e.g., market cap, P/E). Distinguishes from sibling tools like av_balance_sheet, av_earnings, av_quote by focusing on a comprehensive fundamentals overview.

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

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

No explicit guidance on when to use this tool vs alternatives (e.g., av_quote for price only, av_earnings for earnings history). The description is self-contained but doesn't help the agent decide between similar 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, idempotentHint, destructiveHint. Description adds return format but no additional behavioral traits beyond what annotations provide. 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?

Single sentence front-loading purpose, followed by return fields. No extraneous information. Efficient and scannable.

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 read-only tool with full schema coverage, annotations, and output schema, the description covers essential aspects. Could mention need for API key but that's in 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?

Schema coverage is 100% with descriptions for both parameters. Description provides an example pattern but does not add substantial meaning beyond schema. Baseline 3 is appropriate.

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

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

Description explicitly states verb 'Get', resource 'real-time stock price', and lists return fields. Among sibling Alpha Vantage tools, this is the only one for quotes, so it is well-distinguished.

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

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

No explicit when-to-use or alternatives mentioned. However, the name and description imply usage for real-time price queries, making it adequate but lacking direct sibling comparison.

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

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

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?

The description adds substantial behavioral context beyond the annotations (readOnlyHint, openWorldHint). It discloses the account/paid-tier requirement, parallel decomposition across 5,344 tools, the inclusion of gaps[] for unanswered facets ('never invented'), latency ranges, and the semantic excerpting behavior. These details go far beyond the bare read-only/open-world 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 and dense, but every clause contributes useful information, and critical details are front-loaded (account requirement and fallback). The single-paragraph structure makes it somewhat hard to scan, and the contradictions[] behavior is mentioned twice, which is redundant. Still, it is far from bloated and the density is justified for a complex 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?

Despite lacking an output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], and contradictions[] for specific depths. It also covers latency expectations, authority/logo, and the tool's behavior on out-of-catalog topics. This is a complete picture for an agent to decide when and how to invoke the tool.

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

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

The input schema already covers both parameters at 100% with detailed depth descriptions. The tool description reinforces that 'broad/multi-part is fine' for the question parameter and links depth:'thorough' to a paid plan, adding practical context. It does not introduce new syntax but enriches the meaning by explaining how depth choices map to research behavior in the context of gaps and contradictions.

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 specific function: 'Grounded multi-source research across Pipeworx's 1393 STRUCTURED data sources... in ONE call'. It explicitly differentiates from siblings by noting 'this is NOT open-web search' and contrasts with ask_pipeworx for single lookups or current news. The verb-plus-resource scope is unmistakable.

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

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

Usage guidance is explicit with alternatives: 'Best for broad/multi-part questions over structured data' and for single lookups 'use ask_pipeworx'. It also provides a specific fallback when not signed in ('use ask_pipeworx instead') and warns against using deep_research for breaking/current news, stating such topics yield 'mostly empty gaps[]'. This is actionable and comprehensive.

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?

Annotations declare readOnlyHint, openWorldHint, etc. The description adds context beyond annotations: it fans out across multiple sources, mentions the USPTO sunset soft-fail, limits on filings (up to 5 with URIs), sorted fundamentals, and fallback mechanisms. No contradictions.

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

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

The description is appropriately sized for the complexity—neither too terse nor verbose. It is front-loaded with query examples, then lists return components. Every sentence adds value, explaining behaviors and constraints efficiently.

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 broad scope (multiple data sources, many return fields) and no output schema, the description is remarkably complete. It covers inputs, processing, output structure, edge cases, and fallbacks, providing an agent with everything needed 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%. The description explains both parameters in detail: type is limited to 'company', value expects ticker or zero-padded CIK, and explicitly states names are not supported. This adds meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call'. It provides numerous example queries ('Tell me about X', 'research Acme', etc.) and lists the data sources and return fields, distinguishing it from siblings like 'resolve_entity' and 'compare_entities'.

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

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

Explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also advises using 'resolve_entity' first if only a name is available, clarifying when not to use this tool.

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

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

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

Beyond annotations (which declare no read-only or destructive behavior), the description adds critical behavioral details: rate-limited to 5 per identifier per day, doesn't count against tool-call quota, and the team reads digests daily affecting the roadmap. 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 moderately sized but well-structured with a clear lead sentence and subsequent guidelines. Every sentence adds value, though it could be slightly more concise without losing critical context.

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

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

Given no output schema, the description adequately explains the feedback lifecycle, rate limiting, and roadmap impact. Required parameters are fully documented, and nested objects are explained. 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% but the description adds meaningful usage context for each parameter, such as explaining each enum value in detail and advising against pasting end-user prompts. This enhances understanding beyond the 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 explicitly states the tool sends feedback to the Pipeworx team for bugs, missing features, data gaps, or praise. It uses specific verbs and clearly differentiates from any sibling tool by being the only feedback mechanism.

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 when-to-use scenarios (bug, feature, data_gap, praise) and explicit guidance: describe in terms of Pipeworx tools/packs, don't paste end-user prompts. Also mentions rate limits and that it's free.

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 indicate readOnly and idempotent, but the description adds substantial context: it explains the internal logic (two modes), the safety fields (compatibility_warning, temporal_alignment), and the conditions under which spreads are meaningful or not. It fully discloses behavioral quirks, such as why many pre-mapped topics return warnings, exceeding what annotations alone 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 well-organized: purpose, modes, response, safety fields. It uses bold headers ('TWO MODES', 'RESPONSE', 'SAFETY FIELDS') for clarity. Every sentence adds information; there is no repetition or fluff. However, the length could be slightly trimmed for agents that prefer brevity, so not a perfect 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's complexity (two modes, multiple safety flags, response structure), the description is remarkably thorough. It covers the input parameters, the output format (leg-by-leg prices, top spreads, compatibility fields), and edge cases (temporal misalignment, shape mismatches). No output schema exists, so the description bears the full burden for return values, which it satisfies comprehensively.

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 value by enumerating the 10 valid topic values, explaining that explicit parameters override topic-mapped values, and providing examples. This goes beyond the schema's simple type descriptions, justifying a higher score.

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 clear verb+resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It details two specific modes (topic shortcuts and explicit tickers) and distinguishes the tool from siblings like polymarket_arbitrage by focusing on the same question across venues. The purpose is unambiguous and well-defined.

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 the tool (to compare prices across venues) and provides guidance on interpretation, including warnings about compatibility. It does not explicitly contrast with sibling tools, but the context of cross-venue spread vs. single-venue tools is implied. The inclusion of 'Real cross-venue spreads are rarer...' sets appropriate expectations.

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?

Annotations declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context: each call cascades through multiple lookup endpoints internally, and it details the return fields and citation URIs per entity type.

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

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

The description is well-structured with a brief introductory sentence, followed by bullet points for each supported type. It is concise yet comprehensive, with no unnecessary words.

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

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

Despite lacking an output schema, the description fully explains the return values (ticker, CIK, company name, RxCUI, etc.) and includes citation URIs. It covers all necessary aspects for correct 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%. The description enriches parameter semantics by explaining that 'value' can be a ticker, CIK, or name for companies, and brand or generic name for drugs, with concrete examples.

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

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

The description clearly states the tool resolves a user-spoken name to a canonical identifier, with specific examples ('What's the ticker for...') and supported types. It distinguishes itself from siblings as the only resolver 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 says 'Use FIRST whenever you have a name but need an ID,' providing clear guidance on when to employ this tool. It also explains that it replaces 2-3 manual lookups, which reinforces its utility.

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 provide readOnlyHint, openWorldHint, idempotentHint. The description adds detailed behavioral context: internal routing for financial vs. other claims, exact math for financials, verdict types, and citation format. No contradictions.

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

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

The description is a single paragraph that is information-dense and front-loaded with examples. It is slightly long but every sentence adds value; could be broken into shorter sections for clarity.

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

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

Given the lack of output schema, the description thoroughly explains the return format (verdict, value with citation, reasoning) and covers inputs and behavior. 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%, and the description adds significant value beyond schema descriptions, especially for tolerance_pct: explains range, overriding default, and use cases.

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

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

The description clearly states that the tool performs natural-language claim verification against authoritative sources, distinguishing between company-financial and other factual claims. It lists example queries and specifies the return 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?

The description explicitly says to use whenever checking factual correctness of a user's statement, but does not provide explicit when-not-to-use guidance or list alternatives among siblings.

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