Unhcr

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

The description adds significant behavioral context beyond annotations: default model is free, Anthropic requires BYO API key, and the return structure includes per-model details and a combined view. No contradictions with annotations (readOnlyHint, idempotentHint, destructiveHint).

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

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

The description is three sentences, front-loaded with the main action, and each sentence serves a distinct purpose: action+output, details on models and return, and use cases. No wasted words.

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

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

Given the moderate complexity, no output schema, and full parameter coverage, the description explains the return format and model options adequately. It covers all necessary information 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 has 100% coverage with descriptions for all 4 parameters. The description further clarifies the default model for the 'models' parameter, the BYO key for '_apiKey', and the disambiguation role of 'context'. This adds meaning beyond the schema.

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

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

The description uses a specific verb ('probe') and resource ('LLMs for what they know about a business/brand/product/topic') and clearly states the output (score 0-100 per model). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on visibility scoring and default free model.

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 mentions use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' However, it does not provide explicit when-not-to-use guidance or differentiation from the sibling 'scan_competitor_ai_presence'.

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

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

Description adds significant context beyond annotations: explains routing to 3,745 tools, fills arguments, returns structured answers with citation URIs. Annotations already provide read-only, open-world, idempotent hints. No contradictions.

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

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

Description is front-loaded with key preference statement, well-structured with list of domains, mechanism, cue words, and examples. Slightly long but each sentence adds value.

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

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

For a complex tool with no output schema, description covers sourcing mechanism, citation URIs, and example queries. Lacks guidance on handling ambiguous or multi-step questions, but generally 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%, so description need not add parameter details. It does not provide additional semantics beyond schema, meeting 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?

Description clearly states the tool answers factual questions by routing to thousands of verified sources, with specific verb 'ask' and resource 'Pipeworx'. Provides concrete examples and distinguishes from web search.

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

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

Explicitly recommends this tool over web search for a wide range of structured data queries, lists trigger phrases and examples. However, does not mention when NOT to use it or alternatives like 'ask_pipeworx_grounded'.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds valuable context: costs one extra LLM call, returns explicit refusal reasons, and specifies that answers are extracted only from tool results. 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 fairly concise given the amount of information. It front-loads the core purpose and usage guidance. A minor deduction for slight wordiness, but every sentence adds value.

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

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

Handles complexity well: explains routing across many tools, return format with confidence and evidence, refusal reasons, and cost trade-off. Even without an output schema, the description thoroughly covers expected outcomes.

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

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

Schema coverage is 100% with detailed descriptions for each parameter alias. The description adds context that the tool fills arguments but doesn't provide additional parameter-level details beyond what schema already offers. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads. It explains the process (same routing as ask_pipeworx, extracts answer only from tool result), and distinguishes it from the sibling ask_pipeworx.

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 an answer will be quoted, cited, or acted on' and when not: 'prefer ask_pipeworx for casual lookups.' Also describes refusal conditions, providing clear guidance for the agent.

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

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

Annotations already indicate the tool is read-only, idempotent, and non-destructive. The description adds that rows carry specific fields (procedure_type, app_type, dec_level, applied count) and that response.total.applied is the aggregate, providing marginal behavioral context beyond annotations.

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

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

The description is concise (two sentences) and front-loaded with the main purpose. Every sentence adds value: the first states the core function, the second explains row fields and aggregate. 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?

With 6 parameters, no output schema, but rich annotations, the description covers the key aspects: row fields, aggregate, and code reference. It lacks details on pagination behavior (e.g., default limit, page handling), but these are documented in the schema. Overall, it is sufficiently complete for an agent to understand the tool's use.

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

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

The parameter schema has 100% coverage with descriptions for all 6 parameters. The description adds that 'coo' and 'coa' use UNHCR 3-letter codes and references 'list_countries', but this is already partially implied by schema descriptions. The description does not significantly enhance parameter 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 retrieves asylum applications lodged by year, country of origin, and country of asylum. It specifies the verb 'lodged' and the resource 'asylum applications', and distincts from sibling tool 'asylum_decisions' which deals with decisions. The mention of row fields and aggregate further clarifies 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?

The description provides clear context for usage, referencing 'list_countries' for code formats and implying the tool is for querying application data. However, it does not explicitly state when not to use this tool or provide alternatives, which would justify a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by listing the output fields (dec_recognized, dec_other, etc.) and how response.total aggregates them. It also specifies the code format. No contradictions with annotations.

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

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

Two sentences, no filler. The first sentence immediately conveys purpose and dimensions. The second adds output field details and a code hint. Well front-loaded and efficient.

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

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

Given all parameters are optional and schema covers them, the description completes the picture by naming the output fields, explaining aggregation, and providing code usage guidance. No output schema exists, so the description fills that gap adequately.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minor value by mentioning that coo/coa take UNHCR 3-letter codes from list_countries, but it does not clarify page/limit defaults or date range usage beyond what the schema provides.

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

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

The description clearly states the resource (asylum decisions) and the dimensions (year, country of origin, country of asylum). It distinguishes from sibling tools like asylum_applications (applications vs decisions) and list_countries (just codes). The verb 'Decisions on' combined with the specific fields names the tool's exact 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?

The description provides a usage hint by referencing list_countries for valid UNHCR codes. It implies the tool is for decision counts, distinct from asylum_applications. However, it does not explicitly state when not to use it or name alternative tools for different scenarios.

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

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

The description exhaustively discloses behavior: market resolution, classification, parallel fan-out, response shapes, safety mechanisms (low-confidence short-circuit, closed market handling, wide spread warning), resolution rule risk, and parent event extraction. It warns agents about inspecting market_match_confidence. Annotations confirm read-only, idempotent, non-destructive; description adds critical operational details.

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 (~650 words) but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, etc.). It is front-loaded with purpose and usage. While not concise, the structure aids navigation for an AI agent, justifying the length for a complex tool.

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

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

Given no output schema, the description fully explains all return fields: market match confidence, analysis with edge calculations, evidence sources by key, parent event data, news fallback handling, and safety/blocking conditions. It covers edge cases (low-confidence, closed markets, wide spreads, resolution rules). The description is self-contained and comprehensive.

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

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

Schema coverage is 100% with all parameters described. The description adds value beyond the schema: examples for market input format, clarity that depth defaults to thorough, and that include_raw defaults false with rationale. This compensates for the schema's brevity, though some redundancy exists.

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

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

The description specifies the tool researches Polymarket bets by pulling Pipeworx data, accepting slugs, URLs, or question text. It clearly outlines the output (evidence packet + market-vs-model comparison). The verb 'Research' and resource 'bet' are distinct and cover the tool's action comprehensively, though sibling differentiation is implicit.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides context but does not explicitly exclude alternatives or mention sibling tools (e.g., polymarket_edges, polymarket_arbitrage). The guidance is clear and context-rich, missing only exclusionary notes.

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 safe, read-only operation. The description adds rich behavioral details: for companies it pulls latest 10-K financials from SEC EDGAR/XBRL with correct fiscal year handling; for drugs it pulls FAERS data, FDA approvals, trial counts. It also explains sorting by primary metric and citation URIs, providing full transparency.

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

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

The description is thorough but slightly verbose. However, it front-loads example triggers and immediately establishes the tool's value. Every sentence adds meaningful information, but minor tightening 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?

Despite lacking an output schema, the description fully explains what the tool returns (paired data, citation URIs, sorted results) for both entity types. It covers data sources, edge cases (off-calendar fiscal years), and the 'max 5 items' constraint, making it complete for an agent to use correctly.

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

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

Schema covers both parameters 100%. The description adds significant meaning: explains that 'type' selects between company and drug, and 'values' expects tickers/CIKs for company or drug names. It also describes the output behavior, enriching the parameter semantics considerably.

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

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

The description clearly states the tool does side-by-side comparison of companies or drugs in a single call, with specific triggers like 'X vs Y' and 'which is bigger'. It distinguishes itself from sequential lookups by emphasizing parallelism.

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

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

The description explicitly says to prefer this tool over sequential single-pack lookups when comparing entities, providing clear guidance on when to use it and contrasting with 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 provide safety hints. Description adds significant behavioral context: decomposition, parallel routing, grounded extraction with explicit gaps, citation format, and time expectations. 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 denser than necessary but front-loads the key purpose. Every sentence adds value, though slight reduction 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 high complexity, the description covers all essential aspects: output format (findings packet, gaps), prerequisites (account, plan), and behavioral traits. No output schema is present, but description compensates well.

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

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

Schema coverage is 100% with descriptions. Description adds meaning: explains depth values ('quick=3, standard=5, thorough=8') and clarifies that 'decomposition is the point' for the question parameter.

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

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

The description clearly states the tool's function: 'Grounded multi-source research in ONE call.' It explains decomposition, parallel routing, and evidence extraction, distinguishing from sibling ask_pipeworx for single 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?

Explicit guidance on when to use: 'Use for broad or multi-part questions' versus ask_pipeworx for single lookups. Also mentions account requirements, depth limits, and time expectation.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by detailing return payload: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' 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 3-4 sentences with no wasted words. It front-loads the primary action and quickly covers when to use, what it returns, and a strategic recommendation. Every sentence serves a distinct and valuable purpose.

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

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

Given the tool's complexity (6 parameters, many siblings, no output schema), the description covers all needed aspects: purpose, usage context, return contents, and strategic placement. It is self-contained and leaves no gaps for an AI agent to guess 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?

Input schema has 100% coverage with descriptions for all 6 parameters. The description adds meaning by explaining that 'query' accepts natural language and lists aliases ('Accepts task, q, description, search as aliases'), which simplifies usage beyond schema documentation. Examples in schema further clarify.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It specifies a specific verb ('find') and resource ('tools'), and distinguishes it from sibling tools by noting it should be called first when exploring available tools, not for direct answers.

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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and provides specific domains. Also advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and exclusion criteria.

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

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

Annotations already indicate readOnly, idempotent, and openWorld hints. The description adds significant behavioral context: it fans out across multiple data sources (SEC, XBRL, USPTO, news, GLEIF), returns specific fields like recent filings with URIs, and discloses that the patents API sunset in May 2025 with a soft-fall mechanism. This goes well 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 well-structured, starting with examples, then behavioral guidance, then detailed output. Every sentence adds value, but it is somewhat lengthy. Given the complexity of the tool, it is appropriately detailed, though a minor trim 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?

Despite lacking an output schema, the description thoroughly explains the return structure: CIK, company name, recent filings (with URI format), fundamentals (sorted period_end DESC), patents (with note on sunset), news fallback, and LEI. It covers input limitations, data sources, and edge cases, making it fully complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds crucial context: the 'type' parameter is currently limited to 'company', and 'value' must be a ticker or zero-padded CIK (names not supported). It provides concrete examples like 'AAPL' and '0000320193', clarifying the exact format required.

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 multiple natural language example queries like 'Tell me about X' and 'company profile for Microsoft', clearly indicating the tool's purpose of providing a holistic cross-source profile for US public companies. It distinguishes itself from sibling tools like 'resolve_entity' (which resolves names to identifiers) by emphasizing it is the preferred tool for holistic views.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing clear guidance on when to use this tool. It also notes that names are not supported and advises using 'resolve_entity' first if only a name is available, offering specific alternatives and 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 destructiveHint=true, and the description reinforces this by saying 'Delete' and 'clear sensitive data'. It adds useful context about the timing and reasons for deletion, but doesn't disclose additional behavioral details like auth requirements or irreversibility beyond what annotations imply.

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 with no redundancy. The action is front-loaded, and every sentence adds value: what it does, when to use, and how it relates to siblings.

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 one-parameter tool with full annotation coverage, the description is complete. It covers purpose, usage context, behavioral notes, and sibling relationships. No output schema is needed.

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

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

Schema coverage is 100% with a single required string parameter 'key' described as 'Memory key to delete'. The description adds no additional semantic detail beyond the schema, so baseline 3 is appropriate.

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

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

The description starts with 'Delete a previously stored memory by key', providing a specific verb and resource that clearly distinguishes it from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: when context is stale, task is done, or to clear sensitive data. Also suggests pairing with 'remember' and 'recall', giving clear guidance on when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds context on what it fetches (page, title, description, key links) and the output format (standard llms.txt markdown), which enriches behavioral understanding beyond annotations.

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

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

The description is concise with two functional sentences and a list of use cases. Every sentence adds value, 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 the low complexity (2 params, no output schema), the description fully covers the tool's purpose, behavior, output format, and appropriate use cases. No gaps.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add additional semantic value beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Generate' and resource 'llms.txt file for any URL'. It distinguishes from siblings by specifying the output format and use cases like getting a client's site indexed or auditing competitor AI visibility.

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

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

The description provides explicit use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor') but does not explicitly state when not to use or mention alternatives like scan_competitor_ai_presence.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. Description adds that the list is large and paginated with maxPages, and reveals the response structure (each item has code, iso, etc.), complementing 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?

Single paragraph, front-loaded with purpose. Each sentence adds value: purpose, usage, structure, pagination hint. 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?

Two parameters adequately explained. No output schema but description details response structure (code, iso, iso2, name, region, majorArea) and pagination hints. Sufficient for a read-only reference list tool.

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

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

Schema provides 100% coverage for both parameters (page, limit). Description adds context 'large list, raise limit' and '1-based page', but the schema already describes them adequately. The description's extra usage hint is minor.

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

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

Description clearly states it is a reference list of countries/territories tracked by UNHCR, used to map country names to codes. This distinguishes it from sibling tools like validate_claim or asylum_applications.

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

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

Explicitly instructs to use the tool for mapping country names to codes (coo/coa) in other tools. Mentions pagination and adjusting limit/page. Lacks explicit when-not-to-use, but context is clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact returned fields (id, type, params, created_at, etc.) and implying default behavior (active only). 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 two sentences: first defines purpose and outputs, second gives usage context. Every word is necessary and front-loaded. No redundancy.

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

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

Despite lacking an output schema, the description lists all returned fields. The single optional parameter is explained in the schema. The tool is simple, and the description covers all necessary 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?

The only parameter (include_inactive) is fully described in the schema with its default value. The tool description does not add additional semantic meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions', specifying the verb (list), resource (subscriptions), and scope (caller's active). It also lists the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly advises when to use this tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and directs the agent away from alternative tools.

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

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

Annotations are minimal (all false), but the description adds key behavioral traits: rate-limited to 5 per identifier per day, free, and does not count against tool-call quota. This exceeds what annotations provide, though it could mention if responses are immediate.

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: main action, usage guidelines, and behavioral notes. It is front-loaded with the key purpose. While slightly long, every sentence adds value, earning a high score for clarity without unnecessary verbosity.

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

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

Given no output schema, the description covers what to expect: the team reads digests daily and feedback affects roadmap. It also mentions rate limits and quota. For a feedback tool, this is complete enough for an agent to understand the tool's role and constraints.

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 documented. The description adds context around the 'type' enum and advises on message formatting (e.g., be specific, 1-2 sentences, 2000 chars max). This provides meaningful interpretation beyond the schema.

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

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

The description clearly states the tool is for sending feedback to the Pipeworx team, listing specific categories (bug, feature, data_gap, praise, other). It distinguishes itself from siblings like ask_pipeworx by focusing on reporting issues or praising, not asking questions.

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

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

The description provides explicit guidance on when to use each feedback type and what to include (e.g., 'describe the issue in terms of Pipeworx tools/packs'). However, it does not explicitly state when not to use the tool or name siblings as alternatives, though context from the sibling list implies differentiation.

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

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

The description adds significant behavioral context beyond annotations: mentions source (CF analytics-engine), no PII, caching behavior (5min-1h), and self-aggregating nature. No annotation 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 paragraphs with clear sections; no wasted words. Could potentially combine the use-case list into a single line, but overall efficient.

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

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

Given one optional parameter, no output schema, and low complexity, the description covers return type (top tools, packs, volume) and caching details sufficiently. Agent can correctly invoke without ambiguity.

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

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

The single 'window' parameter is fully covered by schema (100% coverage with enum and description). The description adds value by explaining the trade-off between shorter and longer windows for different use cases.

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

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

The description clearly states the tool returns trending usage data ('top tools, top packs, and total call volume') and distinguishes itself as a self-aggregating analytics tool, not another tool-calling or data-retrieval function.

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

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

The description provides three explicit use cases (discovering hot data, confirming canonical tools, checking alignment) and explains window semantics, but does not directly contrast with sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds significant detail: monotonicity checks, partition validation, semantic anchor using Jaccard similarity, partition filter for placeholder slugs, and fill check against CLOB depth. No contradictions with annotations.

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

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

The description is dense but well-structured, front-loaded with the requirement and core purpose. Every sentence adds value, though the length is justified by the tool's complexity. Could benefit from bullet points for readability, but overall efficiently conveys needed information.

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

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

Given the tool's complexity, the description covers purpose, modes, algorithms, error conditions, and references to sibling tools. Output structure is outlined (opportunities array, partition_check object, fill_check details). Without an output schema, the description compensates well. Slight gaps in explaining 'monotonicity violation context' fully, but still complete for an arbitrage tool.

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

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

Schema description coverage is 100% for the two parameters. The description adds substantial context beyond the schema: explains how each mode works (walks child markets for 'event', searches related events for 'topic'), and includes algorithmic constraints (semantic anchor, partition filter). This enriches understanding beyond the parameter descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies two distinct modes (event and topic), differentiating it from siblings like polymarket_edges and polymarket_fill_risk. The verb 'Find' and resource 'arbitrage opportunities' are precise.

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

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

Explicitly states the requirement to provide one of 'event' or 'topic', warns that calling with no args fails, recommends 'event' for specific markets and 'topic' for cross-event scanning. It also directs users to 'polymarket_fill_risk' for custom sizing, providing clear when/when-not/alternatives 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?

The description goes far beyond the annotations. It details the three model families with specific formulas (e.g., lognormal barrier, GDELT ratio), caching behavior ('Cached 1h at the KV level'), response structure including diagnostics, and tradeable-edge knobs. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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 headings, but it is quite long and dense. It could be more concise while retaining the important details. The front-loading of purpose is good, but the verbosity reduces clarity.

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

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

The description is extremely complete, covering input knobs, output structure (by_segment, fed_candidates, diagnostics), caching, and edge-case behavior (e.g., 'partitions with >20% placeholder fraction skipped entirely'). Without an output schema, it fully explains return values.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant value by explaining each knob's impact (e.g., 'min_liquidity: Set to 5000 to drop thin-book opportunities where executing the edge would walk the book past breakeven'), which is beyond 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 starts with a clear verb ('Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price') and explicitly states its target use case ('Built for 'what should I bet on today''). It distinguishes itself from siblings like 'polymarket_arbitrage' and 'bet_research' by detailing its unique model-driven and structural arbitrage approach.

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

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

The description provides strong context for when to use the tool (discovering betting opportunities) and includes parameter knobs for filtering (e.g., min_kelly, min_edge_pp). However, it does not explicitly state when not to use it or compare to alternatives like 'bet_research', 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?

The description goes well beyond annotations, detailing the response structure (tracked, expired, snapshot_dates), how data is computed (decay from daily closes), and limitations (60-day TTL, data gaps). It provides full behavioral transparency without contradicting annotations.

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

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

The description is detailed and front-loaded with the core question. While it is verbose, every sentence adds value. Minor use of ALL CAPS for emphasis is acceptable. It is well-structured with clear sections.

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

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

Without an output schema, the description fully explains the return value (tracked, expired, snapshot_dates) and limits. Parameters are optional and well-documented. The tool's complexity is adequately covered for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds minimal extra meaning beyond the schema, restating default and max/clamp values. It does not provide new semantic details about how parameters affect behavior beyond what is in the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and if it's shrinking. It uses specific verbs and distinguishes its role from sibling tools like polymarket_edges by focusing on historical tracking.

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 the tool (for understanding edge persistence) but does not explicitly mention alternatives. It provides context on the value of historical vs. fresh edges and includes usage constraints like limits, but lacks explicit 'when not to use' guidance.

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

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

Discloses detailed behavioral traits: walks order book ladder, returns multiple fields (top_of_book, vwap_fill_price, slippage, etc.), and warns about partial fill risks. Annotations already indicate read-only, idempotent, non-destructive; description adds crucial execution context without contradiction.

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

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

Well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET). Front-loaded with purpose, all sentences are informative. Length is appropriate given complexity.

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

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

No output schema, but description fully covers return fields for both modes. Addresses risks, usage context, and parameter details. Complete for complex tool with four parameters and two modes.

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

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

Schema has 100% coverage, but description adds significant meaning: explains when to use market vs event, side defaults for basket, and size_usd interpretation as settlement notional. Goes beyond 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?

Clearly states it checks realizable vs theoretical edge against live CLOB depth. Distinguishes two modes (single-market and basket) and specifies the verb 'check' against order-book depth, making it distinct from siblings 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?

Explicitly instructs to use before acting on polymarket_arbitrage signals or large edge trades. Explains consequences of not using (unfillable theoretical overround, partial basket fills causing directional risk). Provides clear mode selection 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 and non-destructive; description adds significant context: compatibility_warning scenarios, temporal alignment checks, skipped cross counters, and real-world tradeability warning. No contradiction with annotations.

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

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

Well-structured with clear sections (overview, modes, response, safety fields). Some redundancy (e.g., twice warns pre-mapped not tradeable) but justified by complexity. Could be slightly more concise.

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

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

For a tool with 3 parameters, complex behavior, and no output schema, the description is very complete. Explains response structure, safety fields, temporal alignment, and skipped counters. 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 covers 3 parameters with descriptions (100% coverage). Description adds value by explaining modes, override behavior, and providing examples, beyond what schema alone conveys.

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

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

Clearly states it computes cross-venue spread between Kalshi and Polymarket for the same question, distinguishing from siblings like polymarket_arbitrage. Specific verb ('compute spread') and resource ('cross-venue price differences').

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

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

Explicitly describes two modes (topic shortcuts and explicit pairs), when to use each, and when spreads are meaningful (compatibility_warning, temporal_alignment). Warns that most pre-mapped topics are not tradeable. However, does not directly compare to alternatives like polymarket_arbitrage.

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 and idempotent behavior. The description adds useful context: pagination (page, limit), year range, and the breakdown logic for coo_all/coa_all. 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 informative and relatively concise, but the run-on sentence structure could be improved by breaking into shorter sentences or bullet points for clarity.

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

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

The description covers key aspects of usage and parameters. However, without an output schema, it could mention the response structure (e.g., pagination fields like maxPages) to be fully complete.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema, such as explaining the UNHCR 3-letter code format, the behavior of boolean parameters, and the inclusive year range.

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

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

The description clearly states the tool retrieves forcibly displaced and stateless persons data by year and country, listing specific population categories (refugees, asylum_seekers, etc.). It distinguishes from sibling tools like asylum_applications by covering multiple displacement types.

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

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

The description explains when to use coo_all/coa_all and warns about UNHCR code format, directing users to list_countries. However, it does not explicitly state when not to use this tool or mention alternatives.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by explaining scoping (by identifier) and behavior when key is omitted (list all). 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 efficient paragraph with clear structure: core functionality first, usage cases second, scope third, pairing fourth. No superfluous 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 low complexity (1 param, no output schema, clear annotations), the description covers usage, scope, and pairing. Not specifying return format is acceptable as the tool's purpose is straightforward (return a value or list). Minor gap: could mention that returned value is the stored data.

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 for the single optional parameter 'key', baseline is 3. The description restates that omitting key lists all (already in schema's description) but adds context about retrieval purpose. Minimal new semantic 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 retrieves a previously saved value or lists all keys, using specific verbs 'retrieve' and 'list'. It distinguishes from sibling tools 'remember' and 'forget' by naming them directly.

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

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

The description provides clear usage context: 'look up context the agent stored earlier' and gives examples (ticker, address, notes). It recommends pairing with remember/forget. However, it does not explicitly state when not to use or compare with alternatives beyond siblings.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description details output structure, filter semantics, mark_read flag behavior, and poll-friendliness. No contradiction with annotations.

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

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

Four sentences, each with distinct purpose: what it does, what returns, how to filter/use, and note on alternative access. No filler, front-loaded.

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

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

Explains output fields, filter parameters, and polling suitability. Lacks explicit error handling or pagination details but given annotations and schema, is reasonably complete for a read-only list tool.

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

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

Schema has 100% coverage with descriptions. Description adds usage examples (e.g., 'sec_8k' for type, ISO timestamp) and explains mark_read side effect, enriching understanding beyond schema alone.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies the returned fields (source, citation_uri, raw event payload), and distinguishes from sibling tools like list_subscriptions and subscribe/unsubscribe.

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

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

Provides filtering guidance (type, since), explains mark_read behavior, and mentions polling vs. direct REST endpoint. Does not explicitly contrast with all sibling tools but gives enough context for appropriate 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 mark the tool as readonly, open-world, idempotent, and non-destructive. The description adds substantial behavioral context: it fans out to multiple sources (SEC EDGAR, GDELT→GNews fallback, USPTO with sunset note), explains the fallback mechanism between GDELT and GNews, and describes the output structure (grouped changes, total count, citation URIs). This goes well beyond what annotations provide.

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

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

The description is well structured: it opens with purpose and example queries, then explains the multi-source behavior, parameter details, output summary, and finally an alternative tool. Every sentence adds value, though the description is somewhat long. It could be slightly tightened without losing information, but it remains highly 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?

Given the tool's complexity (three required parameters, multi-source aggregation, fallback logic, date parsing) and the absence of an output schema, the description is remarkably complete. It covers all input nuances, the internal fan-out and fallback behavior, output structure, and a notable limitation (USPTO API sunset). An agent receiving this description has sufficient information to use the tool correctly.

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

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

Although schema description coverage is 100%, the description enriches parameter semantics significantly. For 'since', it explains both ISO date and relative shorthand formats with examples ('2026-04-01', '7d', '30d', '3m', '1y') and recommends '30d' or '1m' for typical monitoring. For 'value', it clarifies that it accepts ticker or zero-padded CIK. For 'type', it notes only 'company' is supported, which is not in the schema.

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

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

The description starts with concrete examples ('What's new with X', 'latest on Y') and clearly states the tool's purpose: a change feed for a company aggregating SEC filings, news, and patents. It distinguishes itself from the sibling tool entity_profile by noting that entity_profile provides a static profile instead of a dynamic change feed.

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

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

The description explicitly tells when to use this tool vs alternatives with the sentence: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' It also provides example queries ('updates on Acme', 'news on Tesla recently') that help the agent choose the right tool for the user's intent.

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 idempotentHint true and destructiveHint false. Description adds beyond: explains scoping by identifier, persistence differences for authenticated vs anonymous users (24-hour retention). No contradictions.

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

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

Four sentences, front-loaded with purpose, each sentence adds distinct information (purpose, usage trigger, behavior, pairing). No wasted words.

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

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

For a simple write tool with 2 parameters and no output schema, the description covers purpose, usage guidance, persistence behavior, and pairing with sibling tools. 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 descriptions for key and value. Description adds minimal extra meaning beyond the schema (e.g., examples of keys and note that value is any text). The description's value is more in usage context than parameter detail.

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

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

The description states a specific verb 'Save' and resource 'data the agent will need to reuse later', clearly distinguishing it from sibling tools like recall and forget. It also provides examples of what to store (resolved ticker, target address, etc.) and emphasizes cross-session persistence.

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 you discover something worth carrying forward'. Mentions alternatives: 'Pair with recall to retrieve later, forget to delete'. No explicit when-not, but the condition is clear enough.

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

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

Annotations indicate readOnly, openWorld, idempotent, and not destructive. The description adds that the tool cascades through several endpoints, replacing 2-3 manual lookups, which provides behavioral context beyond annotations without contradiction.

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

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

The description is concise and well-structured, starting with example queries, then usage hint, then detailed type information. Every sentence serves a purpose, and it is appropriately sized.

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 specifies return fields (ticker, CIK, company_name, citation for company; RxCUI, ingredient, brand, citation for drug) and explains internal cascading. This provides sufficient completeness 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%, and the description adds meaningful detail: for 'company' it lists acceptable inputs (ticker, CIK, name) and auto-disambiguation; for 'drug' it mentions brand/generic names. This adds value beyond the schema.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with example queries and supported types. It distinguishes itself by specifying it returns IDs needed by other tools, versus siblings that likely do different things.

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

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

The description says 'Use FIRST whenever you have a name but need an ID,' providing clear contextual guidance. It lacks explicit when-not-to-use or alternatives, but the context is sufficient for an agent to decide.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds that it probes each entity, ranks by score, and treats first entity as subject for narrative. 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, all valuable. Front-loaded with purpose. No unnecessary words.

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

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

Given 4 parameters with full schema coverage, rich annotations, and description explaining return format (ranked list with score, confidence, signal density), the tool is fully contextualized.

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 semantic detail: entities must be 2-8, first is subject; models default to workers-ai; _apiKey only needed if anthropic in models. Adds 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?

Clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally. Distinguishes from sibling ai_visibility_check which is for single entity checks.

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

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

Explicitly mentions use case for competitive AI-marketing audits. Implies alternative of ai_visibility_check for single entity. Does not explicitly state when not to use, but context is sufficient.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds significant behavioral context: composite fan-out, partial failure graceful degradation, bundlephobia first-measurement delay (5-30s), and details on returning sources_failed.

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 long but every sentence serves a purpose. It front-loads the core purpose and follows with essential usage details, limitations, and output structure. Some minor redundancy could be trimmed but overall efficient.

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

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

Despite no output schema, the description thoroughly details return fields (summary block, per-advisory, links, alternative versions) and error handling (sources_failed). It also covers ecosystem scope and timing behavior, making it fully complete for an agent to understand behavior and results.

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

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

Schema covers both parameters with descriptions. The description adds that scoped packages are accepted and that version defaults to latest, providing extra clarity beyond the schema.

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

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

The description clearly states it performs a composite npm package safety/popularity check using deps.dev and bundlephobia. It uses specific verbs and resources, and distinguishes from sibling tools by its unique aggregation of multiple data sources.

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

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

Explicitly tells when to use: when an agent asks about safety, popularity, or cost of an npm package. Also notes limitations (NPM only in v1, partial failures) and alternatives (use deps.dev directly for other ecosystems).

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 significant behavioral context: uses BGE-base-en embeddings + cosine, 500-char overlapping windows, 200K char cap with truncation and flagging, returns character offsets and similarity scores. No contradictions.

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

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

Four sentences total, each earning its place. Front-loaded with purpose, then usage guidelines, then behavioral specifics, and finally technical details. No redundancy, efficient wording.

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

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

No output schema exists, but the description compensates by stating what is returned (top-N passages, offsets, similarity scores). It covers input constraints, embedding model, window size, cap, and pairing with sibling tool. Complete for this complexity level.

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

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

Schema coverage is 100% with all three parameters described in both schema and description. Description adds examples for 'query' (e.g., 'supply-chain risk'), clarifies default for 'limit' (5), and explains max chars for 'text'. Adds significant 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 starts with 'Semantic search INSIDE a fetched record,' clearly specifying the verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and using examples like 'SEC 10-K body, an article.'

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

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

Explicitly states when to use: 'when the record is too big to cram into the prompt.' Also provides an alternative: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages.' Mentions truncation cap of 200K chars, guiding appropriate 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 mutation (non-readOnly), idempotency, and non-destructiveness. The description elaborates with constraints like phone verification, SMS cap, webhook signing details, and auto-disable behavior, adding value beyond annotations.

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

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

The description is well-structured with clear sections but slightly verbose, especially the webhook signing details. It front-loads the core purpose, though some details could be trimmed without losing clarity.

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

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

Given the tool's complexity (3 parameters, nested objects, no output schema), the description covers all critical aspects: return value, auth requirements, type-specific filters, delivery options, and constraints like rate limits. 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?

Despite 100% schema coverage, the description provides rich additional meaning: example parameter values for each type, interpretation of items codes like '5.02 = officer change', and detailed delivery channel constraints that clarify schema definitions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream, with a specific verb (create) and resource (subscription). It effectively distinguishes from siblings like list_subscriptions and unsubscribe.

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

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

The description provides good usage context: requires Pipeworx OAuth account, lists supported types with examples, and explains delivery channels. However, it lacks explicit guidance on when not to use this tool (e.g., for one-time data retrieval) or alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it returns category-bucketed examples and tool+argument shapes, and serves as the onboarding entry point. 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?

Description is long but packed with information. Uses slash-separated alternatives and multiple clauses. Could be slightly more concise but well-structured with clear sections.

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

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

Given no output schema, description explains what is returned (category-bucketed example questions with tool+argument shapes). Covers usage patterns with and without topic. Complete for a simple one-param tool with good 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 coverage 100% with description for 'topic' parameter. Description adds meaning by listing example values (finance, pharma, etc.) and explaining behavior when omitted (full spread). Adds value beyond schema.

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

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

Description clearly states it's the onboarding entry point that returns example questions with tool+argument shapes. Distinguishes from siblings by explicitly mentioning it's for learning what Pipeworx can do and how to call meta-tools.

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

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

Explicit guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to omit or specify the topic parameter. Does not explicitly exclude other use cases, but sufficiently clear.

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

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

Discloses critical traits beyond annotations: idempotentHint and destructiveHint are confirmed by 'deactivated not deleted'; adds ownership enforcement. No contradictions.

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

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

Two concise sentences, front-loaded with purpose followed by constraints and side effects. No extraneous information.

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

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

For a simple cancel/delete tool with one parameter, description covers purpose, ownership, side effect (deactivation), and cross-reference to recent_alerts. 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?

Single parameter fully described by schema (coverage 100%), description adds no extra meaning beyond 'by id'. Baseline score 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 action ('Cancel a subscription by id') and the specific behavior ('deactivated, not deleted'), distinguishing it from siblings like subscribe and list_subscriptions.

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

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

Explicitly states ownership enforcement ('only cancel your own subscriptions'), implying when not to use it (others' subscriptions), but does not mention alternatives like permanent deletion.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: returns a verdict (confirmed, approximately_correct, etc.), extracted structured form, actual value with citation, and percent delta. No contradictions.

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

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

The description is well-structured with trigger phrases upfront, followed by purpose, scope, and return details. It is slightly lengthy but each sentence adds value, so no wasted words.

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

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

For a single-parameter tool with no output schema, the description fully explains what it does, what it returns, and its domain. It is complete for an agent to understand its use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing examples of natural-language claims and clarifying the type of claims accepted, which enriches the schema's parameter description.

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

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

The description clearly states the tool is for natural-language claim verification against authoritative sources, with specific trigger phrases and domain (company-financial claims). It distinguishes itself from siblings by being a composite tool that replaces multiple sequential calls.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the supported claim types and what it replaces. No explicit when-not-to-use or alternatives, but the context is clear.

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