Doffin

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds: default model is free, Anthropic requires BYO key and direct payment, and output includes per-model details plus combined view. No contradictions.

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

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

Two sentences, front-loaded with action and purpose. Every sentence adds value: first defines main function and default, second covers optional parameters and output format. No wasted words.

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

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

Given 4 parameters (1 required), no output schema, and annotations covering safety, the description fully explains purpose, parameters, output structure (per-model scores + combined), and use cases. No gaps for agent selection.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining default model behavior, conditions for _apiKey, and purpose of context parameter for disambiguation, which goes 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 probes LLMs for business/brand visibility and scores it 0-100 per model. It specifies the default model and optional Anthropic probe, distinguishing it from sibling tools like ask_pipeworx (single question) or scan_competitor_ai_presence (broader scan).

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

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

It explicitly mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). It does not provide explicit when-not-to-use or alternatives, but the context is clear and the description implies this is for multi-model visibility scoring.

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 that the tool routes internally across 5,462 tools, fills arguments, and returns stable citation URIs—information that goes beyond the readOnlyHint/openWorldHint annotations. It also notes speed and tier availability, but doesn't elaborate on failure modes or potential delays.

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 and free of filler, with each sentence covering a distinct aspect: domains, routing behavior, trigger phrases, examples, alternatives, and a breaking-news note. Minor redundancy between 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it' prevents a perfect score.

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 as a router over thousands of sources and its minimal schema (one question field with aliases), the description is remarkably complete. It covers input styles, output behavior (structured answer with citations), comparisons with siblings, tier coverage, and special cases, 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?

The schema already documents all six parameters with descriptions and aliases, achieving 100% coverage. The description's examples reinforce correct usage but don't add new parameter-level constraints or formatting details, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: routing factual queries to thousands of verified sources and returning structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by specifying their different roles.

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

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

Provides explicit when-to-use guidance, including trigger phrases ('what is', 'look up', 'find'), preference over web search, and direct alternatives for cases requiring verbatim evidence or broad multi-part queries. Also explains behavior for breaking news and encourages starting here by default.

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

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

Discloses that candidate routing improvements are enabled live, that no candidate is currently active so behavior matches ask_pipeworx exactly, and that this is a full working router, not a fallback. These traits go beyond the readOnly/openWorld/idempotent annotations.

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

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

Three dense sentences, each adding value: identity, current state, and usage. The specific retirement date adds context but could be trimmed; still well-structured.

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

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

Given no output schema, the description explains the router's purpose, current state, and usage. It doesn't describe the response shape, but defers to ask_pipeworx, which is acceptable for a tool with low parameter complexity and rich 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 covers 100% of parameters with clear alias documentation. The description only says 'same arguments' relying on the schema, so it adds no extra semantic detail beyond 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 identifies this as the beta version of ask_pipeworx, an identical universal router with the same 5,462 tools and response shape. It distinguishes itself from the stable ask_pipeworx sibling by emphasizing its experimental routing improvements.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. This provides clear when-to-use guidance and implies the alternative.

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

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

Annotations already declare read-only, open-world, and idempotent hints, but the description adds valuable behavioral details: the refusal_reason enum, the use of verbatim evidence quotes, the constraint of using ONLY tool results, and the extra LLM call cost. These go beyond the annotations and are critical for understanding the tool's guarantees and failure modes.

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

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

The description is dense but well-structured, front-loading the core purpose before covering mechanics, return format, usage guidance, and trade-offs. Every sentence adds meaningful information, with no redundancy or fluff. The length is justified given the tool's 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?

Despite having no output schema, the description fully specifies the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the refusal variants. It also provides scale context (5,462 tools, 1419 sources) and cost implications, making the description complete for an agent to understand the tool's full behavior.

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

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

Schema coverage is 100% with the 'question' parameter and documented aliases (q, text, input, query, prompt). The description does not add any parameter-level semantics beyond the schema, so the baseline score of 3 applies. The schema itself is comprehensive, and the description correctly focuses on behavior rather than repeating parameter 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 identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and explains its process: routing, argument filling, fetching, and extracting answers only from tool results. It distinguishes itself from sibling ask_pipeworx by emphasizing the grounded extraction and explicit refusal behavior, making its purpose specific and unambiguous.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It also provides a concrete trade-off (one extra LLM call), giving clear decision-making guidance.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds extensive behavioral context: response shapes (market, analysis, evidence), resolver contract details (confidence levels, alternatives), parent event extraction, news fields with fallback info, safety mechanisms (low-confidence short-circuit, closed market handling), and resolution-rule risk. 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 dense and comprehensive but very long (multiple paragraphs). It front-loads the main purpose effectively but becomes verbose with many details. Each sentence adds value, but overall length could hinder quick scanning. A more structured approach with bullet points or sections would improve conciseness.

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

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

Given the tool complexity (3 params, no output schema), the description thoroughly explains return fields, edge cases (low confidence, closed markets, illiquid spreads), error handling, and resolution rule risk. It compensates well for the lack of output schema by detailing response shapes. All critical aspects for an AI agent to use effectively are covered.

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 three parameters (market, depth, include_raw) all described. The description adds context: depth enum values ('quick' vs 'thorough' with brief explanation), include_raw purpose and size implications, and market parameter examples. It does not add entirely new semantics but reinforces the schema, meeting baseline expectations.

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 in one call, with specific verb ('research') and resource ('Polymarket bet'). It distinguishes from siblings by detailing unique data sources and fan-out behavior. The examples of inputs (slug, URL, question) and output (evidence packet + comparison) are specific and actionable.

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 suggests use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. It provides classifiers and fan-out examples. However, it does not explicitly state when NOT to use or name alternative tools, though the sibling list implies this is for polymarket bet research. The examples are thorough but could be more concise.

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. Description adds detailed behavioral context: pulls latest 10-K data for companies, handles off-calendar fiscal years, uses FAERS for drugs, sorts results by primary metric, and returns citation URIs.

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

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

The description is concise, front-loaded with example queries, and every sentence adds necessary detail. Well-structured with separate sections for company and drug.

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 no output schema, the description covers data sources, sorting, and return format (paired data + citation URIs). Annotations provide safety info, making it 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?

Input schema covers 100% of parameters with descriptions. Description adds value by clarifying 'values' as tickers/CIKs for company and drug names for drug, and specifying min/max items.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 companies or drugs, with specific examples like 'which is bigger' and 'rank these companies'. It distinguishes from siblings by advising preference over sequential single-pack lookups.

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

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

Explicitly provides when-to-use scenarios (comparison queries) and recommends against sequential single-pack lookups. Sibling tools like entity_profile handle single entity data, so this tool is for multi-entity comparison.

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

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

Beyond the readOnly/idempotent annotations, the description discloses account requirements, parallelism, findings packet structure (evidence, confidence, source, fetched_at, stable pipeworx:// citations), gaps[], contradictions[], hop field, fetchable citation_uri behavior, semantic excerpting, latency expectations, and failure modes like 'returns mostly empty gaps[]' for breaking news. 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 longer than average, but it is dense and front-loaded with the account requirement. Almost every sentence adds necessary context for a complex tool; minor redundancy exists in the news/ask_pipeworx guidance and depth semantics, but overall structure is effective.

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

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

Despite no output schema, the description fully explains the return packet, gaps, contradictions, citation behavior, latency, and limitations. It covers prerequisites, depth options, and alternative tools, making it sufficient to interpret results and plan usage without external documentation.

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

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

Schema coverage is 100% and the schema already describes both `question` and `depth`. The description adds value by clarifying that broad/multi-part questions are fine, tying 'thorough' to a paid plan, and explaining how depth levels affect hop behavior and contradictions[] — meaning beyond the schema's enum text.

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

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

The description uses a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call.' It clearly distinguishes itself from siblings by explicitly contrasting with ask_pipeworx for single lookups and breaking news.

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

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

Explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and 'For a single lookup use ask_pipeworx... For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx.' It also provides account/tier requirements and an alternative (ask_pipeworx) when not signed in.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds useful behavioral details: returns top-N tools with full schemas and no second lookup needed.

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, but slightly verbose. Could trim some examples, but still effective.

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

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

For a simple discovery tool with clear annotations, the description fully covers input, output, and usage context. No output schema needed.

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

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

Schema covers all parameters (100% coverage). Description adds value by explaining aliases (q, task, search, description) and providing examples, though schema already documents them.

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 examples like 'SEC filings, FDA drugs' and distinguishes itself from siblings as a discovery tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', providing clear context for when to use.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable context: what fields are returned (buyer, description, CPV codes, deadlines, values, award details) and the need for an API key (authentication detail).

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, each earning its place: purpose with example, content of returns, and usage guidance. No redundancy, front-loaded with the core action.

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

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

Given no output schema and only 2 parameters, the description covers all necessary aspects: what the tool does, what it returns, how to get the id, and authentication. An agent can confidently invoke it.

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

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

Schema coverage is 100%, but the description adds meaning: explains the format of doffin_id ('2023-100282'), specifies the source of the API key, and gives a concrete example.

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 the verb 'fetch', the resource 'full document for one Norwegian public-procurement notice', and the required identifier (Doffin id). Distinguishes from sibling tools doffin_search and doffin_recent by mentioning they provide the ids.

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: to get the full document given an id from doffin_search or doffin_recent. Also mentions the API key requirement, though 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 already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: results are sorted newest first, each hit includes a public doffin.no URL, and authentication via API key is required. There is 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 a single paragraph of moderate length, front-loading the core action. It efficiently covers key aspects but could be slightly more concise by using bullet points or shorter sentences for readability.

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

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

Without an output schema, the description adequately hints at output structure (each hit has a URL) and ordering. It also covers authentication and optional filters. For a simple list tool with good annotations, this is sufficient though not exhaustive.

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 describes all 6 parameters with 100% coverage, including examples. The description adds context for the _apiKey parameter (mentioning free sign-up) and the type parameter (mapping plain words to enum values). This provides meaningful addition beyond the schema's base 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 uses a specific verb ('list'), identifies the resource ('latest Norwegian government tenders and contract awards published on Doffin'), and specifies scope ('in the last N days, newest first'). It clearly distinguishes itself from sibling tools like doffin_notice (single notice) and doffin_search (search) by focusing on recency.

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 a clear use case ('Great for monitoring fresh Norwegian anbud, new kunngjøringer, contract award results, and upcoming bid deadlines') and mentions optional filters. However, it does not explicitly state when not to use this tool or compare it to alternatives, leaving some 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe, idempotent read operation. The description adds that each hit gets a public URL, which is useful but not critical. The API key requirement is mentioned but does not conflict 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 fairly long but well-structured, with the core purpose front-loaded. Every sentence adds value, though some details (like the synonym mappings) could be condensed. It is not excessively verbose.

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

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

Despite lacking an output schema, the description explains that each hit gets a public URL. All 13 parameters are described with guidance. The API key requirement is noted, and context about preference over web search is given. The description is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining each parameter in natural language, providing synonyms for notice types and statuses, and offering examples. This goes far beyond the schema's dry 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 it searches Norwegian government procurement notices on Doffin, with a specific verb (search) and resource (Doffin notices). It distinguishes itself from sibling tools like doffin_notice and doffin_recent by explicitly mentioning it is a full-text search with filters, implying it is the general search tool.

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

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

The description explicitly states to prefer this tool over web search for Norwegian public tenders, providing clear context. It includes examples and notes about the API key. However, it does not explicitly exclude cases where other tools like doffin_notice might be more appropriate (e.g., for a single notice lookup).

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false. The description adds substantial context: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; mentions potential soft-fail for patents (USPTO PatentsView API sunset May 2025); and details the return 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 relatively lengthy but front-loaded with example queries and purpose. Every sentence adds value—it covers inputs, outputs, behavior, and alternatives. Slightly dense, but well-organized and effective for an AI agent.

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

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

Given the tool's complexity (multiple data sources) and lack of an output schema, the description is thorough: it lists all return fields (cik, company_name, recent_filings with URI format, fundamentals, patents, news, LEI), mentions potential failures, and specifies input constraints. No gaps.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema by explaining that value can be ticker or zero-padded CIK, and reaffirms that names are not supported. It clarifies the type parameter (only 'company' supported).

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 a 'full cross-source profile of a US public company' with specific example queries like 'Tell me about X' or 'company profile for Microsoft'. It distinguishes itself from siblings by explicitly noting it takes ticker or CIK, not names (which should use 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?

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'Names not supported (use resolve_entity first if you only have a name)'. This provides clear when-to-use and when-not-to-use guidance.

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

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

Description aligns with annotations (destructiveHint=true). Adds context about clearing sensitive data and removing stale context, going beyond what annotations provide. No contradiction.

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

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

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

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

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

For a simple tool with one parameter and no output schema, the description provides complete context: purpose, usage, and behavior. No gaps.

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

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

Single parameter 'key' has schema description 'Memory key to delete'. Schema coverage is 100%, so description adds no extra meaning 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 deletes a stored memory by key, using a specific verb and resource. It distinguishes itself from siblings by mentioning 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also advises pairing with related tools.

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

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

Beyond annotations, the description details the process: fetches page, extracts title/description/key links, emits standard markdown. No contradiction with annotations.

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

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

Two sentences, front-loaded with purpose and process, then use cases. Every sentence adds value with no waste.

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 explains the output format and usage context. All necessary information for an agent is present.

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

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

Schema coverage is 100% with clear descriptions; the tool description adds no additional parameter meaning beyond what's in the schema, which is sufficient.

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 'generate' and resource 'llms.txt file' for any URL, distinguishing it from sibling tools like 'scan_competitor_ai_presence'. No ambiguity.

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 (client indexing, own project, competitor audit) but does not specify when not to use it or compare with alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds value by listing specific returned fields and suggesting usage context, which goes beyond the annotations.

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

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

The description is concise with three sentences, each serving a clear purpose: listing the function, specifying output, and providing usage guidance. No unnecessary text.

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

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

Given the simple nature of the tool (optional boolean parameter), the description sufficiently covers what the tool returns and its intended use case. It could mention ordering or limits but otherwise is complete for its context.

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

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

Schema coverage is 100%, so the parameter 'include_inactive' is already well-described in the schema. The description does not add any additional meaning or usage guidance for the parameter, sticking to the baseline level.

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 and resource ('List the caller's active subscriptions') and specifies the returned fields. It also differentiates from sibling tools by noting usage for reviewing before subscribing or finding an id to cancel.

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

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

The description explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel'. This provides clear context and implies when not to use (e.g., if you want to subscribe or unsubscribe directly).

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 are all false, so the description carries the burden. It adds rate limits ('Rate-limited to 5 per identifier per day'), quota behavior ('Free; doesn't count against your tool-call quota'), and processing context ('The team reads digests daily and signal directly affects roadmap'). It also warns not to paste user prompts. It doesn't explicitly state that feedback is transmitted or stored, but 'Tell the Pipeworx team' implies it. Minor gap, but not a contradiction.

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

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

The description is front-loaded with purpose, then flows logically: triggers → scope exclusion → guidance → process → rate limit. Every sentence adds value; nothing is redundant. It is moderately long (~120 words) but each clause serves a distinct purpose, making it appropriately sized for a feedback tool that needs to avoid misuse.

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 3-param tool with no output schema and all-false annotations, the description covers the key context: when to use, scope boundaries, formatting constraints, rate limits, and roadmap impact. It doesn't specify any confirmation or post-submission behavior, but with no output schema that's acceptable. Could mention whether feedback is anonymous, but not critical. Overall highly 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 100% of parameters, so baseline is 3. The description adds meaningful guidance beyond schema: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also clarifies the intent of the type enum by redefining bug/feature/data_gap/praise in practical terms. This semantic enrichment earns 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 opens with a clear, specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It further distinguishes from siblings by explicitly scoping to Pipeworx tools only and naming alternatives (ask_pipeworx, discover_tools, etc. are not feedback channels). This unambiguously sets it apart from all other tools in the catalog.

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

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

The description provides explicit when-to-use triggers: bug, feature/data_gap, praise. It also gives a clear exclusion: 'if the tool came from a different MCP server... we cannot fix it' and redirects to that server. 'Not sure? Pipeworx tool names are the ones this connection lists' offers a fallback check. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: data source (CF analytics-engine), no PII, caching (5min-1h), and what is returned (top tools, packs, volume). No contradiction.

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

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

The description is concise: 3 sentences and 3 bullet points. It is front-loaded with the core purpose in the first sentence. Every line adds value, with no redundancy or fluff.

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

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

Given the tool's simplicity (one optional param, no output schema), the description completely covers what the tool does, what it returns, and when to use it. It explains caching, data source, and privacy, leaving no major 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?

The schema already provides full documentation for the single parameter (window) with enum and description. The description adds semantic value by explaining the effect of shorter vs longer windows, going beyond the schema's technical specification.

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

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

The description clearly states what the tool does: returns top tools, top packs, and total call volume over a recent window. It lists specific use cases and distinguishes itself from other tools like discover_tools or ask_pipeworx 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?

The description explicitly provides three use cases with bullet points, helping the agent decide when to use it. It does not explicitly mention when not to use it or name alternatives, but the use cases are clear enough to guide 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 (readOnly, idempotent), the description details fill check logic, semantic anchor similarity threshold, partition filter for placeholder slugs, 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?

Well-structured with clear sections for each mode, but somewhat verbose with details like fill check thresholds. Front-loaded with main purpose and action verbs. Could be slightly more concise.

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

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

Given no output schema, the description thoroughly explains response fields (opportunities array, partition_check object) and fill check behavior. Covers edge cases like placeholder filtering and similarity checks. Complete for agent invocation.

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

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

Schema has 100% coverage with descriptive parameter comments. The description adds further context: e.g., for event it explains it walks child markets and checks ordering; for topic it explains cross-event scanning and Jaccard similarity. 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes between three modes (trending scan, single-event, cross-event) and contrasts with sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicit guidance on when to use each mode: no args for trending_scan, event for per-event partition_check, topic for cross-event scanning. Provides example event slugs and topic seeds. Lacks explicit comparison to siblings (e.g., when to use polymarket_edges instead), but intra-tool guidance is strong.

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

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

The description details caching behavior (1h KV cache), response structure (by_segment, diagnostics), and filtering. It does not contradict annotations (readOnlyHint, etc.) and adds significant context on behavioral traits.

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

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

The description is very detailed and well-structured with numbered segments, but it is lengthy and contains dense jargon. It is front-loaded but 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 the complexity (9 parameters, three model families, nested response), the description thoroughly explains all aspects, including return structure and caching. No output schema exists, so this completeness is essential.

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

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

With 100% schema coverage, the description adds rich meaning to parameters, explaining tradeable-edge knobs, slippage handling, and filter behavior. It goes well beyond the schema descriptions.

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

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

The description clearly states the tool scans top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verb 'scan' and resource 'top Polymarket markets', and the distinct approach differentiates it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly says it's built for 'what should I bet on today' and helps agents discover opportunities without paging. However, it does not explicitly state when not to use it or compare to alternatives like polymarket_edge_tracker.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds important behavioral details: snapshots written on cache-miss, gaps mean no scan, 60-day TTL, decay from daily closes. No contradictions.

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

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

The description is well-structured and front-loaded with the main purpose. However, it includes extensive output format details that could be more concise, though they provide completeness.

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 complexity, full schema coverage, no output schema, the description compensates by detailing output structure (tracked, expired, snapshot_dates) and limitations. It is fairly complete.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds default and max for days and default for window, but little beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: edge persistence and decay telemetry from snapshots, answering how long an edge has existed and if it's shrinking. It distinguishes itself from sibling tools like polymarket_edges by adding temporal analysis.

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

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

The description implies when to use (to check edge age and trend) but does not explicitly state when not to use or compare to alternatives. The context is clear enough for an AI agent to infer usage.

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

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

Annotations indicate readOnlyHint=true, destructiveHint=false, and the description reinforces this as a non-destructive check. It adds behavioral details like walking the ladder, returning specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and warning about thin books and stranded 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 lengthy but dense with valuable information. It is front-loaded with the core purpose. While it could benefit from more structured formatting (e.g., bullet points for return fields), every sentence earns its place given the tool's complexity.

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

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

Despite lacking an output schema, the description enumerates all return fields and explains their significance (e.g., clean|degraded|cannot_fill verdict, thin_legs, forced_directional_risk). It also covers edge cases like partial fills and unhedged positions, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, and the description adds significant value beyond the schema: it clarifies the dual meaning of size_usd (max spend on buys vs target proceeds on sells) and the basket mode interpretation (settlement notional). It also explains the side defaults for basket mode.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check' and details two modes (single-market and basket). It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edges by specifying that it should be used before those tools for trades above ~$500.

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

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

Explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and warns about partial basket fills converting arb into 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 (non-destructive), idempotentHint=true, openWorldHint=true. The description adds significant behavioral context: it reveals that the tool computes spreads only when bet shapes are equivalent, details safety fields (compatibility_warning, temporal_alignment, skipped_cross_type), and warns that real spreads are rarer than the shortcut list suggests. No contradictions found.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds necessary detail. It could be slightly more concise, but front-loading the main purpose and using clear headings helps readability. No redundant information.

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

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

Given no output schema, the description thoroughly explains return fields (spread, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters) and their interpretation. It covers edge cases like non-equivalent bet shapes and temporal misalignment. For a complex tool with multiple safety mechanisms, the description is complete and leaves no major gaps.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value beyond schema by explaining the interaction between 'topic' and explicit parameters (override behavior), and provides examples in the schema. It clarifies that 'topic' auto-fetches events while explicit parameters allow custom pairs, but much of this is inferable from schema descriptions. Slight improvement over baseline 3.

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

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

The description starts with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly stating the verb (computes spread) and resources (Kalshi event, Polymarket event). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges, which focus on single-venue arbitrage or edges, by focusing on cross-venue comparison.

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 details two modes ('topic' shortcuts and explicit tickers), explains when to use each, and warns that most pre-mapped topics return compatibility warnings, implying when not to rely on the results. Safety fields like compatibility_warning and temporal_alignment tell the agent when spreads are meaningless, providing clear when-not-to-use guidance.

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

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

Annotations already indicate readOnly and idempotent; description adds scoping details and how it pairs with siblings, 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 essential, front-loaded with purpose, and no wasted words.

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

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

Given one parameter, annotations, and no output schema, the description fully covers purpose, usage, scoping, and parameter behavior.

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 baseline 3; description adds that omitting key lists all, providing extra meaning beyond the schema.

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

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

The description clearly states it retrieves a saved value or lists all keys, distinguishing it from siblings remember and forget with specific verbs and resource.

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 (look up context stored earlier), implies omission of key lists all, and scoping is explained.

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 an important behavioral trait: setting mark_read:true flags events as read, affecting future calls. This goes beyond annotations (readOnlyHint, idempotentHint) which only state safety. No contradictions with annotations.

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

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

The description is concise (three sentences) and front-loaded with the purpose. Information is presented in a logical order. Slightly more structure (e.g., bullet points) could improve readability, but it's not overly verbose.

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

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

Despite no output schema, the description explains the return content (source, citation_uri, payload) and filtering. It also covers side effects (mark_read) and provides an alternative access method. For a read-only tool, this is comprehensive.

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

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

Schema coverage is 100%, so baseline is 3. The description adds behavioral context beyond the schema, such as explaining that mark_read ensures 'the next call only shows newer ones' and that since filters by 'fired_at >= this time'. This added value justifies 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 'Pull fired events from your subscription feed' and specifies what each event carries (source, citation_uri, payload). While it doesn't explicitly differentiate from siblings like 'list_subscriptions' or 'recent_changes', the verb and resource are specific and unambiguous.

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

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

The description explains filtering options (type, since, limit, mark_read, unread_only) and notes that polls work fine. It also provides an alternative endpoint for scripts/dashboards. However, it doesn't explicitly state when not to use this tool compared to similar siblings, which prevents 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?

Describes fan-out behavior, source fallback (GDELT→GNews on rate limits/5xx), USPTO soft-fail, and return structure (grouped changes, total_changes, URIs). Annotations already declare read-only and idempotent; this adds rich 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?

Description is thorough yet efficient, front-loaded with example queries. All information is relevant, though slightly verbose in listing time-relative examples. 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?

With 3 parameters, 100% schema coverage, and no output schema, the description fully explains tool behavior, sources, fallback, and return structure. Provides enough context for correct invocation.

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

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

Schema coverage is 100%; description adds value by explaining 'since' accepts ISO or relative shorthand, recommends '30d', and clarifies 'value' accepts ticker or CIK. These details enhance usability beyond the schema.

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

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

Description uses specific verb+resource ('change feed for a company') and provides example queries that clearly define scope. Differentiates from sibling tool 'entity_profile' explicitly.

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 (change feed queries) and when not ('Use entity_profile for static profile'). Provides parameter recommendations (e.g., 'Use \"30d\" for typical monitoring').

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 (idempotentHint, destructiveHint), description adds persistence details (authenticated vs anonymous) and scoping. Minor missing: no explicit statement about overwrite, but idempotentHint covers it.

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. Efficient and clear.

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

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

Lacks return value description (no output schema), but for a simple store, the behavior is well-covered. Could mention confirmation, but not essential.

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 meaningful examples for keys and values (e.g., 'subject_property', 'target_ticker'), enhancing understanding 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 saves data for later reuse, gives specific examples (ticker, address, preference, subject), and distinguishes from sibling tools (recall, 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 (discover something worth carrying forward), pairs with recall/forget, and notes scoping by identifier and retention policies.

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 flag readOnly, idempotent, non-destructive, and openWorld. The description adds valuable context beyond that: it cascades through several internal endpoints (so it's a composite operation), auto-disambiguates inputs, and returns specific fields including citation URIs. This is a rich behavioral disclosure.

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

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

The description is longer than a minimal one but stays well-organized: it opens with example queries, defines the core purpose, then breaks down supported types with explicit details. The closing note about internal cascading is useful. Every sentence adds value, though the density of information makes it less 'punchy' than a two-sentence version.

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?

Since there is no output schema, the description fully covers return values by listing exact fields for each type (ticker, CIK, company_name, citation URI for company; RxCUI, ingredient, brand, citation for drug). It also covers input variations, auto-disambiguation, and replacement of manual lookups, making the tool fully understandable for selection and invocation.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds meaningful type-specific semantics: 'company' accepts ticker, CIK, or name with auto-disambiguation; 'drug' accepts brand or generic. It also specifies which return fields correspond to each type, enriching the schema without redundancy.

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

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

The description uses a clear verb 'resolve' and specifies the resource: user-spoken names are resolved to canonical/official identifiers. It provides concrete example queries and names the supported types (company, drug), distinguishing it from sibling tools like entity_profile by emphasizing it produces the ID inputs other tools require.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also explains that it replaces 2-3 manual lookups, but does not explicitly mention when not to use it or alternative tools, so it stops short of a full when/when-not comparison.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds key behavioral details: returns ranked list with score, confidence, signal density per entity. No contradictions.

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

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

Three sentences, front-loaded with main purpose. Each sentence adds distinct value without redundancy. No waste.

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?

Although no output schema, description explains return format (ranked list, score, confidence, signal density). Adequate for a composite tool given parameters are well-documented.

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 value beyond schema: notes 'first entry treated as subject for narrative' for entities, and 'omit for just workers-ai' for models, clarifying usage patterns.

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 'Compare AI visibility across multiple entities side-by-side' with specific verb (compare), resource (AI visibility across entities), and action (probes, ranks). Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 case: 'competitive AI-marketing audits' with example question. No explicit exclusions or alternatives, but context implies when to use (multi-entity comparison). Suggests it builds on ai_visibility_check, clarifying its composite nature.

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

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

Annotations declare readOnly, idempotent, and not destructive. The description adds valuable behavioral details: partial failures degrade gracefully, bundlephobia timeouts (5-30s), sources_failed listing, and the response structure. While comprehensive, it could be slightly more explicit about rate limits or authentication.

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

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

The description is front-loaded with the primary purpose and provides essential details in a logical order. Each sentence adds value without redundancy. Slightly verbose phrases like 'fans out' and 'degrade gracefully' are acceptable but prevent a top score.

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

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

Given no output schema, the description comprehensively explains the return value, listing all fields in the summary block and additional components (advisory detail, links, alternative versions). It also covers error behavior (partial failures, timeouts) and ecosystem scope, leaving no significant gaps.

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

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

Schema coverage is 100% with clear descriptions for both parameters (package name and version). The description repeats that version defaults to latest, adding minimal extra meaning. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: a composite check for deciding whether to add an npm package, integrating deps.dev and bundlephobia. It specifies the verb 'scan', the resource 'npm package', and distinguishes from siblings by focusing on dependency evaluation rather than general research.

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

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

Provides explicit usage context: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also states limitations ('NPM ecosystem only in v1') and directs users to other tools for other ecosystems, offering clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate safety (readOnly, idempotent). Description adds critical details: embedding model (BGE-base-en), window size (500-char overlapping), similarity metric (cosine), character limit (200K chars with truncation), and that passages carry offsets for verification.

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

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

The description is front-loaded with the main action, then splits into usage and technical details. Every sentence adds value, but the bullet-like technical details could be more concise. Still efficient overall.

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 compensates by stating return format (passages with offsets and scores), truncation behavior, and parameter constraints. Covers all necessary information for an agent to invoke the tool correctly.

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

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

Schema coverage is 100% but description adds value: explains 'text' as 'the document text', provides example queries for 'query', and clarifies 'limit' range. This goes beyond the schema descriptions.

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

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

The description uses a specific verb ('search') and specifies the resource ('record'), clearly distinguishing from siblings like 'ask_pipeworx_grounded' by stating it operates on an already-fetched record. Examples (SEC 10-K, article) solidify the purpose.

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 ('record is too big to cram into prompt') and mentions a complementary sibling ('Pairs with ask_pipeworx_grounded'). Provides clear context for usage.

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

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

The description discloses key behaviors beyond annotations: OAuth account requirement, delivery channel constraints (SMS 10/day, webhook auto-disable after 10 failures, secret one-time return). 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 well-structured with clear sections and examples, but is slightly verbose. Could be tightened without losing critical 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?

Given complexity, the description covers types, examples, delivery options, auth, rate limits, and webhook details. Missing explicit mention of idempotency or full response format beyond id.

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

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

Schema coverage is 100%, but the description adds significant value with concrete examples per type and delivery channel constraints (e.g., item codes for sec_8k, topic for polymarket_edge, SMS verification requirements).

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 'Create' and the resource 'proactive monitoring subscription to a live-data event stream'. It distinguishes from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

The description explicitly states the auth requirement and gives context for when to use (proactive monitoring). It does not mention alternatives or when-not to use, but the sibling list provides context.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it returns categorized examples with tool definition shapes from a live catalog of thousands of tools, which is valuable context beyond annotations.

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

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

Four sentences, each providing essential information. Front-loaded with natural language examples of queries. Could be slightly more concise, but no filler.

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

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

No output schema, but description adequately explains the return format (category-bucketed examples with tool+args) and the source (live catalog). Complete enough for an agent to understand what to expect.

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 only parameter. Description adds meaning by enumerating allowed topic values and explaining that omitting gives a cross-category spread, which goes beyond the schema's brief 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 tool returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself as the onboarding entry point, separate from other tools like ask_pipeworx or discover_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 the meta-tools. Provides guidance on omitting or passing topic. Lacks a when-not clause but is still 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?

Adds value beyond annotations: explains deactivation behavior, ownership check, and impact on historical events. Annotations (destructiveHint=false, idempotentHint=true) are consistent.

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

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

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

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

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

Covers all relevant aspects: action, ownership, persistence, and relation to sibling tool. No output schema needed; description is sufficient.

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

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

Schema coverage is 100% with a clear description for 'id'. Description adds no additional parameter information 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?

Clearly states the tool cancels a subscription by ID. Distinguishes 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?

Provides explicit context: ownership enforcement, deactivation not deletion, and link to 'recent_alerts' for history. No explicit when-not-to-use, but clear enough.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description details internal mechanics: SEC EDGAR + XBRL fast path for financial claims, grounded pipeline for others, return format (verdict, actual value with citation, reasoning), and efficiency gain over sequential calls.

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

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

The description is quite long but well-structured: starts with trigger phrases, defines purpose, explains dual pipeline, lists return values, and notes efficiency. Every sentence adds value, though some trimming could improve conciseness.

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

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

Given the tool's complexity (two processing paths, no output schema), the description is remarkably complete. It covers input format, internal routing, return fields (verdict, value, reasoning), and parameter nuances, leaving minimal gaps for an agent.

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

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

The description enriches both parameters: for 'claim' it provides natural-language examples and clarifies it's any factual claim; for 'tolerance_pct' it explains default behavior (implied from wording, capped at 5) and suggests use cases like setting 1-2 for hallucination detection, adding 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 verifies natural-language factual claims with examples like 'fact check' and 'verify the claim that...'. It distinguishes between company-financial claims and other factual claims, specifying the different processing paths, which sets it apart from sibling tools.

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

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

The description explicitly says to use this tool 'whenever the agent needs to check whether something a user said is factually correct.' It provides good context for when to use but does not explicitly list cases where it should not be used or direct alternatives.

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