Shodan

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc. The description adds behavioral details: return type (per-model scores, confidence, signals, raw_response, combined view), free default model, and BYO key requirement for Anthropic. No contradictions.

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

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

Two sentences: first sentence covers core function and output, second adds model details and use cases. Every sentence is necessary, concise, and front-loaded with key information.

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

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

For a tool with 4 parameters, 1 required, and no output schema, the description compensates by outlining the return structure and typical use cases. It is nearly complete, though it could mention pagination or rate limits (if any).

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value beyond the schema by specifying the default model ('Workers AI Llama-3.3-70b') and clarifying the API key payment model ('you pay Anthropic directly').

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

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

The description uses a specific verb ('probe') and names the resource ('one or more LLMs'), clearly scoping to brand/entity visibility scoring. It distinguishes from siblings like 'compare_entities' by focusing on LLM knowledge probing.

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) and explains when to provide an API key. However, it does not compare with similar tools like 'scan_competitor_ai_presence' or mention alternatives.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds rich behavioral context beyond annotations: it routes to 5,529 tools across 1,455 sources, fills arguments automatically, and returns structured answers with pipeworx:// citation URIs. It also notes that it works on every tier and is fast. 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 front-loaded with the core directive ('PREFER OVER WEB SEARCH') and structured into clear sections: domain list, usage triggers, examples, and escalation paths. Some redundancy exists (e.g., multiple 'use whenever' statements), but each sentence adds value. It's slightly verbose but appropriately detailed for its 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?

For a tool with no output schema, the description adequately explains the return type ('structured answer with citation URIs'). It covers domains, examples, usage, and alternatives, making it highly usable. However, it omits potential edge cases like ambiguous queries or failure modes, which slightly limits completeness.

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

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

Schema description coverage is 100% with aliases clearly documented, so the baseline is 3. The description does not add significant parameter-level meaning beyond the schema; it only provides example questions. The phrase 'fills arguments' hints at natural language parsing but doesn't elaborate on the parameter format.

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 routes factual questions to a large set of verified sources and returns structured answers with citations. It explicitly differentiates itself from siblings like ask_pipeworx_grounded and deep_research, making its purpose unambiguous.

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

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

The description provides explicit usage guidance: PREFER OVER WEB SEARCH, use for factual questions, START HERE for most questions. It also specifies when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad/multi-part questions), giving clear when-to-use and 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.

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

Beyond the annotations (read-only, idempotent), the description discloses that this is an experimental router with no fallback, that candidate routing improvements are only active during tests, and that currently it matches ask_pipeworx exactly. This provides useful context about potential variability in routing behavior.

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

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

Three sentences efficiently convey the tool's beta nature, current status, and usage. While slightly long, every clause adds necessary context and the key information is front-loaded at the beginning.

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, usage, current behavior, and the lack of fallback, which is sufficient for an agent to invoke it correctly. It references matching ask_pipeworx for response shape, so return value details are implicitly inherited from the stable tool.

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

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

The input schema already covers all six parameters, which are aliases for the single 'question' parameter. The description adds no new parameter-specific meaning beyond confirming the same arguments as ask_pipeworx, so the schema does the heavy lifting.

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

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

The description clearly states this is a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx tool by its experimental routing, making its purpose and scope immediately 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?

Explicitly instructs to 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router. This gives a clear directive on when to choose this tool over the stable alternative, with no ambiguity.

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

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

Adds meaningful behavioral context beyond annotations: extra LLM call cost, refusal reasons, and the guarantee to only extract from tool results. The annotations already declare read-only and idempotent, and the description reinforces these without contradicting them.

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

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

The description is dense but every sentence adds value: purpose, mechanism, return shape, refusal modes, and usage guidance. It is somewhat long but justified for the complexity and high-stakes context.

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

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

Given the tool's complexity, the description covers the full behavior: success return fields, explicit refusal reasons, comparison with ask_pipeworx, and cost tradeoff. No output schema exists, so the detailed return/refusal explanation fills that gap effectively.

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

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

All 6 parameters have full schema descriptions (all aliases for 'question'), so the schema carries the parameter meaning. The description does not add parameter-specific semantics beyond the schema, which is acceptable given the high 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 identifies this as a grounded, hallucination-resistant answer mode, distinct from the sibling ask_pipeworx. It specifies the verb (answer/extract), the resource (Pipeworx tools/data), and the key behavior of using only tool-returned content.

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 (answers that will be quoted, cited, or acted on) and when to prefer the alternative (casual lookups, because of the extra LLM call). This directly addresses usage vs siblings and provides 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 declare read-only, idempotent, open-world. The description extensively adds behavioral details: fan-out logic by category, response shapes, resolver contract, parent event extractor, news fields, safety short-circuits, wide-spread handling, resolution-rule risk. 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?

Very detailed with many examples and edge cases; all content is valuable but the description is verbose (~500 words). Could be more concise while retaining key points.

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: input formats, fan-out logic per category, output structure, match confidence, parent events, news fallback, safety mechanisms, resolution rules. No output schema, but description fully compensates. Complete for a complex tool.

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

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

Schema coverage is 100%. Description adds meaning: market can be slug/URL/question, depth defaults to thorough, include_raw default false with explanation of when to set true. Enriches schema with practical guidance.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, specifying inputs (slug, URL, question) and outputs (evidence packet + comparison). It distinguishes from siblings like ask_pipeworx by focusing on bet-specific 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?

Provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z') and advises inspecting market_match_confidence. However, does not explicitly state when not to use or compare to alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds specifics: data sources (SEC EDGAR for companies, FAERS for drugs), sorting by primary metric, and citation URIs. 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?

Every sentence is purposeful: trigger phrases, usage preference, data details, sorting, and return format. Dense but not verbose, front-loaded with key info.

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

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

For a tool with two entity types and complex data, the description covers all essential behavior (data sources, sorting, citations). No output schema, but return format is described. 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%, but description adds rich meaning: examples of values (tickers, drug names), details on what data is pulled (revenue, net income, adverse events), and sorting behavior. This significantly aids correct parameter 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 explicitly states the tool does side-by-side comparison of 2–5 companies or drugs, listing trigger phrases like 'compare', 'X vs Y', 'head to head'. It clearly identifies the resource (companies/drugs) and distinguishes itself from sequential 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?

The description says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving explicit when-to-use guidance and implying when not to use it. This is strong usage direction.

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 readOnly/openWorld/idempotent annotations, the description discloses the findings packet structure, gaps[] array with a never-invented policy, always-fetchable citation_uri, contradictions scan for standard/thorough depths, semantic excerpting, and expected latency. This is far richer than the annotations alone.

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

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

The description is long but every sentence carries meaningful information, and it is well-structured with account requirements upfront, then purpose, usage boundaries, depth semantics, citation guarantees, and performance. It could be slightly more scannable with bullet points, but it earns a 4 for no wasted 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?

For a complex tool with no output schema, the description covers the full picture: output structure, error representation via gaps[], citation resolvability, latency, plan requirements, and alternative tools. It leaves very little for the agent to guess.

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 both parameters fully (100%), so the baseline is 3. The description adds value beyond the schema by clarifying that questions can be broad/multi-part and explaining the behavioral consequences of each depth level (gap recovery, lead chasing, contradictions), justifying a 4.

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

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

The description clearly states the tool does grounded multi-source research across 1,455 structured data sources, decomposes questions into facets, and routes to 5,529 tools in parallel. It explicitly distinguishes itself from ask_pipeworx and notes it is NOT open-web search, making the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance (best for broad/multi-part structured questions, with examples), when-not-to-use (single lookups, breaking/current news), and names alternatives ('use ask_pipeworx instead'). It even covers account prerequisites and when a paid plan is required.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior; description adds that results include full schemas and are ready to call, enhancing transparency.

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

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

Front-loaded with purpose and usage, lists relevant domains efficiently, though slightly long; no wasted sentences.

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

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

Fully covers purpose, when to use, output format (despite no output schema), and integration with other tools; comprehensive for a discovery tool.

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

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

Schema coverage is 100%, so baseline 3; description provides query examples but adds little beyond schema definitions for parameters.

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

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

The description clearly states 'Find tools by describing the data or task' with specific domain examples, and distinguishes itself from sibling tools by being a meta-tool for discovery.

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 'Call this FIRST when you have many tools available and want to see the option set' providing clear context, though does not explicitly mention when not to use it.

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

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

Beyond annotations, description details return fields, data sources (SEC, XBRL, USPTO, news, GLEIF), fallbacks (GDELT→GNews), and soft-fail for patents. Adds actionable behavioral context.

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

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

Front-loaded with examples; slightly long but each sentence adds value. Structured explanation of sources and returns justifies 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?

Comprehensive coverage of return fields, sources, fallbacks, and limitations. No output schema, but description explicitly lists what the tool returns, making it complete for the complex multi-source profile.

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 describes both parameters with examples (type enum, value format). Description reinforces but does not add substantial new semantics beyond schema.

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

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

Description clearly states the tool provides a full cross-source profile of a US public company in one parallel call, with example queries and explicit distinction from sibling tools like resolve_entity.

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 preferring this tool over chaining single-source lookups for holistic views, and clarifies to use resolve_entity if only a name is provided.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and stale context, enhancing transparency beyond annotations without contradiction.

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

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

Three concise sentences: purpose, usage guidelines, and sibling pairing. No redundant or irrelevant content; each sentence serves a clear function.

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 a simple tool with one parameter, no output schema, and informative annotations, the description covers purpose, usage, and relationships completely.

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

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

Schema coverage is 100% for the single parameter 'key,' which is adequately described in the schema. The description adds minimal parameter detail beyond 'by key,' so baseline 3 is appropriate.

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

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

The description clearly states 'Delete a previously stored memory by key,' specifying the verb and resource. It also naturally distinguishes from sibling tools remember and recall by implying storage and retrieval functions.

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

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

The description gives explicit when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also advises pairing with remember and recall, though it does not explicitly state when not to use.

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

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

Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and well-supported. The description adds process details (fetches page, extracts title/description/key links, emits markdown format) beyond annotations, providing behavioral transparency 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 concise (4 sentences), front-loaded with the main purpose, and uses clear, structured language. 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?

For a simple tool with 2 parameters and no output schema, the description provides sufficient context: explains the output format, process, and use cases. It could mention potential errors or rate limits, but overall completeness is high.

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

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

Schema coverage is 100%, with clear descriptions for both 'url' and 'max_links'. The tool description does not add additional parameter semantics beyond what the schema already provides, meeting the baseline for high coverage.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the output format and use cases. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on file generation rather than scanning.

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 three explicit use cases (client site indexing, personal project drafting, competitor auditing), providing clear context for when to use the tool. It does not explicitly state when not to use or name alternatives, but the examples are sufficient for an AI agent.

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

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

Annotations already declare readOnly=true, idempotent=true, destructive=false. Description adds value by naming return fields and noting default behavior (active only, include_inactive toggle). No contradictions.

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

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

Two sentences, no wasted words. First sentence defines action and output, second gives usage guidance. Perfectly front-loaded.

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

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

With rich annotations and a simple parameter, the description adequately covers what an agent needs: what it does, what it returns, and when to use it. Could mention ordering or pagination, but not necessary for this tool.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra meaning beyond the schema's parameter description.

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

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

Description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe. It also lists return fields.

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 when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Directly references sibling actions (subscribe, cancel), giving clear context.

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

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

Adds significant behavioral context beyond annotations: claim_token flow for later status checks, rate limit of 5 per identifier per day, free/no quota impact, daily digest review, and roadmap influence. No contradictions with annotations (readOnly=false aligns with side effects of submitting feedback).

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

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

The description is long but every sentence serves a purpose: purpose, usage scenarios, exclusions, token behavior, operational details. It's front-loaded with the main action and flows logically 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?

For a feedback tool with 4 parameters, one nested object, and no output schema, the description covers all necessary angles: what, when, how, limitations, and follow-up semantics. It is self-sufficient for an agent to decide, invoke, and interpret the result.

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

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

Schema already covers all parameters with clear descriptions (100% coverage). The description adds useful context such as how to use claim_token (pass it back with no other arguments) and emphasizes message should be 1-2 sentences and not paste user prompts, enhancing the schema's explanation.

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 'Tell the Pipeworx team something is broken, missing, or needs to exist' with specific feedback types (bug, feature, data_gap, praise). It also distinguishes this tool from sibling tools by limiting scope to Pipeworx-served tools 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 provides when-to-use scenarios ('Use when a tool returns wrong/stale data...') and when-not-to-use (if the tool came from a different MCP server, file it there instead). Also advises how to phrase feedback (in terms of Pipeworx tools/packs, not user prompts).

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 readOnly, openWorld, idempotent, and non-destructive. Description adds self-aggregating signal from CF analytics-engine, no PII, and caching details (5min-1h). No contradictions.

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

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

Well-structured in three parts: what it does, use cases, technical details. Each sentence provides value; no fluff.

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

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

Given the tool's simplicity (one param, no output schema), the description explains output (top tools, packs, call volume), caching, and data source. Sufficient for an agent to understand 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 covers the single parameter (window) with enum and description. Description adds extra meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' 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 returns top tools, packs, and call volume over a window, with specific verb (returns) and resource (top tools/packs, call volume). It distinguishes from siblings by focusing on trending 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?

Provides explicit use cases (discovering hot data, confirming popular tool, aligning with agent needs) and differentiates window lengths. Does not explicitly state when not to use, but context is clear.

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

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

Annotations declare readOnlyHint, so read-only behavior is clear. The description adds substantial behavioral context: details on arbitrage detection logic, semantic anchor (Jaccard similarity), partition filter, fill check, and response structure. No contradictions with annotations.

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

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

The description is detailed but somewhat verbose. It front-loads the primary function and maintains logical flow. Every sentence adds value, but could be more concise by grouping mode-specific details. Still, it remains highly informative.

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

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

Despite lacking an output schema, the description fully explains the return structure (opportunities array with gap_pp, suggested_trade, reasoning; partition_check details). It covers modes, edge cases (low similarity, placeholder filtering), and fill check. Given complexity, it is 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 description coverage is 100% for both parameters. Description adds meaning beyond the schema: explains 'event' accepts slug or URL, 'topic' is a seed question, and elaborates on what each mode does. The description also explains output fields like 'gap_pp', 'suggested_trade', and partition check details.

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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It explicitly distinguishes three modes (trending_scan, event, topic) with examples, differentiating it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

Provides explicit guidance: call with no args for trending scan, pass 'event' for single-event mode, pass 'topic' for cross-event mode. Recommends 'event' for specific markets and explains when to use each. Includes warnings about fill checks and references polymarket_fill_risk for custom sizing.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond annotations, detailing the three model families, edge calculation (edge_pp_net after slippage, kelly_fraction, kelly_fraction_half capped at 0.25), caching at KV level for 1 hour, and diagnostic info (funnel counters, category_counts, filter_skips). 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 quite long (multiple paragraphs) but well-structured with sections like response top-level, diagnostics, and cached info. It front-loads the main purpose but includes very granular details about model families (e.g., 'partition_overround on mutually-exclusive events; per-leg favorite-longshot bias correction with per-sport α'). This could be 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 9 parameters, no output schema, and rich annotations, the description thoroughly covers behavior, response structure (by_segment, diagnostics), caching, and knob usage. It even explains why Fed bets are excluded and why segment might be empty. This compensates fully for the lack of output schema.

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

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

All 9 parameters are described in the input schema (100% coverage). The description adds value for tradeable-edge knobs like min_liquidity and max_spread_pp by explaining their role in dropping unrealizable edges. It also clarifies min_partition_leg_kelly vs min_kelly. However, the description does not significantly expand on parameters already well-documented 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 starts with 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly identifies the verb (scan, return), resource (Polymarket markets), and specific purpose (disagreement detection). It distinguishes from the sibling polymarket_arbitrage and others by focusing on Pipeworx data vs market price.

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 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It also explains the three response segments and when knobs like min_liquidity and max_spread_pp apply. However, it does not explicitly state when to avoid using this tool or compare it to siblings like polymarket_fill_risk.

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

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

Adds significant context beyond annotations: explains data source (daily snapshots), snapshot creation triggers (cache-miss), limits (60-day TTL), decay computation (daily closes, not intraday), and response structure. No contradiction with annotations.

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

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

Well-structured with clear sections: purpose, output fields, limits. Slightly verbose but front-loaded with essential information; each part serves a 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?

Given no output schema, the description fully explains the response structure (tracked, expired, snapshot_dates) and covers limits and data source details. Comprehensive for an agent to understand usage.

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

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

Schema coverage is 100% and schema describes both parameters. Description adds context: default values (14 for days, '1wk' for window), clamp range for days, and concrete examples for window family. Provides more practical meaning.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' from daily snapshots, answering specific questions about edge age and trend. It distinguishes itself from sibling 'polymarket_edges' by focusing on historical 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?

Implicitly contrasts fresh vs old edges, indicating usage for historical persistence analysis. Does not explicitly state when not to use or name alternatives, but context suggests differentiation from current-edge tools.

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

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

Annotations already indicate readOnlyHint=true and non-destructive, but the description adds rich behavioral context: it walks the order-book ladder, returns fill metrics, and warns about the dominant loss mode (partial basket fills causing unhedged directional positions). 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 packed with information and uses formatting to highlight key points. It is somewhat long but well-organized, front-loading the purpose and structure. Every sentence 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?

Without an output schema, the description thoroughly details return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, theoretical_sum, capture_ratio, thin_legs, forced_directional_risk, etc.), covering edge cases and risks comprehensively.

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

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

Schema description coverage is 100%, but the description adds extra meaning: for size_usd it clarifies settlement notional in basket mode and default/clamp; for side it explains auto behavior. This adds 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and references sibling tools like polymarket_arbitrage and polymarket_edges for 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?

Explicitly states 'REQUIRES one of `market` or `event`' and advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500,' explaining 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 declare readOnlyHint=true and idempotentHint=true. The description enriches this by detailing edge cases: compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype counters, and explicit warnings about real spreads being rarer than suggested. 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 front-loaded with purpose and structured into clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). It is informative but slightly verbose, especially the final sentence which is a run-on. Could be trimmed for conciseness without losing substance.

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

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

Given the complexity (3 optional params, no output schema), the description is exceptionally complete. It explains the response structure (venue prices, top_spreads_pp), safety fields, and edge cases like temporal misalignment and incomparable bet shapes. The lack of output schema is compensated by detailed prose.

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 basic type descriptions. The description adds semantic value by explaining the two modes, listing valid topic strings, and describing how explicit ticker/slug override topic. This goes beyond schema but could include more specifics on format expectations (e.g., ticker format 'KXFED-26OCT').

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

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

The description clearly states 'Cross-venue spread between Kalshi and Polymarket for the same resolving question', with specific verb (compute/compare spread) and resource (two venues). It distinguishes from siblings like polymarket_arbitrage which focuses on Polymarket internal arbitrage.

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

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

The description explains two modes (topic for pre-mapped macro shortcuts, explicit for custom pairings) and provides context on when spreads are meaningful vs when compatibility_warning fires. It implicitly advises caution by noting that 'most pre-mapped topics return compatibility_warning today', but lacks explicit 'when not to use' guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safety. The description adds behavioral context: scoping to identifier (anonymous IP, BYO key hash, or account ID) and the dual behavior (retrieve vs list). 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 consists of two concise sentences with no wasted words. The first sentence states the core functionality, the second provides usage and scope context. Excellent front-loading.

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

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

For a simple tool with one parameter and no output schema, the description is complete. It covers purpose, parameter behavior, usage context, and scope. The annotations further support the completeness.

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

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

Schema coverage is 100% with a single optional parameter 'key'. The description adds value by explaining the default behavior when key is omitted (list all keys) and by providing the use-case context, going beyond the schema 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 the verb ('retrieve' or 'list') and resource ('value saved via remember' or 'all saved keys'). It distinguishes itself from sibling tools like remember and forget by specifying that it retrieves or lists stored context.

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

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

The description provides clear usage context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions pairing with remember and forget, but does not explicitly state when not to use the tool. However, the single-purpose nature makes it 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 readOnly=true and idempotent=true. The description adds behavioral details: the mark_read flag affects subsequent calls (only shows newer events), and mentions return fields (source, citation_uri, payload). 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?

Three sentences are concise and front-loaded with purpose. Every sentence adds necessary information without waste. The structure flows naturally from action to details to 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?

Despite no output schema, the description details return fields (source, citation_uri, raw payload) and explains polling suitability and an alternative endpoint. With 5 parameters (none required) and rich annotations, this is 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 covers all parameters with descriptions (100% coverage). The description adds value by explaining the mark_read behavior (flags events read so next call shows newer) and hints at filtering by type/since. This supplements the schema well.

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

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

The description clearly states the tool retrieves fired events/alerts from a subscription feed, with a specific verb ('Pull'/'Returns'). It distinguishes itself from siblings like 'list_subscriptions' and 'subscribe' by focusing on recent alerts from the feed.

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 on when to use the tool (polling works fine) and mentions an alternative endpoint for scripts/dashboards. It doesn't explicitly exclude other tools or state when-not, but the guidance is sufficient.

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

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

Discloses behavior beyond annotations: fans out to multiple sources in one parallel call, mentions soft-fail for USPTO due to sunset, and explains fallback logic. 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 front-loaded with example queries, every sentence adds value, and it is efficiently packed with information while remaining readable.

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

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

Given the complexity of multiple sources and fallback, the description is complete. It describes the return structure (changes[] grouped by source, total_changes, citation URIs) despite no output schema.

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

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

Schema coverage is 100%, baseline 3. Description adds value by explaining the 'since' format with examples, recommending typical values, and clarifying that 'type' only supports 'company' and 'value' can be ticker or CIK.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, aggregating from multiple sources. It uses example queries like 'What's new with X' and distinguishes itself from sibling 'entity_profile' which is for static profiles.

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

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

Explicitly tells when to use this tool vs alternatives: 'Use entity_profile instead when you want the static profile'. Describes fallback behavior between GDELT and GNews.

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, but description adds valuable context: persistence differences between authenticated vs anonymous users, and scoping by identifier. No contradictions.

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

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

Four sentences, front-loaded with purpose, no wasted words. Each sentence adds distinct value: purpose, usage, format, and pairing.

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 is needed for a simple save operation. Description covers key behavioral aspects (persistence, scope, pairing) sufficiently for an agent to use 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 covers both parameters fully (100% coverage). Description adds example key formats and notes value is 'any text', which is helpful but not essential 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 verb 'Save data' and resource 'memory key-value pair', with specific examples (ticker, address, preference) that distinguish it from siblings recall and forget.

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

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

Explicitly says when to use: 'when you discover something worth carrying forward' and provides alternatives: recall to retrieve, forget to delete. Also clarifies scoping and persistence.

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 signal read-only, open-world, idempotent, non-destructive. The description adds meaningful context beyond those: cross-source behavior, graceful degradation when upstream APIs fail, explicit unresolved identifier reporting, and the fact that one call replaces multiple manual lookups. It also discloses ownership relationships (parent/ultimate-parent/children), which is not inferable from annotations.

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

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

The description is long but information-dense. The trigger-phrase opening front-loads usability, and the supported types are clearly separated. Some redundancy exists (e.g., listing the same examples in both description and schema), but every sentence earns its place by providing workflow context, supported types, and edge-case behavior. Not a 5 because it could be split into more digestible paragraphs.

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

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

Given there is no output schema, the description compensates well by stating what identifiers come back, labeling sources, and noting unresolved items are explicitly included. It also covers failure behavior (GLEIF/OpenFIGI unavailable) and multi-endpoint cascade. It doesn't mention pagination or return format, but for a resolver tool this is complete enough to set correct 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the exact formats expected for company input ('ticker (AAPL), CIK (0000320193), or name') and drug input ('brand or generic name (e.g., ozempic, metformin)'). It also explains what each type returns (CIK/ticker/LEI/FIGI vs RxCUI/ingredient/brand), which enriches the raw 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 natural-language triggers ('What's the ticker for...' etc.) and immediately states the core function: resolving a user-spoken NAME to canonical identifiers. It clearly lists supported entity types (company and drug) and distinguishes itself from sibling tools by naming the downstream need ('other tools require as input'). The detail about returning identifiers like CIK, LEI, and RxCUI makes the purpose unambiguous.

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

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

The description says 'Use FIRST whenever you have a name but need an ID,' which gives a clear when-to-use directive and explicitly positions it as the first step in workflows. It does not name specific sibling alternatives or state when NOT to use it, but the guidance is strong enough for an agent to select this tool over entity_profile or compare_entities, which likely consume these identifiers.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that it internally calls ai_visibility_check and returns a ranked list with score, confidence, and signal density, providing context beyond annotations without contradiction.

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

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

The description is three sentences, front-loading the main action and methodology. It is concise with no filler, though it could be slightly more structured (e.g., bullet points for output).

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

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

Without an output schema, the description adequately explains the return format (ranked list with fields). It covers use case and methodology. However, it omits details on error handling or rate limits, which are not critical given the annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it mentions entities but the schema already explains the first entry as subject. No extra parameter context is provided.

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: to compare AI visibility across multiple entities side-by-side, probe with ai_visibility_check, rank by score, and surface most/least recognized. It distinguishes from sibling tool ai_visibility_check, which handles single entities.

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

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

The description gives a concrete use case (competitive AI-marketing audits) and implies it is for multiple entities, contrasting with single-entity checks. However, it does not explicitly exclude single entities or name ai_visibility_check as the alternative, which would make guidance stronger.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint=true; description adds critical behavioral detail: bundlephobia first measurement can take 5-30s, partial failures degrade gracefully, and sources_failed will list timed-out sources. This goes beyond annotations without contradicting them.

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

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

Description is comprehensive but somewhat lengthy. It is front-loaded with the primary purpose in the first sentence. Every sentence adds useful information, though slight tightening could improve conciseness. Still well-structured 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?

Despite no output schema, description fully explains return value: summary block with specified fields, per-advisory details, links, and recent alternative versions. Also covers partial failure behavior. Complete for a composite tool with complex return.

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

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

Schema coverage is 100% with both parameters described. Description adds value by noting scoped packages are accepted (e.g., '@types/node') and that version defaults to latest if omitted. This enriches the schema definitions.

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

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

Description clearly states it's a composite check for adding an npm package, combining deps.dev and bundlephobia. It specifies the exact purpose: answering if a package is safe/popular/small or what it costs. Distinguishes from siblings by noting NPM ecosystem only and referencing alternative tools for other ecosystems.

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

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

Explicitly states when to use: when agent asks about safety, popularity, size, or cost of npm packages. Also specifies when not to use: other ecosystems (PyPI, Maven, etc.) should use deps.dev:version directly. Provides 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?

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds model details (BGE-base-en embeddings + cosine over 500-char windows), a 200K character input cap with truncation and flagging, and that passages include offsets and similarity scores. 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 slightly long (4 sentences) but each sentence adds value: use case, pair suggestion, technical details, and cap info. It is front-loaded with the primary purpose, then details. Good structure.

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 the description explains the return format (top-N passages with character offsets and similarity scores). For a tool with 3 parameters and no complex outputs, this is sufficient. Could mention that it returns an array of objects.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by giving concrete query examples ('supply-chain risk', 'fiscal year 2024 revenue') and specifying the default limit (5), enhancing the schema's already good parameter descriptions.

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

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

The description clearly states the tool performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and states it is for when records are too large for the prompt. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It doesn't explicitly say when not to use alternatives, but the pairing hint with ask_pipeworx_grounded provides differentiation.

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 aligns with annotations (readOnlyHint, idempotentHint) and adds behavioral details: it returns a full profile including ports, services, CVEs, etc. This goes beyond the annotations to inform the agent of the output contents.

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

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

The description is very concise—two sentences and an example—packed with essential information. No unnecessary words, and the most critical info (purpose, example) appears first.

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

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

For a simple read-only tool with comprehensive annotations and full schema coverage, the description covers the purpose, output fields, and an example. It does not mention error handling or rate limits, but these are less critical given the tool's nature.

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

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

Schema coverage is 100%, so the description adds minimal extra parameter semantics. The description does not further explain parameters beyond what the schema already provides. A baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: looking up an IP address to discover open ports, services, and CVEs. It uses a specific verb ('Returns') and resource ('full Shodan host profile'), and includes an example. This sufficiently distinguishes it from sibling tools like 'shodan_host_search' and 'shodan_host_count'.

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 an example invocation but does not explicitly state when to use this tool versus its siblings (e.g., shodan_host_search for query-based lookups). The usage context is implied by the name and example, but no 'when to use' or 'when not to use' guidance is given.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds context: 'free — this endpoint does not consume query credits' and describes the return format. No contradictions.

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

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

Two concise sentences plus an example. Every sentence adds value: first states purpose and free aspect, second explains return, example clarifies usage. No fluff.

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

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

For a count endpoint with no output schema, the description adequately explains the return value (match count + optional facets) and API key requirements. It covers all needed 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 description coverage is 100% with good descriptions for all three parameters. The description adds a concrete example showing usage of query, facets, and _apiKey, which aids understanding beyond the schema alone.

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

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

The description clearly states the tool's function: 'Count hosts matching <query> with facet breakdown'. It specifies the verb 'Count' and resource 'hosts', and distinguishes from sibling tools like shodan_host_search by emphasizing it's a count endpoint that is free (no query credits).

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

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

The description indicates when to use this tool (to get counts and facets) and highlights it's free, implying preference over siblings for counting. However, it does not explicitly state when to avoid alternative tools like shodan_host_search, which would be needed for a 5.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool returns specific fields (IP, port, org, etc.) and uses Shodan syntax, providing additional context beyond annotations without contradiction.

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

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

The description is concise: two sentences plus an example call. It front-loads the purpose and includes a practical example, with 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?

The description mentions returned fields and pagination (via page parameter). Without an output schema, it provides enough information for typical use. It could mention that 100 results per page is the default, which is already in the schema but not in the description. Still, it is mostly complete.

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

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

The input schema has 100% description coverage for all three parameters (query, page, _apiKey), so the baseline is 3. The description adds example usage but does not significantly extend the schema definitions. Score meets 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 searches Shodan for hosts matching a query, provides example syntax, and lists returned fields (IP, port, etc.). This distinguishes it from siblings like 'shodan_host_count' and 'shodan_host' (single IP lookup).

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 includes example queries and Shodan search syntax, aiding usage. However, it does not explicitly state when to use this tool versus alternatives like 'shodan_host_count' or 'shodan_host', which would be helpful. Implicit guidance is sufficient but not explicit.

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

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

The description discloses write behavior, OAuth requirement, delivery constraints (SMS cap, webhook limitations), and return value. Annotations are consistent; description adds useful context beyond annotations.

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

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

The description is well-structured and front-loaded with the main purpose. While somewhat lengthy, each sentence adds value with examples and constraints. Minor redundancy in delivery description but overall efficient.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers prerequisites, supported types, parameter formats, delivery options with examples, return value, and limitations (SMS cap, webhook secret). No gaps.

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

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

Schema coverage is 100%, and the description adds meaningful examples and constraints for each parameter, including nested delivery options and webhook signing details, exceeding mere schema repetition.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id, distinguishing it from related tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit context on when to use (requires OAuth account, supports specific types) and details delivery channels. While it does not explicitly list when not to use or compare directly to siblings, the guidance is clear and practical.

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, open-world, idempotent, non-destructive. Description adds detail on return structure (category-bucketed examples with tool+argument shape) and call patterns (no args vs topic filter). Adds useful context beyond annotations.

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

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

Description is informative but slightly long; front-loaded with common queries. Could be trimmed slightly, but every sentence adds value. Well-structured for quick scanning.

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 fully explains what is returned (category-bucketed examples, tool+argument shape). Also covers optional parameter and usage context. Complete for an onboarding tool.

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

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

Schema coverage is 100%, description explains the topic parameter with examples ('finance', 'pharma', 'betting') and clarifies behavior when omitted. Adds meaning beyond the schema's basic 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?

Clearly states it is the onboarding entry point to discover what Pipeworx can do, returning category-bucketed example questions. Distinguishes from siblings by specifying it's for learning capabilities and connecting to tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and mentions alternatives like ask_pipeworx, entity_profile, compare_entities. Provides clear when-to-use and when-not-to guidance.

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

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

Beyond annotations (idempotent, non-destructive), description adds ownership enforcement and the deactivation behavior, providing useful context that annotations do not cover.

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

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

Two concise sentences with front-loaded action word. No unnecessary information.

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

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

For a simple tool with one parameter and no output schema, the description explains the effect (deactivation vs deletion) and links to recent_alerts, making it fully understandable.

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 parameter description is clear. Description does not add additional semantics beyond the schema's description of 'id'.

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 'Cancel' and resource 'subscription by id', distinguishing it from siblings like subscribe and list_subscriptions.

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

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

Mentions ownership enforcement ('you can only cancel your own subscriptions') and that deactivation preserves historical events, implying when to use it. However, does not explicitly state when not to use or name alternative tools.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description discloses critical behavioral nuances: the verdict vocabulary, the semantic difference between could_not_verify (check did not happen, carries verification_error, not evidence) and unsupported (no source covers it), and the two routing paths (structured SEC EDGAR vs. grounded pipeline). This adds substantial value and does not contradict any annotation.

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

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

The description is long but front-loaded with a purpose statement and trigger phrases, then logically moves through usage, return values, and critical caveats. Every sentence conveys important information, especially the could_not_verify warning and the 'replaces 4–6 calls' efficiency note. The opening list of phrases is slightly repetitive, but overall the structure earns its length for the tool's complexity.

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

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

With no output schema, the description carries the burden of explaining return values and behavior. It does so thoroughly: enumerates all verdicts, describes the actual value with pipeworx:// citation, explains could_not_verify and unsupported, and outlines the two processing paths. This provides enough context for an agent to use the tool correctly and interpret results, even without an output schema.

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

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

Schema coverage is 100% and the schema already thoroughly explains both parameters, including tolerance_pct's override behavior and hallucination-detection usage. The description adds only a minor tie-in via 'exact percent-delta math,' which reinforces but does not extend the parameter meaning. This meets the baseline for well-documented schemas.

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

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

The description opens with natural-language trigger phrases and explicitly states the core function: 'natural-language claim verification against authoritative sources.' It distinguishes the tool by covering both SEC EDGAR/XBRL financial claims and a grounded pipeline for other claims, and clearly names it as a replacement for 4–6 sequential calls. This is a specific verb+resource that differentiates it from sibling tools like ask_pipeworx or deep_research.

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

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

The description gives an explicit when-to-use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates the financial vs. non-financial paths. It does not explicitly state when not to use it or name alternative tools, but the 'Replaces 4–6 sequential calls' line provides implicit guidance against doing the multi-step pipeline manually. This is clear context but lacks exclusionary directing.

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