Data Providence

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

Annotations declare readOnlyHint, idempotentHint, etc. The description adds value by noting default model (Workers AI Llama) is free, _apiKey passed to Anthropic (BYO key), and return structure (per-model + combined). 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?

Two sentences front-loaded with core purpose and output. Second sentence covers details efficiently. Every sentence adds value; 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?

Despite no output schema, the description summarizes return structure (per-model + combined). Covers all parameters, required fields, use cases, and cost implications. Complete for a moderate-complexity tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context: default model behavior, _apiKey usage, and purpose of 'context' parameter for disambiguation. Exceeds baseline with useful extra meaning.

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

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

The description uses specific verbs ('Probe', 'score') and clearly defines the resource ('LLMs') and output ('visibility (0-100) per model'). It distinguishes from siblings like 'ask_pipeworx' (specific dataset) and 'scan_competitor_ai_presence' (focused on competitors).

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

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

Explicitly states use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Also explains when to provide _apiKey (for Anthropic probing). Lacks explicit 'when not to use' but provides clear context.

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

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

Beyond annotations declaring read-only/idempotent, the description reveals routing across 5,529 tools and 1,455 sources, automatic argument filling, stable pipeworx:// citation URIs, 'one fast call' performance, and live news coverage.

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 longer than average, it fronts the core directive and uses examples and clear alternative pointers. Slight redundancy (news mentioned twice) but each section serves a distinct role.

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?

Fully positions the tool within its ecosystem: describes what it does, what it returns, when to use alternatives, and the breadth of domains. With no output schema, it adequately specifies return type as structured answer with citations.

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

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

Input schema covers all six parameters (question plus aliases) at 100%. The description adds realistic examples and clarifies the natural-language nature of the main parameter, complementing the schema without redundancy.

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

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

The description clearly states the tool answers factual questions by routing to verified data sources and returning structured answers with citation URIs. It distinguishes itself 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?

Explicitly says 'PREFER OVER WEB SEARCH', provides trigger phrases like 'what is', 'look up', and tells when to step up to ask_pipeworx_grounded for hallucination-resistant answers or deep_research for broad multi-part questions.

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

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

Beyond annotations, the description discloses that it is an experimental edge with candidate routing improvements, that no candidate is currently active, and that it currently matches ask_pipeworx exactly. It also clarifies that there is no fallback—it is a full working router. This adds meaningful behavioral context.

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

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

The description is well-structured and front-loads the key fact that it's a beta version. While it is somewhat long, each sentence adds relevant information about the experimental nature, current state, and usage. It earns a 4 for being efficient without being overly verbose.

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 what the tool is, its experimental state, how to use it, and what response shape to expect (same as ask_pipeworx). Given the absence of an output schema, the description sufficiently explains the tool's behavior and integration context.

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

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

The input schema provides 100% description coverage for the 'question' parameter and all aliases, so the schema already carries the semantic burden. The description adds no additional parameter-specific detail, warranting the baseline score 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 clearly states this is a beta version of ask_pipeworx, a universal router that takes questions and routes them across 5,529 tools. It explicitly distinguishes itself from the stable ask_pipeworx and the grounded variant, making the tool's 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?

It provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing'. It also explains the experimental context and comparison against the stable router, giving the agent clear conditions for when this tool is appropriate.

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

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

The description discloses key behavioral traits beyond the annotations: it returns a structured result with evidence and refusal reasons, lists specific refusal reasons, and mentions the cost of an extra LLM call. It also explains the constraint of using ONLY the tool result, which adds significant context. No contradiction with the readOnly/idempotent annotations is present.

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 the ideal two-sentence example but every sentence provides necessary information: purpose, routing, extraction behavior, return format, refusal cases, use guidance, and cost tradeoff. It is front-loaded with the core purpose and structured logically. Slightly verbose, hence a 4 rather than 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 there is no output schema, the description thoroughly explains the return structure, including success fields and the explicit refusal format. It also covers complexity, use cases, and cost considerations. The description is fully complete for an AI agent to understand the tool's behavior and output without needing external documentation.

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 required parameter 'question' is described in the input schema, including all aliases. The description does not add parameter-specific details, but since the schema already documents them fully, a baseline score of 3 is appropriate. The description's mention of 'question' in natural language is redundant but harmless.

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

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

The description opens with a specific verb+resource: 'Hallucination-resistant answer mode for high-stakes reads,' and clearly explains the tool's function: routing to the appropriate tool, fetching data, and extracting an answer with evidence. It also distinguishes itself from the sibling ask_pipeworx by noting the extra LLM call and identical routing, making the purpose unambiguous.

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

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

The description explicitly states when to use the tool: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and provides a direct alternative: 'prefer ask_pipeworx for casual lookups.' This gives clear usage context and exclusions, satisfying the requirement fully.

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 read-only, idempotent, and non-destructive. Description adds extensive behavioral details: fan-out logic, resolver contract, parent_event extractor, news fallback, safety checks for low-confidence, closed markets, wide spreads, and cancellation rules. Far exceeds annotation burden.

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 very long and dense with detailed sections. While well-organized with all-caps section markers and clear labeling, it could be pruned for an agent. However, every sentence appears to earn its place given the complexity of the 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?

Given the tool's complexity (multiple categories, response shapes, edge cases), the description is extremely complete. Covers resolver confidence, parent events, news fallback, safety mechanisms, cancellation rules, and more. No output schema, so description carries full burden.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. Description adds substantial context: explains market parameter accepts slug/URL/text, depth has quick/thorough with defaults, and include_raw explains when to use true vs false. Clearly adds value beyond schema.

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

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

Description clearly states it researches Polymarket bets by pulling Pipeworx data in one call. Accepts slug, URL, or question text. Returns evidence packet and market-vs-model comparison.Distinguishes itself among many siblings by being the dedicated bet research 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?

Explicitly lists use cases like 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides extensive examples of fan-out per category and when certain fields are relevant. No explicit when-not, but the guidance is thorough.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. Description adds critical details: company data includes latest 10-K revenue/net income/cash/debt with off-calendar handling, drug data includes FAERS counts, FDA approvals, trial counts. Results sorted by primary metric. 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?

While packed with useful information, the description is slightly verbose. However, it is well-structured with examples and clear instructions, earning its length. Minor nit for conciseness.

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

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

No output schema exists, but description explains returns (paired data + citation URIs). Covers key use cases and data sources. Could mention pagination or edge cases, but overall adequate 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 both parameters described. Description adds context: enum values 'company'/'drug', array constraints (2-5 items), and examples (tickers for company, drug names). Exceeds 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 tool performs side-by-side comparisons of 2-5 companies or drugs, with specific data sources (SEC EDGAR for companies, FAERS/FDA for drugs). It distinguishes from sibling tools like entity_profile by emphasizing parallel lookup over sequential.

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 'ALWAYS PREFER over sequential single-pack lookups' and provides example queries ('compare X and Y', 'which is bigger'). Gives clear context for when to use this tool versus alternatives.

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

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

Annotations already declare read-only, non-destructive, idempotent. Description adds value by listing returned fields and usage hint for resource_id, going beyond annotation basics.

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 efficient sentences, front-loaded with action and results. Every word adds value, no repetition 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?

Combined with annotations and full schema, description fully covers purpose, inputs, output hints, and next step. No gaps for a search tool.

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

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

Schema covers all parameters with 100% description coverage, so description need not add much. Baseline 3 is appropriate; description doesn't enhance parameter meaning.

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

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

The description clearly states the tool searches a specific open data catalog by keyword, with precise verb+resource+scope. It distinguishes from 25+ sibling tools as a focused dataset search.

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

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

Describes return fields and next step (pass resource_id to query/metadata). Missing explicit when-not-to-use or alternative tools, 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?

Beyond annotations (readOnly, idempotent), the description discloses substantial behavior: it returns a findings packet with verbatim evidence, confidence, source, fetched_at, fetchable pipeworx:// citations, explicit gaps[] for unanswered facets, and contradictions[] for standard/thorough. It also mentions 'never invented' data, latency (15-60s up to ~90s), and depth-dependent hops. No contradiction with annotations.

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

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

The description is long but every sentence contributes operational value, front-loading account requirements and key alternatives. Some redundancy exists with the schema's depth explanation, but overall it is organized 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?

Despite lacking an output schema, the description thoroughly explains return format (findings packet, gaps[], contradictions[], hop field, citation_uri), timing, account requirements, and use-case fit. It leaves no major operational gap for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and the schema already explains both parameters in detail (depth enum values, question free text). The description restates depth behavior and the paid plan, but adds no new parameter-specific semantics 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 states a specific action: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It explicitly distinguishes itself from siblings by saying 'this is NOT open-web search' and naming ask_pipeworx for single lookups and current-news topics, making the tool's identity clear.

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

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

The description gives direct when-to-use advice: 'Best for broad/multi-part questions over structured data' and explicitly exclusions: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also instructs signed-out users to use ask_pipeworx, covering prerequisites and alternatives.

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

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

Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) indicate safe, read-only behavior. The description reinforces this by stating it 'returns' tools and 'no second schema lookup needed,' implying no mutations. It adds value beyond annotations by detailing the return format (names, descriptions, full schemas with examples) and indicating results are directly callable.

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: opens with purpose, lists use cases, describes return, and ends with usage guidance. It is slightly verbose (e.g., listing many domains), but each sentence contributes value. No redundancy with schema, and front-loaded with the core action.

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 fully explains what is returned: top-N tools with names, descriptions, full input schemas, and curated examples. It also clarifies that results are ready to call without additional lookups. This is sufficient for an agent to understand the tool's capability and output format.

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

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

Schema coverage is 100% with clear property descriptions for 'query', 'q', 'task', etc. The description does not add significant new parameter meanings, though it provides natural language examples and confirms alias usage. Since the schema already covers semantics fully, a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, FDA drugs, etc.) and distinguishes it from siblings by emphasizing it returns top-N tools with full schemas, ready to call. This differentiates it from other search/tool-lookup tools like datasets or query.

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

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

Explicit guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Also lists when to use ('when you need to browse, search, look up, or discover what tools exist for...') and provides examples. No exclusionary statements, but the 'FIRST' directive implies priority over other 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 indicate read-only, open-world, idempotent, non-destructive. Description adds crucial behavioral details: fans out across multiple sources, returns specific fields, notes patents API sunset and soft-fail behavior. 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?

Description is relatively long but well-structured: starts with query examples, then function, then output details, then limitations. Could be slightly more concise, but 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 no output schema, description thoroughly explains return fields (CIK, filings with URIs, fundamentals, patents, news, LEI) and covers limitations (patents soft-fail, name restriction). Complete for a complex tool with no 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 well-described parameters. Description reinforces that value can be ticker or zero-padded CIK, and names are not supported. Adds clarity beyond the schema, though baseline is high due to good schema descriptions.

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

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

Description clearly states the tool's purpose: generating a holistic cross-source profile of US public companies. Provides specific query examples and distinguishes from alternative tools like resolve_entity for name resolution. Differentiates from sibling tools by explicitly recommending this over chaining single-source lookups.

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

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

Explicitly states when to use (holistic company view) and when not to use (names not supported; use resolve_entity first). Mentions soft-fail for patents API. Lacks explicit alternatives for other siblings like compare_entities, but context is clear enough.

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

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

Annotations already declare destructive and idempotent hints. The description adds context on what is deleted but does not disclose additional behavior like error handling or side effects. Moderate added value over 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 waste. Action verb first, usage guidance, and sibling references all efficiently included.

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?

Simple tool with one parameter, annotations covering destructive/idempotent, and no output schema. The description fully informs the agent when and how to use the tool.

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

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

Schema coverage is 100% and already describes 'key' as 'Memory key to delete'. The description repeats 'by key' without further detail, adding minimal 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 specifies the verb 'Delete', the resource 'previously stored memory', and the method 'by key'. It clearly distinguishes from sibling tools '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?

Explicit usage scenarios given: stale context, task done, or clearing sensitive data. Pairing with remember/recall is mentioned. No explicit when-not-to-use, but the positive cases are 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?

The description adds significant context beyond annotations: it explains the process (fetches page, extracts title/description/links) and output format. No contradictions with annotations.

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

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

The description is a single paragraph of about four sentences, front-loaded with the main action. Every sentence is informative and 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?

Given low parameter count, full schema coverage, and rich annotations, the description is complete. It explains the output format (text blob) sufficiently for a tool with no 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%. The description adds detail beyond schema: default max_links (25) and maximum (50), and clarifies that url is the site to summarize. This adds value.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the output format and use cases. It uses a specific verb and resource, and distinguishes from sibling tools.

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

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

The description explicitly lists three use cases: indexing a client's site, drafting for own project, auditing competitor. While it doesn't state when not to use, the context is clear and provides good 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 read-only, idempotent, non-destructive. Description adds return fields and caller scoping, which is useful but not essential 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 filler: purpose, return values, and usage guidance included 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 the simple tool with optional parameter and no output schema, the description covers all necessary behavioral and usage aspects.

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

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

Schema covers the only parameter completely (100%). Description does not add extra meaning beyond implying 'active' default, so baseline score 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 it lists the caller's active subscriptions and specifies the returned fields. It distinguishes from sibling tools like subscribe/unsubscribe.

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

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

Explicitly advises using this tool to review subscriptions before adding more or to find an ID to cancel, providing clear context.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, indicating a safe, idempotent read operation. The description adds value beyond these by specifying the exact output details (columns, types, row count, category, last-updated), giving the agent a precise expectation of what data will be returned without needing to invoke the tool. This is useful behavioral context.

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

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

The description is a single, well-structured sentence that front-loads the key action and resource. Every word is informative, including the example and the list of metadata attributes. There is no redundancy or irrelevant information, making it efficient and easy to parse.

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 required parameter, no output schema), the description is fully complete. It explains what the tool does, what the input is (with an example), and what the output contains. There are no gaps, as the annotations cover safety and idempotency. The description alone is sufficient for an agent to understand and 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?

The input schema has 100% parameter description coverage, with a clear description for 'resource_id'. The description provides an example ('vank-fyx9'), which adds context but does not introduce meaning beyond the schema. Since the schema already documents the parameter adequately, the description's contribution is marginal, warranting a baseline score 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 clearly states the tool retrieves schema and metadata for a Providence Open Data dataset, using the specific verb 'Get' and naming the resource. It lists specific attributes (columns, types, row count, etc.) and provides an example resource_id, leaving no ambiguity about its function. It also differentiates from siblings like 'datasets' by focusing on metadata retrieval.

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

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

The description provides clear context and an example, but does not explicitly state when to use this tool versus alternatives. It does not offer exclusion criteria or mention other tools that might be more appropriate for similar tasks, such as 'datasets' tool. This lack of comparative guidance limits its utility for tool selection.

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

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

The description discloses behavior beyond annotations: the claim_token flow for later retrieval, the daily rate limit ('5 per identifier per day'), and that it is 'Free; doesn't count against your tool-call quota.' Annotations only state non-read-only and non-destructive, so this context is genuinely additive.

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 each sentence earns its place, covering purpose, usage, exclusions, token mechanics, and rate limits. It is front-loaded with the purpose and could be slightly better structured with clearer paragraph breaks, but it avoids redundancy and 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?

The description covers all relevant context: when to use, when not to use, how to provide feedback, what the claim_token does, rate limits, and cost/free status. No output schema exists, but the description explains the return token sufficiently. It is complete for a feedback-reporting tool with moderate 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%, satisfying the baseline of 3. The description adds further value by advising how to structure the message ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt') and by clarifying the claim_token usage pattern, moving it above baseline.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This clearly states the tool's purpose and distinguishes it from siblings like ask_pipeworx, which is for asking questions rather than submitting feedback.

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

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

It provides explicit when-to-use scenarios ('Use when a tool returns wrong/stale data... when a tool you wish existed isn't in the catalog... or when something worked surprisingly well') and an explicit exclusion ('ONLY for tools served by this Pipeworx connection... file it with that server instead'). This leaves no ambiguity about when to invoke 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 declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds self-aggregating signal from CF analytics, no PII, and caching details (5min-1h). 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?

Concise, front-loaded with key output, then use cases, then technical details. Every sentence is informative with zero 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 simple tool (1 param, no output schema, rich annotations), description fully covers what it returns, how to use, caching, and privacy. 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?

Single parameter 'window' with enum values. Description adds meaning beyond schema by explaining the trade-off between short and long windows. Schema coverage is 100%.

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 over a recent window. It distinguishes itself from siblings by focusing on real-time usage by other AI agents.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) and guidance on window selection (shorter for hot, longer for steady-state).

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds significant behavioral context: Jaccard similarity threshold (≥0.30), partition placeholder filter (>20% placeholder returns null), live CLOB depth fill check (realizable_edge_pp ≤ 0 means don't trade). 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?

Well-structured with clear sections for each mode, but somewhat verbose. Essential information is present and front-loaded, but some redundancy could be trimmed.

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

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

Despite no output schema, the description details response structure (opportunities[], partition_check, fill check fields). However, it doesn't list all possible sub-fields comprehensively, leaving minor gaps for an agent.

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

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

Schema coverage is 100% with meaningful descriptions. Description adds rich context: examples of event slugs ('fed-decision-may-2026'), topic seed questions ('Fed rate decision'), and behavior details for each parameter.

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

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

The description states a specific verb ('find') and resource ('arbitrage opportunities on Polymarket') with clear methods ('monotonicity violations + partition-sum checks'). It distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on arbitrage detection.

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 guides when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Also provides when-not-to-trade guidance via fill check and refers to polymarket_fill_risk for custom sizing.

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 traits beyond annotations, including caching (cached 1h at KV level keyed on knobs), model families and their details, tradeable-edge knobs, response diagnostics explaining empty segments, and why Fed bets are excluded. This adds significant value over annotations (readOnlyHint, etc.) with no contradiction.

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

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

The description is front-loaded with purpose but becomes very verbose with technical details on model families, knobs, and diagnostics. While every sentence adds value, its length could overwhelm an agent; more structured formatting would improve conciseness.

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

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

Despite no output schema, the description explains the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics) and key fields (edge_pp_net, kelly, etc.). It covers filter skips and segment emptiness. However, a high-level summary of the exact output format is slightly lacking.

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

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

Schema description coverage is 100% with thorough parameter descriptions in the schema. The tool description does not significantly enhance parameter meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price, with the explicit purpose of 'what should I bet on today'. This distinguishes it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker by focusing on model-driven and structural arbitrage opportunities generated by Pipeworx data.

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

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

The description provides strong context on when to use the tool (discovering betting opportunities without paging hundreds of markets) and explains exclusion of Fed bets from ranking with reasoning. However, it does not explicitly state when not to use it or mention alternatives among siblings beyond the implicit scope.

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 and idempotentHint. Description adds critical behavioral details: limitations (60-day TTL), decay computation from daily closes, response structure with tracked/expired/snapshot_dates, and sign conventions. 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 detailed and well-structured with clear sections. Every sentence adds value, though it is slightly long. Could be more tightly organized (e.g., bullet points) but maintains readability.

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

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

Despite no output schema, description fully documents the response structure (tracked, expired, snapshot_dates) with field details, limitations, and computation notes. Very comprehensive.

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. Description adds context: default and max for days, default for window, and explains the role of window as 'snapshot family'. This aids 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?

Description explicitly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and is clearly distinct from sibling tools like polymarket_edges or polymarket_arbitrage.

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

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

Description provides context on when to use (e.g., differentiating a fresh edge from an old one) but does not explicitly name alternative tools or state when not to use. Still, the usage 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?

While annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, the description adds rich behavioral context: it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warns about forced_directional_risk. This goes well beyond the annotations, giving the agent a thorough understanding of the tool's behavior.

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

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

The description is lengthy but well-structured, with clear sections for single-market and basket modes, and uses capitalization for emphasis. Every sentence adds value given the tool's complexity, though it could be slightly more concise without losing detail.

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 comprehensively explains return values for both modes, including fields like verdict, capture_ratio, profit_usd, thin_legs, and forced_directional_risk. It also covers edge cases and provides enough context for the 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 description coverage is 100%, but the description adds significant value: it explains that size_usd in basket mode is 'settlement notional S (shares per leg; each share pays $1),' and that side auto-defaults based on partition sum for baskets. This contextualizes parameters beyond their schema definitions, especially for the basket mode.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket), making it easy to understand the tool's scope and distinguish it from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the rationale (theoretical overround is not capturable, partial basket fills cause unhedged directional positions), 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 declare readOnlyHint, openWorldHint, idempotentHint true. The description adds extensive behavioral detail: compatibility flags, temporal alignment, skipped pairs, and leg-level pricing. This goes well beyond the annotations, fully disclosing the tool's behavior and limitations.

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

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

The description is verbose but well-structured: purpose first, then modes, then response fields and safety notes. It front-loads key information. While some details could be delegated to output schema, the density is justified by the tool's complexity.

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

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

Given no output schema, the description comprehensively explains the response structure (leg-by-leg prices, top_spreads_pp, safety fields like compatibility_warning, temporal_alignment, skipped counters). It covers all necessary context for a tool of moderate 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, but the description adds value by explaining the two modes, listing all 10 topic shortcuts, and explaining that explicit tickers override the mapped side. This clarifies parameter usage 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 defines the tool as a cross-venue spread calculator between Kalshi and Polymarket. The verb 'spread' and resource 'cross-venue' are specific. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on inter-venue differences.

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

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

The description explains two modes (topic shortcuts or explicit tickers) and provides guidance on when spreads are meaningful, including compatibility warnings and temporal alignment checks. It warns that pre-mapped topics may not yield tradeable spreads. However, it does not explicitly mention when to avoid using this tool or suggest alternative 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 indicate read-only, idempotent, non-destructive behavior. The description adds the nuance of SoQL clauses without leading $ and confirms return format as JSON, providing useful context beyond annotations.

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

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

Two sentences: first introduces purpose with example, second details parameters and output. No extraneous text; efficient and front-loaded.

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

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

Covers the core functionality, parameter usage, and return format. Could mention default limit (schema covers it) but otherwise complete for a query tool without 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 good parameter descriptions. The description adds critical detail about omitting the '$' prefix in SoQL clauses, which is not in the schema, and clarifies the purpose of each parameter class.

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 runs a SoQL query against a Socrata dataset, specifies the resource_id format, and lists the filter parameters. It distinguishes itself from the 'datasets' sibling tool which lists available datasets.

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 querying data but does not explicitly state when to use this tool versus alternatives like 'datasets' for listing. No exclusion criteria or context are provided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so description adds scoping context ('Scoped to your identifier...') which goes beyond annotations. 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 concise with three sentences, no redundant information, and front-loads the core action. 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 simple parameter set and rich annotations, the description covers purpose, usage, and scoping well. It omits explicit error behavior (e.g., if key not found), but the use case is straightforward.

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 description adds practical nuance: omitting key lists all keys, and keys are saved via remember. This adds value beyond the bare 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 verb 'retrieve' or 'list' and the resource ('value previously saved via remember' or 'all saved keys'). It distinguishes from sibling tools like 'remember' and 'forget' by explicitly mentioning pairing.

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 concrete examples of when to use (e.g., 'the user's target ticker, an address, prior research notes') and context ('look up context the agent stored earlier... without re-deriving it from scratch'). Does not explicitly mention when not to use or alternatives, but the pairing with remember and forget is implied.

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

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

Annotations declare readOnlyHint=true, implying no side effects, but the description states setting mark_read:true flags events as read, a state mutation. This contradicts the annotations. Additionally, the description lacks clarity on other behavioral aspects like rate limits or data freshness.

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

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

The description is three sentences, front-loaded with purpose, and each sentence adds necessary context. No redundant or unnecessary information.

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

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

Given 5 optional parameters and no output schema, the description covers purpose, filtering, mark_read behavior, polling suitability, and alternative access. It mentions return fields but lacks explicit structure of the response, which is acceptable for a feed tool.

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

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

Schema description coverage is 100%, providing baseline 3. The description adds value by explaining the effect of mark_read and unread_only in the context of tracking read status, and gives an example for type filtering. This slightly exceeds the 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 tool pulls fired events from a subscription feed, specifying the data elements (source, citation_uri, raw payload). It distinguishes itself from siblings like list_subscriptions by focusing on event retrieval and providing filtering options.

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 filtering by type and since, and the mark_read flag for pagination. It mentions the same feed is available via REST for scripts/dashboards, providing an alternative usage context. However, it does not explicitly state when not to use this tool versus siblings.

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

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

Discloses fan-out to multiple sources, GDELT→GNews fallback, USPTO soft-fail condition, and return structure with citation URIs. No contradiction with annotations (readOnlyHint, idempotentHint).

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

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

Well-organized with examples at the start, then technical details. Slightly verbose but every sentence adds useful information.

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

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

Given the tool's complexity (multi-source, fallback, soft-fail, various inputs, no output schema), the description covers all behavioral aspects 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 already covers all parameters with 100% description coverage. Description adds value by explaining type enum limitation, providing concrete examples for since, and clarifying value accepts ticker or CIK.

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

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

The description clearly states it's a change feed for a company covering SEC filings, news, and patents. It includes example query patterns and explicitly distinguishes itself from sibling tool entity_profile.

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 guidance on when to use this tool ("What's new" queries) and when to use entity_profile instead (static profile). Also explains date formats and typical monitoring values.

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 write operation (readOnlyHint=false) and idempotent (idempotentHint=true). Description adds retention details: authenticated users get persistent memory, anonymous 24h. 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 purpose. Every sentence adds value without redundancy. Clear, succinct, and well-organized.

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

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

For a 2-param tool with no output schema and annotations present, the description fully covers storage scope, duration, and usage pattern. No gaps remain.

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

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

Input schema covers both key and value with descriptions. The description adds naming conventions for keys (e.g., 'subject_property') and clarifies value can store any text, slightly enriching 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 saves data for reuse across conversations/sessions, with specific examples (ticker, address, preference). It distinguishes from siblings like recall and forget.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and provides after-actions: pair with recall to retrieve, forget to delete. No ambiguity about when to use.

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

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

Beyond the read-only and idempotent annotations, the description reveals that internal cascading calls occur, unresolved identifiers are listed under 'unreserved' rather than omitted, and LEI/FIGI enrichment degrades gracefully if upstream services are unavailable. These are valuable behavioral traits not visible from annotations alone.

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

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

The description is longer than average but front-loaded with example queries and a clear purpose statement. It is well-structured with supported types and parentheses. Every sentence adds useful context, though the density of details (source labels, graceful degradation, cascading) makes it somewhat heavy.

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 having no output schema, the description explains what identifiers are returned for each type, how unresolved identifiers are handled, and what happens when upstream services are unavailable. It covers both company and drug flows, input formats, and ownership details, making it highly self-sufficient for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage with detailed examples for both parameters (type enum and value format). The description reiterates the same information (ticker, CIK, name; brand/generic) without adding new semantic distinctions, so the baseline 3 is appropriate.

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

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

The description opens with concrete example queries and states clearly: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from sibling tools by focusing on identifier lookup rather than comparison or profiling, making the purpose unmistakable.

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

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

Explicit guidance is provided: 'Use FIRST whenever you have a name but need an ID.' The description also gives example use cases and notes that it replaces multiple manual lookups. However, it does not explicitly say when not to use it or name alternative tools for exclusion, so it falls slightly short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent. Description adds that it internally calls 'ai_visibility_check' per entity and ranks results, providing behavioral insight beyond annotations.

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

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

Two sentences, front-loaded with purpose, then details. Every sentence is informative with no redundancy.

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

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

Despite no output schema, description fully covers return values (ranked list with score, confidence, signal density). Inputs, process, and outputs are all 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, baseline 3. Description adds meaning: entities are brand/business names, first is subject; context disambiguates common names. This adds value over schema alone.

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

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

Description clearly states verb 'Compare', resource 'AI visibility across multiple entities', and distinguishes from sibling 'ai_visibility_check' which checks single entities. It specifies output: ranked list with score, confidence, signal density.

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

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

Explicitly states use case ('competitive AI-marketing audits') with an example question. Implicitly distinguishes from single-entity check, but does not explicitly list when not to use or provide alternative 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, and destructiveHint. The description adds valuable behavioral details: fans out to two services, returns a summary block with specific fields, mentions possible 5-30s delay for bundlephobia first measurement, and describes graceful partial failure behavior.

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

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

Despite its length, every sentence serves a purpose. The description is front-loaded with the main composite check purpose, followed by use cases, return format, and caveats. No redundant information.

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

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

The description comprehensively covers what the tool does, what it returns, limitations (NPM only, bundlephobia first-measurement delay), and partial failure behavior. With no output schema, it adequately describes return values.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: version defaults to latest, and scoped packages are accepted. This provides useful clarification.

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 a composite check for evaluating npm packages, fanning out to deps.dev and bundlephobia. It specifies the verb 'scan' and resource 'dependency', and distinguishes from siblings by noting that other ecosystems are handled by deps.dev:version directly.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also advises that for non-NPM ecosystems, users should use deps.dev:version directly, providing clear guidance on when to use versus alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows it's safe and idempotent. The description adds important behavioral details: truncation at 200K chars with flag, embedding model, chunking over 500-char windows, and output format (passages with offsets and scores). 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 relatively concise given the amount of useful information. It front-loads the core purpose and usage, then adds technical details. A slight reduction in length could improve conciseness, but the structure is effective.

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 tool has no output schema, but the description fully explains the return value (top-N passages with character offsets and similarity scores). It covers all necessary context: pairing with sibling tool, embedding model, chunking strategy, character limit, and truncation behavior. Complete for the tool's complexity and lack of 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%, so the parameter descriptions are already present. The description adds operational context (e.g., max chars for text, natural-language query examples) and explains the output format, which indirectly adds parameter meaning. However, the parameter descriptions themselves are not significantly enhanced 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 performs semantic search inside a fetched record, specifies the use case (when record is too large for prompt), and contrasts with sibling tools like ask_pipeworx_grounded. It includes technical details (BGE-base-en, cosine, 500-char windows, 200K char cap) that precisely define the tool's functionality.

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 ('when the record is too big to cram into the prompt') and provides alternative pairing with ask_pipeworx_grounded. The description gives clear context for when this tool is appropriate versus alternatives.

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

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

Beyond annotations (readOnlyHint=false, idempotentHint=true, etc.), the description adds crucial behavioral details: OAuth requirement, anonymous/BYO limitations, type-specific parameters, delivery channels with constraints (phone verification, daily caps, webhook HMAC signing, auto-disable after failures). 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 relatively concise given the detailed information it conveys. It is front-loaded with the main purpose, followed by requirements and type-specific details. Could be slightly more structured (e.g., bullet points) but 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 complexity (3 params, nested objects, no output schema), the description is highly complete. It covers return value ('Returns the new subscription id'), all supported types, delivery channels, constraints, and failure behavior. No gaps remain.

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

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

With 100% schema coverage, the baseline is 3, but the description significantly enriches parameter understanding by providing concrete examples for each type (e.g., sec_8k items, polymarket_edge topic, fred_series series_id) and detailed delivery channel specifications (E.164 format, email validation, webhook signing).

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 creates a proactive monitoring subscription to a live-data event stream, a specific verb-resource combination. It clearly distinguishes from sibling tools like 'unsubscribe' and 'recent_alerts' by focusing on creation and listing supported 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 provides clear context for using the tool (to set up proactive monitoring) but does not explicitly discuss when not to use it or mention alternative sibling tools like 'list_subscriptions' or 'unsubscribe' for comparison.

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

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

Annotations already indicate readOnly, openWorld, idempotent, not destructive. The description adds that it returns 'category-bucketed example questions with the exact tool + argument shape drawn from the live catalog', which goes beyond the annotations.

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

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

The description is somewhat long listing many categories, but it is front-loaded with example queries and structured. Every sentence adds value, though it could be slightly more concise.

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

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

For a tool with no output schema, the description explains the return value (category-bucketed example questions with tool shapes) and covers both invocation modes (no args vs topic). It is complete for its purpose as an onboarding tool.

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

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

Schema coverage is 100% with a clear description of the 'topic' parameter. The description gives examples like 'finance, pharma, betting' which matches the schema's enum list, but does not add new meaning beyond what the schema already provides.

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

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

The description clearly states this is the onboarding entry point for a new agent, answering 'what can I ask?'. It distinguishes itself from sibling tools like ask_pipeworx by specifying its role as a discovery tool for example questions and tool shapes.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also provides options: no arguments for full spread, or topic to focus. No explicit when-not-to-use, 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?

The description adds significant context beyond annotations: ownership enforcement, soft-delete behavior, and historical event availability via recent_alerts, while annotations provide idempotent and non-destructive hints 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 purpose, no unnecessary 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?

For a simple tool with one parameter, no output schema, and good annotations, the description covers ownership, deactivation, and historical data retention completely.

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 does not add new details about the single 'id' parameter beyond what the schema already provides (uuid from subscribe).

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', which is specific and distinct from siblings like 'subscribe' or 'list_subscriptions'.

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

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

It explains ownership enforcement (can only cancel own subscriptions) and that the row is deactivated not deleted, but does not explicitly contrast with alternatives beyond stating ownership constraint.

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

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

Annotations already declare readOnly/idempotent/non-destructive behavior, satisfying the safety profile. The description goes further by explaining failure semantics: could_not_verify means the check did not happen and carries verification_error, unsupported means no source covers the claim, and both must be interpreted differently from confirmed/refuted. 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 lengthy but information-dense; every sentence contributes (examples, routing logic, return structure, failure modes, efficiency). It is front-loaded with query patterns and follows a logical outline, though it could be tightened without losing 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?

There is no output schema, but the description compensates by enumerating the verdict values, stating the return includes the actual value with pipeworx:// citation and reasoning, and detailing error handling for could_not_verify. This gives enough context for an agent to invoke the tool and interpret results correctly.

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

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

Input schema has 100% description coverage, so the baseline is 3. The description adds meaningful nuance for tolerance_pct, explaining it overrides the claim-wording-implied tolerance and recommending 1–2% for hallucination detection. This goes beyond the schema's simple type/range 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?

The description opens with natural-language query patterns ('Is it true that…' / 'fact check') and clearly states the core function: natural-language claim verification against authoritative sources. It differentiates from siblings by noting it replaces 4–6 sequential calls and by routing company-financial claims vs. other claims to different pipelines.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives concrete guidance on when the structured SEC EDGAR path is used versus the grounded pipeline, and clarifies the important distinction between could_not_verify and unsupported verdicts, helping callers avoid misusing results.

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