Brave Search

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 crucial details: default free model, requirement of _apiKey for Anthropic with direct billing, and per-model return structure. 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?

Three sentences, front-loaded with core purpose, followed by key defaults and use cases. Every sentence is informative without redundancy.

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

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

Given no output schema, the description adequately explains return values (per-model {score, confidence, signals, raw_response} + combined view). It covers all behavioral aspects and use cases, making the tool self-contained.

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

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

Schema coverage is 100% with clear descriptions for all 4 parameters. The description adds value by explaining the default model, the role of _apiKey, and the purpose of context, going beyond the schema alone.

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

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

The description clearly states the verb 'probe' and the resource 'LLMs for visibility scoring (0-100) per model'. It distinguishes itself from sibling tools like ask_pipeworx or scan_competitor_ai_presence by specifying its unique output and use case.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. It does not explicitly state when not to use the tool or mention alternatives, but the context implies differentiation from sibling tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it explains that the tool routes to downstream tools, fills arguments automatically, returns citations, works on every tier, and is a single fast call. This gives the agent a clear behavioral model without contradicting annotations.

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

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

The description is dense but well-organized, front-loading the most critical instruction ('prefer over web search') before explaining behavior, examples, and escalation paths. Every sentence serves a purpose, and the length is justified given the router's broad scope.

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

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

Given the tool's complexity and absence of an output schema, the description is remarkably complete. It explains return format (structured answer with citation URIs), usage boundaries, sibling distinctions, example inputs, and even tier compatibility. An agent has enough context to select and invoke the tool correctly in most situations.

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 every parameter documented as an alias for the natural-language question. The description reinforces what kind of questions are appropriate with examples, but it does not add substantial parameter-level meaning beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it routes a natural-language question to one of 5,581 tools across 1,463 verified sources, fills arguments, and returns structured answers with pipeworx:// citation URIs. It also differentiates itself from siblings like ask_pipeworx_grounded and deep_research, so an agent can tell them apart.

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

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

The description explicitly says to prefer this over web search for factual questions, calls it the default entry point, and gives concrete step-up guidance for when to use ask_pipeworx_grounded or deep_research instead. It also provides examples of triggering phrasings and domains, leaving little to inference.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description adds valuable operational context: that it's the experimental edge, currently has no active candidate, matches ask_pipeworx exactly, and that results feed merge decisions. This goes beyond the structured annotations and helps the agent understand the tool's current behavior and lifecycle.

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 efficient, roughly four sentences that all carry information. It front-loads the beta relationship and usage, then clarifies it's fully operational. There is slight redundancy in repeating 'identical' and 'exactly,' but overall it is well-structured and free of 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?

For a complex universal router with no output schema, the description adequately covers purpose, current state, relationship to siblings, and usage guidance. It explains that the response shape matches ask_pipeworx, which suffices. It lacks explicit examples or edge-case handling, but the core information needed to invoke it correctly is present.

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

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

The schema covers 100% of parameters, including detailed descriptions for the aliases. The description merely states 'same arguments' without adding new semantic meaning, so it relies on the schema for parameter interpretation. This meets the baseline for high schema coverage, but no extra value is added.

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 beta variant of ask_pipeworx, a universal router with 5,581 tools, and explicitly states it is currently identical to the stable version. It distinguishes itself from the sibling ask_pipeworx (stable) by labeling itself as the experimental edge, giving the agent a precise understanding of what it does and how it relates to alternatives.

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 instructs to use it exactly like ask_pipeworx when the newest routing is desired and notes that results are compared against the stable router to guide merges. While it doesn't explicitly say 'don't use this for production' or list exclusions, the experimental label and comparison mention convey that stable should be preferred for reliability. This provides clear context for usage.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds substantial beyond-annotation context: the exact success return shape, the explicit refusal shape with enumerated refusal reasons, verbatim-quote evidence, and the extra LLM-call cost. No contradiction exists between description and 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?

Every sentence earns its place: purpose, mechanism, return/refusal contract, usage policy, and cost trade-off. It is front-loaded and structured so an agent quickly learns what the tool is and when to pick it.

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 — routing across 5,581 tools and 1463 sources — and no output schema, the description fully compensates by detailing return values, refusal reasons, evidence behavior, cost, and the comparison to ask_pipeworx. Nothing needed for correct invocation or selection is missing.

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

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

Schema coverage is 100%: the question parameter and all five aliases are fully documented in the schema. The description does not add parameter-level semantics beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a distinct purpose — "Hallucination-resistant answer mode for high-stakes reads" — and then explains the extraction-on-tool-result-only mechanism. It explicitly differentiates from ask_pipeworx by grounding and refusal behavior, so an agent can distinguish these siblings without inspecting schemas.

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

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

It gives explicit when-to-use guidance: any time an answer will be quoted, cited, or acted on, and when the agent must not invent facts (financial/legal/medical/public statements). It also names the alternative and the cheaper default: "prefer ask_pipeworx for casual lookups."

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

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

The description is highly transparent about the tool's behavior. It explains the fan-out mechanism per category, response shapes, resolver contract with confidence levels, parent event extraction, news fields with fallback handling, safety short-circuits, and cancellation rule parsing. Annotations (readOnlyHint, idempotentHint, etc.) are consistent with the described read-only, idempotent research operation. 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 well-structured with clear sections (RESOLVER CONTRACT, PARENT_EVENT EXTRACTOR, NEWS FIELDS, etc.) and begins with a concise summary. While it is lengthy, every paragraph adds necessary detail for safe and effective tool use. A minor improvement could be trimming some redundant explanations (e.g., the blocking mechanism for closed markets), but overall it earns its length.

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

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

Given the tool's complexity (3 parameters, no output schema, many siblings), the description is exceptionally comprehensive. It covers input resolution, fan-out logic per category, response structure, edge cases (low confidence, closed markets, wide spreads), cancellation rules, and even response size considerations. This completeness enables an agent to use the tool correctly without guessing.

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

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

The input schema covers all three parameters with descriptions, achieving 100% coverage. The description adds significant value: examples for 'market', explanation of 'depth' values ('quick' vs 'thorough' with source counts), and context for 'include_raw' (summarized vs full payloads). This enriches the schema beyond basic type/constraint info.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the action (research), resource (Polymarket bet), and method (pass slug, URL, or question text). It also distinguishes itself from sibling tools by providing use cases like 'should I bet on X' and listing classifiers and examples, making it unique among the many related tools.

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

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

The description explicitly lists use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides guidance on when to inspect output fields (market_match_confidence) and describes blocking conditions (low-confidence short-circuit, closed markets, wide spreads). While it doesn't explicitly compare to siblings, the given use cases and blocking conditions offer clear usage 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, destructiveHint. The description adds valuable behavioral context: off-calendar fiscal years handled correctly, results sorted by primary metric, returns paired data with citation URIs. 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 front-loaded with query examples and gets to the point quickly. It is slightly long but every sentence provides useful information. No filler or redundancy.

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

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

Given no output schema, the description compensates by explaining return format (paired data + citation URIs) and sorting behavior. It handles complexity like off-calendar fiscal years and explains the tool replaces 8–15 lookups, making it complete for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the enum values (company vs drug), specifying input formats (tickers/CIKs for companies, names for drugs), and noting min/max items. It also clarifies that results are sorted by primary metric.

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. It provides specific example queries and distinguishes from sibling tools by explicitly preferring this over sequential lookups. The verb 'compare' and resource 'entities' are precise.

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

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

The description gives clear usage context: use when comparing entities, prefer over sequential lookups. It also explains what each entity type pulls. However, it does not explicitly state when not to use or list alternative tools for specific scenarios.

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

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

The description is notably transparent about tool behavior: it states the read-only nature (returns a findings packet, no mutations mentioned), explicitly says it is NOT open-web search, and explains how it handles unfilled facets via gaps[] and contradictions. It also mentions semantic excerpting of large records so users know how data is processed. The readOnlyHint annotation matches the description's lack of any mutating operations, so 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 extremely long and contains a lot of information, but it's not well-structured — it's a single dense paragraph without line breaks. While every piece of info is useful, the wall-of-text format makes it harder to scan quickly. It repeats the 'not open-web' point and mixes prerequisites, output details, and usage examples in one flowing paragraph. A structured format with headings for prerequisites, behavior, limitations, and examples would improve readability without losing content.

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

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

This is extremely comprehensive. It covers prerequisites (account required), pricing/tiers, alternative tools, input semantics (question and depth), expected latency, output structure (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[]), limitations (not for breaking news), and even implementation details like parallel routing and contradictions. For a tool with only 2 parameters, this is exceptionally complete coverage of context, limitations, and expectations.

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 two parameters (question and depth) are both documented in the schema. The description elaborates on the 'depth' parameter in detail, explaining what each enum value ('quick', 'standard', 'thorough') means in terms of facets, hops, and paid requirements. 'question' is described as natural language input. The description effectively covers the required fields and their usage.

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

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

The description clearly explains that this tool performs grounded multi-source research across 1,463 structured data sources in one call. It differentiates it from open-web search and describes the internal process of decomposing questions and routing to 5,581 tools in parallel. The output format (findings packet with evidence, confidence, source, fetched_at, citations, gaps[]) is explicitly stated, leaving no ambiguity about what the tool does.

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

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

Provides comprehensive guidance: account requirement and free sign-up via GitHub, paid tier for 'thorough' depth, an alternative tool (ask_pipeworx) when not signed in, and specific use-case recommendations. It also cautions against using this tool for current-news topics and explains depth tiers with timing expectations (15-60s, up to 90s for thorough). The 'best for' and 'for a single lookup use' sections give clear decision criteria.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it returns top-N tools with full input schemas and curated examples, ready to call. 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 somewhat long but is dense with useful information and front-loaded with purpose. Every sentence adds value, though minor trimming possible.

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 discovery tool, the description covers how it works, what it returns, and when to use it. No output schema needed; completeness is high given context.

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

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

Schema has 100% parameter coverage with descriptions. The description adds context about aliases and natural language usage examples, going beyond the schema alone.

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

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

The description clearly states the tool finds tools by describing a data or task, listing many example domains. It distinguishes itself from siblings by being the discovery tool to call first.

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 to use this tool first when many tools are available to see options, and when needing to browse or discover tools. Does not specify when not to use, but positive guidance 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?

Annotations already declare safe, idempotent, read-only behavior. The description adds valuable context: returns specific fields (cik, recent_filings with URIs, fundamentals sorted, patents soft-fail, news fallback), and explains source dependencies. 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?

Well-structured with examples first, then details on return fields and caveats. Slightly long but every sentence adds value. Front-loaded with key examples.

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 all aspects: intended use, data sources, return values, edge cases (soft-fail, name unsupported). No output schema, but description fully explains expected results. Complete enough 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?

Both parameters have schema descriptions (100% coverage). The description adds usage examples and clarifies that names are not supported via the 'value' field, enhancing real-world understanding.

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

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

The description explicitly states the tool provides a 'full cross-source profile of a US public company' with example queries. It clearly distinguishes from siblings by recommending preference 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 says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes 'names not supported (use resolve_entity first if you only have a name)'. Also mentions patent API soft-fail.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description confirms deletion but adds no behavioral details beyond what annotations convey.

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

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

Three focused sentences with no waste. The action and use cases are front-loaded, making the purpose immediately clear.

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

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

Given the tool's simplicity (one parameter, no schema options, no output schema), the description fully covers its behavior and usage 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 already describes the 'key' parameter (100% coverage). The description adds no additional parameter semantics beyond what the schema provides.

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

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

The description clearly states the action 'Delete' and the resource 'previously stored memory by key', and the verb-resource combination distinguishes it from siblings like '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?

Specifies multiple concrete use cases: when context is stale, task is done, or clearing sensitive data. Also explicitly pairs with 'remember' and 'recall'.

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, idempotentHint) already indicate safe, read-only behavior. The description adds meaningful context: it fetches the page, extracts content, and emits standard markdown 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 concise with two short paragraphs, front-loading the core action and purpose. Every sentence adds value (what it does, how it outputs, use cases). No wasted words.

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

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

Given the tool's simplicity and full schema/annotation coverage, the description is complete: it explains output format (markdown), intended placement (site-root/llms.txt), and provides use cases. No missing critical details.

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

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

Schema description coverage is 100% (both 'url' and 'max_links' are documented). The description does not add new meaning beyond the schema (e.g., it mentions 'max_links' explicitly but no format or constraints). Baseline 3 is appropriate.

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

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

The description clearly states it generates an llms.txt file for a URL, explaining the specific verb ('generate'), resource ('llms.txt'), and action ('fetches page, extracts title/description/key links, emits markdown'). This distinguishes it from siblings like 'scan_competitor_ai_presence' or 'web_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?

The description lists explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, auditing how an AI crawler would see a competitor'), providing clear context for when to use. However, it does not mention when not to use or specify alternatives among siblings.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description does not need to reiterate safety. It adds value by specifying returned fields and parameter behavior, though not strictly necessary.

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 the core purpose, no redundant information. Every word 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 complexity (1 param, no output schema), the description is complete: it explains return fields, usage, and parameter in the schema. 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?

Schema coverage is 100% and the schema already describes include_inactive. The description does not add further parameter meaning beyond what is in the schema.

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

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

The description clearly states it lists the caller's active subscriptions and specifies the returned fields (id, type, params, etc.). This distinguishes it from siblings like subscribe and unsubscribe.

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

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

Explicitly advises 'Use this to review what you're monitoring before adding more or to find an id to cancel,' providing clear guidance on when to use the tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing safe read behavior. The description adds value beyond annotations by specifying return fields and mentioning 'publication metadata' and 'breaking-news flag.' Some behavioral details (e.g., rate limits, pagination) are omitted but not critical given the safety profile.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. No fluff or redundancy.

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

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

Given the presence of an output schema and high schema coverage, the description is sufficient for most use cases. It explains what is returned but could briefly mention how parameters like 'freshness' affect results. Still, it avoids gaps for a news-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?

The input schema has 100% coverage with descriptions for all 6 parameters. The description does not add any parameter-specific information beyond what the schema already provides, so the score is at baseline.

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

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

The description clearly states it is a 'News-specific search' tool, specifies the verb 'search' and resource 'news', and lists exact return fields (title, URL, source, age, snippet, breaking-news flag). This distinguishes it from sibling tools like 'web_search' by emphasizing news focus and metadata.

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 term 'News-specific search' implies use for news queries, but no explicit guidance on when to use this vs. alternatives like 'web_search' or when not to use it. No exclusion criteria or alternative tool names are mentioned.

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 provide no hints (all false), so the description carries the burden. It discloses rate limiting ('5 per identifier per day'), lack of quota impact, the anonymous claim_token flow, and how signals are used. It does not explicitly state that every submission writes data, but this is strongly implied. The added operational details (rate limits, token semantics) go well beyond the bare annotation fields.

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

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

Although the description is long, it is densely packed with non-redundant information. The main purpose is front-loaded, followed by usage conditions, scope boundaries, and behavioral details. Each sentence contributes unique guidance, and the structure flows logically from what → when → how → caveats. No filler or tautology.

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

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

For a feedback tool with 4 optional parameters, a nested context object, an enum, and no output schema, the description fully covers purpose, usage scope, behavioral nuances, token flow, rate limits, and post-submission behavior. It even anticipates the 'not sure' edge case. The absence of an output schema is compensated by explaining what a filing returns (claim_token) and later retrieval semantics.

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

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

Schema coverage is 100%, so the baseline is 3. The description augments the schema by explaining how claim_token is obtained (filing without an account) and the intended usage ('pass it back later'), which is not fully captured in the schema's field description. It also sets message length expectations ('1-2 sentences typical, 2000 chars max'), though this duplicates the schema's max constraint partially.

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

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

The description opens with a clear imperative: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates specific feedback types (bug, feature/data_gap, praise), distinguishing this tool from all sibling research/search tools. The verb+resource+scope structure is explicit and unambiguous.

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

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

The description provides explicit when-to-use criteria for each feedback category and an explicit exclusion: 'ONLY for tools served by this Pipeworx connection' with guidance to file elsewhere for third-party MCP servers. It also clarifies how to handle uncertainty and directs users on follow-up via claim_token. This is textbook alternative 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 provide safety profile (readOnly, openWorld, idempotent, non-destructive). The description adds context about data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h), which further discloses behavior beyond annotations. No contradiction.

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

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

The description is front-loaded with core function, follows with bullet points for use cases, and ends with technical details. It is concise without unnecessary words, though slightly long.

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

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

Without an output schema, the description adequately explains what is returned (top tools, top packs, total call volume) and provides caching details. For a simple read-only tool with one optional parameter, this is sufficient.

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

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

Schema coverage is 100% with a well-described optional enum parameter. The description reaffirms the window options but adds no new meaning beyond the schema. Baseline 3 is appropriate given high schema coverage.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over a recent window, which is a specific and unique purpose. It distinguishes itself from siblings like 'discover_tools' which list available tools, not trending usage.

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 three explicit use cases (discovering hot data sources, confirming canonical tool, aligning use case) that guide when to use. It doesn't explicitly mention when not to use or compare to siblings, but the context is clear and helpful.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read-only behavior. The description adds valuable context: it explains scanning, monotonicity and partition checks, fill check against CLOB depth, placeholder filtering, and similarity thresholds, without contradicting annotations.

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

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

While the description is well-structured with clear sections, it is quite verbose and contains excessive technical detail. The first sentence front-loads the purpose, but subsequent paragraphs could be more concise to improve 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?

The description thoroughly explains the return format (opportunities[], partition_check, fill check details) despite no output schema. It covers multiple modes, edge-case filtering (placeholders, similarity), and trade recommendations. No major gaps are apparent.

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 significant value by explaining what event slugs and topic seeds look like, giving concrete examples, and detailing behavior for each parameter (e.g., 'walks child markets, checks ordering...' for event, 'searches related events...' for topic).

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes the tool's function from siblings like polymarket_edges and polymarket_fill_risk by detailing its unique modes (event, topic, trending).

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

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

The description provides explicit guidance on when to use each mode: 'Call with NO args for a trending_scan', 'pass event for... partition_check', 'topic for cross-event scan'. It also includes recommendations ('event recommended for a specific market'), conditions to avoid ('do not trade it' when fill check negative), and explains when cross-event mode is advantageous.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds significant context: caching (1h KV), diagnostics for empty segments, Fed bets exclusion, specific model details (e.g., per-sport alpha for favorite-longshot bias), and a warning that edge may already be priced in. No contradictions with annotations.

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

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

The description is comprehensive but verbose, packing detailed model explanations and diagnostics into paragraphs. While front-loaded with purpose, it could be more concise without losing essential information. Still functional for an AI agent.

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 (9 parameters, no output schema, multiple segments), the description is exceptionally complete. It explains response structure (by_segment, fed_candidates, _diagnostics), caching, filter behaviors, and edge calculations, ensuring an agent knows what to expect despite the absence of an output schema.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description adds some context (e.g., min_kelly refers to half-Kelly, max_spread_pp as tradeable filter), but the schema already covers meaning adequately. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: scanning Polymarket markets for opportunities where Pipeworx data disagrees with market price, targeting the 'what should I bet on today' use case. It distinguishes itself from sibling tools by detailing three distinct model families and segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), making its unique value 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 provides extensive guidance on when to use the tool, including the tradeable-edge knobs and filters for customizing output. However, it lacks explicit comparisons to sibling tools or stated when-not-to-use scenarios, slightly reducing clarity for an AI agent deciding between alternatives.

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

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

The description fully discloses behavior: read-only telemetry, snapshot data source, time-series computation, trend classification, and limitations (TTL, snapshot gaps). Annotations already indicate readOnlyHint and idempotentHint, and the description adds valuable context without contradiction.

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

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

The description is detailed but well-structured with clear sections for purpose, response fields, and limits. It is slightly verbose but every sentence adds necessary context, earning a 4.

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

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

With no output schema, the description fully explains the return structure (tracked, expired, snapshot_dates) and data nuances (trend, decay, lifespan). This makes it complete for an agent to understand the output.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds practical defaults (days=14, window=1wk) and constraints (max 30 days), providing extra value beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis.

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

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

The description explains when to use it (to assess if an edge is fresh or old and decaying) but does not explicitly mention when not to use it or compare to alternatives, though 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?

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description is not required to repeat that. The description adds significant behavioral details beyond annotations: it walks the order book ladder, returns specific metrics like top_of_book, vwap_fill_price, slippage, shares_filled, verdict, and warns about forced directional risk. 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 dense but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). It front-loads the purpose and uses punctuation and line breaks for readability. Every sentence adds value, from the functional description to usage guidance and risk warnings.

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 comprehensively lists all return fields for both modes: top_of_book, vwap, slippage, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket. It also explains the practical risk of partial fills, making the tool self-contained for the agent.

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

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

Schema coverage is 100%, but the description adds crucial meaning beyond schema. It explains that size_usd interpretation differs between single-market (max spend on buys, target proceeds on sells) and basket (settlement notional, shares per leg). It clarifies default side logic for basket (auto from partition sum). This enables the agent to use parameters correctly.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes between single-market and basket modes, and the purpose is well differentiated from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on risk assessment.

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

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

The description provides explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns when not to rely on theoretical edges on thin books and explains the risk of partial basket fills converting an arb into an unhedged directional position.

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, non-destructive behavior. The description adds substantial behavioral context: how matching works, safety fields (compatibility_warning, temporal_alignment), and why spreads may be invalid. 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 well-structured with bullet points, bolding, and clear sections. It front-loads the main purpose and each sentence adds value. 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, the description comprehensively explains the response structure (leg-by-leg prices, spreads array, safety fields) and edge cases. For a tool with 3 parameters, this is thorough and leaves no ambiguity.

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 each parameter. The description adds meaning beyond schema: it explains the two modes, enumerates topic values, describes how explicit tickers override, and includes examples. This adds significant value for an agent.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes between two modes (topic shortcuts vs explicit tickers) and explains the output (leg-by-leg prices, spreads). This differentiates it from sibling tools like polymarket_arbitrage or polymarket_edges.

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

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

The description provides extensive guidance: it explains when to use each mode, when the spread is meaningful, and when compatibility_warning fires (non-equivalent bet shapes, semantically unrelated events, temporal misalignment). It even warns that most pre-mapped topics return warnings today, setting clear expectations.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scope details (anonymous IP, BYO key hash, account ID) and pairing with remember/forget, which adds value 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?

Three sentences, front-loaded with action. Every sentence adds value without redundancy. Efficient and clear.

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

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

For a simple 1-parameter tool with good annotations and no output schema, the description is complete. It covers purpose, usage, scope, and pairing with siblings.

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% for the single parameter. Description adds that omitting the key lists all keys, which is not in the schema description, providing actionable semantics.

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

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

Description clearly states the tool retrieves a value saved via remember or lists all saved keys. It distinguishes from siblings 'remember' and 'forget' by specifying its complementary role.

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 explicit usage guidance: use to look up context stored earlier without re-deriving. It explains the optional key argument to list all keys. It does not explicitly state 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?

Discloses the side effect of 'mark_read:true' on subsequent calls, and confirms read-only behavior via annotations. No contradictions; description adds 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?

Four sentences front-load the main purpose and provide supplementary details without verbosity. 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, the description adequately describes the return fields (source, citation_uri, payload). All parameters are explained, and usage context is sufficient for complex optional parameters.

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

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

Schema covers 100% of parameters, and description adds meaningful context (e.g., example type 'sec_8k', explanation of 'mark_read' effect) that goes beyond the schema alone.

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

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

The description uses a specific verb 'Pull fired events' and identifies the resource 'subscription feed'. It clearly distinguishes from sibling tools like 'list_subscriptions' by focusing on events/alerts 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?

Explicitly mentions filtering options and provides an alternative endpoint for scripts/dashboards. While it doesn't list all when-not scenarios, the context is clear enough for an agent to decide.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds substantial behavioral context: fans out to multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail), explains fallback logic ('GDELT preferred, GNews when rate-limited or 5xx'), and notes the PatentsView API sunset. 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 dense and front-loaded with query examples, but it runs to 4 sentences and includes technical details about API fallbacks and sunset dates. While efficient, it could be slightly more concise without losing clarity. However, every sentence adds distinct 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 no output schema, the description adequately summarizes the return structure: 'structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs'. It covers three diverse data sources, fallback behavior, and parameter formats, leaving no major gaps for a monitoring 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 already has 100% coverage with clear descriptions. The description adds valuable context: concrete relative shorthand examples for `since` ('7d', '30d', '3m', '1y') and the recommendation 'Use "30d" or "1m" for typical monitoring'. For `value`, it provides examples of both ticker and CIK formats, enhancing usability 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 starts with concrete query examples ('What's new with X', 'latest on Y') that immediately clarify the tool's purpose as a change feed for companies. It explicitly distinguishes from sibling entity_profile ('Use entity_profile instead when you want the static profile'), establishing clear differentiation.

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

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

Provides explicit guidance on when to use this tool (query language examples like 'updates on Acme') and when not to ('Use entity_profile instead'). Mentions sibling tool by name, giving clear context for 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?

Annotations provide idempotentHint=true and destructiveHint=false. The description adds valuable context: memory is key-value, scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradictions.

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

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

The description is a single, well-structured paragraph. It front-loads the purpose, then explains when to use, how it works, and related tools. Every sentence adds value; no wasted words.

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

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

For a simple write tool with two string parameters and no output schema, the description fully covers usage, storage behavior, scope, retention, and pairing with recall/forget. Annotations handle safety hints. Complete.

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

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

Schema coverage is 100% with descriptions. The description adds real-world examples (e.g., 'subject_property', 'target_ticker') and clarifies the value can hold any text, enhancing understanding beyond the schema.

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

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

The description uses a specific verb ('Save') and resource ('data') and clearly states the tool's purpose: storing data for reuse across conversations or sessions. It distinguishes itself from sibling tools like recall and forget by explaining the 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?

The description explicitly states when to use this tool ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). It also clarifies scope and persistence depending on authentication.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds significant behavioral detail: graceful degradation of LEI/FIGI enrichment (partial results if external APIs fail), explicit disclosure of `unresolved` identifiers, and lookup cascading that replaces multiple steps. This goes well beyond annotations.

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

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

The description is comprehensive but slightly verbose, with multiple paragraphs covering examples, purpose, and type-specific details. It is well-structured and front-loaded with actionable examples, but could be trimmed without losing meaning. Every sentence earns its place given 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?

Despite having no output schema, the description fully compensates by detailing the output (identifiers labelled by source, unresolved list) and the cascading resolution behavior. For a tool with only two simple parameters and complex internal logic, the description provides complete guidance for correct use.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds clarity by explaining how the `value` parameter is interpreted differently per type (e.g., ISIN resolves to legal entity via GLEIF mapping), which is not in the schema description. This extra context helps the agent understand resolution logic.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with explicit examples ("What's the ticker for…") and supported types (company, drug). It distinguishes itself from siblings by advising "Use FIRST whenever you have a name but need an ID." This provides a specific verb-resource pairing and contextual differentiation.

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

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

The description explicitly advises using this tool first for name-to-ID tasks and notes it replaces 2-3 manual lookups, giving clear context. However, it does not explicitly state when not to use it or name direct alternatives (e.g., entity_profile for when an ID is already known), though the guidance implies such boundaries.

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

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

Description details probing mechanism, ranking, and output fields (score, confidence, signal density), complementing annotations that mark it as read-only, idempotent, and non-destructive.

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 clearly defines action, second adds usage and output details. 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?

Covers all aspects: purpose, parameters, usage, output format, and behavioral traits, especially since output schema is absent.

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, but description adds context on entity count range, first-as-subject, context disambiguation, and models usage.

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

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

States specific verb 'Compare' and resource 'AI visibility across entities', distinguishes from siblings like ai_visibility_check and compare_entities by specifying side-by-side comparison and ranking.

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 use case example ('competitive AI-marketing audits') and related tool (ai_visibility_check), but lacks explicit when-not or alternative exclusions.

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

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

Annotations already indicate readOnly, openWorld, idempotent. Description adds key behavioral traits: graceful degradation, bundlephobia latency (5-30s on first measure), and sources_failed listing. 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 concise yet information-dense: composite check, usage, return summary, ecosystem scope, failure behavior. Every sentence adds value; front-loaded with purpose.

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

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

No output schema, but description covers return structure (summary block, advisories, links, alternatives). Parameters fully covered. All necessary context for an agent to invoke correctly.

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

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

Schema coverage is 100% with descriptions for both parameters. Description enhances by mentioning scoped packages are accepted for 'package' and default behavior for 'version'. 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?

The description clearly states the tool's purpose as a composite check for npm package quality, fans out across deps.dev and bundlephobia. It specifies the verb-resource combination (scan_dependency for npm packages) and distinguishes from siblings by focusing on npm ecosystem only.

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 (agent asks about safety, popularity, size) and when not to (other ecosystems fall under different tools). Also provides guidance on partial failures and timing.

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, etc.), description discloses embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), char limit (200K), and truncation flagging. Also states output includes character offsets and similarity scores, enabling verification.

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 4 sentences, each earning its place: purpose, usage, pairing, technical details. No fluff; front-loaded with main idea. Efficient and well-structured.

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

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

Given no output schema, description still explains return format (passages with offsets and scores). Annotations cover safety and idempotency. Technical constraints (200K char limit, embedding details) are provided. Complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% but description adds valuable examples and context: for 'query' gives natural language examples like 'supply-chain risk'; for 'text' notes max 200K chars; for 'limit' implies default 5 and range 1-20. Adds meaning beyond the schema entries.

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 'Semantic search INSIDE a fetched record' — specific verb (search inside), resource (fetched record), and context (after fetch). It distinguishes from sibling 'ask_pipeworx_grounded' by explaining how they pair together.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and explains the benefit (saves context, returns only passages that matter). Also notes the 200K char cap and truncation behavior, providing clear guidance on when the 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?

Beyond annotations (e.g., idempotentHint=true, destructiveHint=false), the description reveals prerequisites (OAuth account), delivery constraints (sms verification, 10/day cap, webhook auto-disable), and returns subscription id. 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 front-loaded with the main purpose and is structured into clear sections: general statement, prerequisite, types, delivery channels. Every sentence adds value without redundancy.

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

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

Given the tool's complexity and lack of output schema, the description covers prerequisites, types, delivery details, and return value. It is sufficient for correct agent invocation.

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

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

The description adds significant meaning to each parameter, e.g., explaining type-specific filter formats and delivery subfields, going well beyond the schema's descriptions. Schema coverage is 100%, but the description enriches understanding.

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

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

The description clearly states the tool's action: 'Create a proactive monitoring subscription to a live-data event stream' and specifies the return value. It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context for when to use the tool (creating subscriptions) and details on parameters and delivery options, but does not explicitly state when not to use it or reference alternatives (though siblings are available).

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 behavioral context beyond annotations by detailing that it returns example questions with tool+argument shapes and is the starting point for discovering capabilities.

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

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

The description is fairly long but well-structured with parentheses for examples and front-loading of key phrases. 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?

Given no output schema, the description adequately explains that it returns category-bucketed example questions with tool+argument shapes. It covers the tool's purpose, usage, and behavior fully for its simple interface.

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 one optional parameter. The description adds meaning by explaining that omitting topic yields a cross-category spread and providing example values like 'finance', 'pharma', etc., which goes beyond the schema's 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 clearly states that this tool is the onboarding entry point for learning what Pipeworx can do. It specifies the verb 'ask' and resource 'Pipeworx', and distinguishes from siblings by emphasizing its role as a first-use tool for getting started and understanding meta-tools.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It provides clear context for when to use it (onboarding) and implies it should be used before other tools, though it doesn't explicitly name alternatives.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds important behavioral context beyond the annotations (idempotent, non-destructive). No contradiction with annotations.

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

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

Two concise sentences, both informative and front-loaded with the main action. No unnecessary words.

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

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

For a simple 1-parameter tool with full schema coverage and no output schema, the description provides complete context: purpose, usage constraint, and behavioral outcome. Nothing is missing.

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

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

Schema coverage is 100% with parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds the context that the id comes from subscribe, which is helpful but not extensive. 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 explicitly states the action ('Cancel a subscription') and the resource ('by id'). It clearly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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 a clear constraint: 'Ownership is enforced — you can only cancel your own subscriptions.' This guides usage, though it doesn't explicitly state when to use this tool over alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses error behavior (could_not_verify means no check happened), the distinction between 'unsupported' and 'could_not_verify', the return of verbatim evidence with pipeworx:// citations, and the fallback routing logic. This adds significant behavioral context that annotations alone cannot convey.

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

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

The description is longer than average but every sentence carries meaningful information. It is front-loaded with examples and purpose, then efficiently covers routing, verdict types, caller caveats, and efficiency gains. The only slight detractor is the length, but for a tool with this complexity, the detail is justified.

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

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

The description is complete for a tool of this complexity. It enumerates all possible verdict values ('confirmed', 'approximately_correct', 'refuted', 'inconclusive', 'unsupported', 'could_not_verify'), clarifies the meaning of the error state, and explains the fallback mechanism. No output schema is provided, but the description adequately covers return value structure and edge cases.

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

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

The schema already documents both parameters and has 100% description coverage. The tool description adds valuable nuance, especially for tolerance_pct: it explains how the default is implied by claim wording and capped at 5, and gives guidance for hallucination detection (set 1–2). This goes beyond basic parameter types and helps the agent select appropriate values.

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

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

The description clearly states the tool's purpose with a specific verb ('verify') and resource ('natural-language claim against authoritative sources'). It opens with natural-language examples that make the intent unmistakable, and it distinguishes this tool from generic search or research tools by emphasizing verdict-based claim verification. The scope is well-defined, including special handling for company-financial claims vs. other factual claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance (SEC EDGAR fast path vs. grounded pipeline) and mentions that it replaces 4–6 sequential calls, signaling it is the preferred tool for claim verification. The important caller note about 'could_not_verify' adds critical usage caveats.

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 minimal behavioral context beyond naming the Brave index and return fields. 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 concise sentences that front-load the core purpose and immediately list return fields and optional filters. No extraneous words.

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

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

The description covers purpose, return fields, and optional filters. Output schema exists for return values. Minor omission: no mention of pagination/offset, but that's documented in the 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 detailed parameter descriptions. The description mentions 'Optional country, language, safesearch, and freshness filters,' which restates schema content without adding significant new meaning.

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

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

The description clearly states it performs a 'General web search via the Brave index' and lists specific return fields (title, URL, description snippet, etc.). This distinguishes it from sibling tools like deep_research or news_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?

No explicit guidance on when to use this tool versus alternatives (e.g., deep_research, news_search). The description implies general search but lacks 'when to use' or 'when not to use' instructions.

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