Unhcr

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

Annotations confirm read-only, idempotent, non-destructive behavior. The description adds that Workers AI is free, Anthropic requires a key and external payment, and the return format includes per-model details and a combined view. No contradictions with annotations.

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

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

The description is a single paragraph of four sentences, no wasted words. It front-loads the key action (probe and score), lists default model, special key requirement, return structure, and use cases. Every sentence earns its place.

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

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

Given 100% schema coverage and no output schema, the description adequately explains all parameters, return structure, and use cases. It could elaborate on the scoring methodology, but the information provided is sufficient for selection and inference.

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

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

All four parameters are described with added context beyond the schema. The description explains that 'entity' is the topic to probe, 'models' lists supported values, '_apiKey' is optional but needed for anthropic, and 'context' disambiguates common names. This adds meaningful guidance.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility. It specifies the default model, return fields, and distinguishes among sibling tools by framing use cases like AI-marketing audits and competitive monitoring.

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

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

The description explicitly lists use cases (AI-marketing audits, brand checks, competitive monitoring) and mentions that the default model is free while Anthropic requires a key with BYO billing. However, it does not explicitly state when not to use this tool or directly compare to 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 (readOnlyHint, idempotentHint), the description reveals routing to 5,245 tools, argument filling, structured answer with citation URIs, and performance characteristics ('one fast call, works on every tier'). 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 verbose but well-structured with clear sections, front-loaded key message, and informative examples. Slightly longer than needed but efficient for the complexity.

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

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

Given the tool's broad scope and many siblings, the description covers behavior, alternatives, examples, and citation format. No output schema, but the description sufficiently explains return value (structured answer with citations).

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

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

Schema coverage is 100% with well-described aliases. The description adds examples of natural language questions but does not provide additional semantic detail beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool handles factual questions about various structured data sources (SEC filings, FDA, etc.), provides specific examples, and explicitly distinguishes from web search and sibling tools (ask_pipeworx_grounded, deep_research).

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

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

The description gives explicit guidance: 'PREFER OVER WEB SEARCH', specifies when to use ('what is', 'look up', etc.), and explains when to step up to alternatives (grounded or deep_research for multi-part questions). Also notes it's the default entry point.

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

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

Discloses that it is a full working router with no fallback, and that no candidate is active currently so it matches stable. Annotations already indicate read-only, idempotent, non-destructive; description adds context about experimental edge.

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

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

Description is informative and front-loaded with key purpose, then explains candidate logic and current state. A bit lengthy but every sentence adds value; could be slightly tighter.

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

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

Covers purpose, behavioral nuances, fallback, and usage context. No output schema, but references same response shape as stable version. Adequate for a router 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 is 100%, so the schema fully documents parameters. Description does not add extra parameter-level detail beyond stating 'same arguments', which is acceptable but not additive.

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

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

The description clearly states it's the beta version of ask_pipeworx, an identical universal router with candidate routing improvements, and distinguishes it from the stable sibling by mentioning active testing and current match.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. Implicitly suggests not using if stability is preferred, but lacks explicit when-not-to-use.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details the refusal mechanism, return format with evidence and refusal reasons, and the extra LLM call cost, offering rich behavioral context.

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

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

The description is efficient with two main sentences plus a structured return format bullet. It's well front-loaded but could be slightly more concise by removing 'Same routing as...' though it aids 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 (grounded answering, refusal types, extra cost) and high schema coverage, the description covers all necessary context including return format, making it complete.

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

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

Schema coverage is 100% and all parameters are aliases for 'question' with descriptions. The description adds no new parameter-level meaning beyond noting aliases, 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 the tool is a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from sibling ask_pipeworx by highlighting the grounded extraction behavior and extra LLM call cost.

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

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

Explicitly guides when to use: 'Use whenever an answer will be quoted, cited, or acted on...' and advises preferring ask_pipeworx for casual lookups, providing clear context for selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false, so the description does not need to repeat safety traits. The description adds minor context about response structure (e.g., response.total.applied is aggregate) but no significant behavioral disclosure beyond annotations.

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

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

Two sentences efficiently convey the purpose, grouping, row structure, and aggregate. Every sentence earns its place with no fluff.

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

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

The description covers the core data and row structure, but does not mention pagination defaults (e.g., page, limit from schema) or explain the year range behavior. However, with good annotations and 100% schema coverage, it is largely adequate for a 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 description coverage is 100%, but the description adds value by explaining that coo/coa use UNHCR 3-letter codes (referencing list_countries) and describing the row fields (procedure_type, app_type, dec_level, applied count) and aggregate, which are not detailed 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 'Asylum applications lodged, by year, country of origin (coo) and country of asylum (coa)', which specifies the verb (retrieve/query), the resource (asylum application counts), and the grouping dimensions. This contrasts with sibling 'asylum_decisions', making the tool's purpose distinct.

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

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

No explicit guidance is provided on when to use this tool versus alternatives like asylum_decisions. The only reference is 'see list_countries' for codes, which is about input format, not usage 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 readOnly, openWorld, idempotent, non-destructive. The description adds behavioral details: row fields (dec_recognized, etc.) and that response.total aggregates the same fields. 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?

Three sentences, front-loaded with purpose, each sentence adds necessary detail without waste. Examples in schema supplement but description itself is concise.

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

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

Given good annotations and full schema coverage, the description is complete for a data retrieval tool. It explains row fields and aggregation, though no output schema is present.

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

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

Schema covers 100% of parameters with descriptions. The description adds value by explaining that coo/coa take UNHCR 3-letter codes and referencing list_countries, providing context 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 it returns 'Decisions on asylum claims, by year, country of origin (coo) and country of asylum (coa)' and specifies the breakdown fields (dec_recognized, etc.). It differentiates from siblings like asylum_applications by focusing on decisions, though not explicitly contrasting.

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

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

No explicit when-to-use or when-not-to-use guidance. It implies usage for retrieving asylum decision data and references list_countries for codes, but lacks alternatives or exclusions.

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

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

The description provides extensive behavioral details: market resolution, classification, fan-out to data sources, evidence packet construction, safety checks (low-confidence short-circuit), closed market handling, wide-spread illiquidity flag, and cancellation rule parsing. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent and the description adds context beyond them.

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

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

The description is comprehensive but very long (over 1500 words). While the first sentence front-loads the purpose, the rest is a dense block of text. It could benefit from clearer structure (e.g., bullet points or sections) to improve readability. The extensive detail is valuable but not concise.

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

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

Given the tool's complexity (multiple classifiers, fan-out examples, response shapes, resolver contract, safety conditions), and the absence of an output schema, the description is remarkably complete. It covers all essential aspects, including edge cases like cancellation rules, news fallbacks, and parent event extraction.

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

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

Schema coverage is 100%. The description adds meaningful information for each parameter: market input examples (slug, URL, question text), depth enum with default behavior, and include_raw with effect on response size. This goes well beyond the schema definitions.

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

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

The description clearly states the tool researches Polymarket bets by pulling Pipeworx data, with specific inputs (slug, URL, question text) and output (evidence packet + comparison). It distinguishes from siblings by explaining the fan-out mechanism and comprehensive analysis, which is not present in other Polymarket tools like polymarket_edges.

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

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

The description explicitly states when to use the tool ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It also warns about low-confidence resolutions and closed markets, which implicitly advises against use in those cases. However, it does not explicitly mention alternatives or exclusion scenarios for other use cases.

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 behavior. The description adds that off-calendar fiscal years are handled correctly and results are sorted by primary metric, which is useful 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 verbose but well-structured: starts with natural language triggers, then explains behavior per type, then sorting and return. Each sentence adds value, though it could be slightly more concise.

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

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

No output schema, but the description mentions returning paired data and citation URIs. It covers data sources and sorting. Lacks specifics on time range or data recency, but overall sufficient for a comparison 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%. The description enriches both parameters: for 'type', it explains the data source per entity type (SEC EDGAR vs FAERS); for 'values', it clarifies format (tickers/CIKs vs drug names) and constraints (2-5 items).

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

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

The description explicitly states it performs side-by-side comparison of 2-5 companies or drugs, pulling specific financial or adverse-event data. It distinguishes from siblings by stating it replaces 8-15 sequential single-pack lookups, contrasting with tools like entity_profile.

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

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

Clear trigger phrases ('X vs Y', 'which is bigger') and a directive to prefer over sequential lookups. While it doesn't list alternatives for non-comparison cases, the context is well-defined.

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

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

Annotations already declare readOnlyHint, idempotentHint, true, and destructiveHint false. The description goes far beyond, detailing decomposition into facets, parallel execution, output format (evidence, confidence, source, fetched_at, citations, gaps, contradictions), semantics of depth levels (quick/standard/thorough), behavior for large records (semantic excerpting), and timing estimates (15-90s). No contradiction with annotations.

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

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

The description is long but well-structured, with critical information (account requirement, alternatives) front-loaded. Every sentence serves a purpose, covering usage, behavior, and expectations. While some redundancy exists (e.g., mentioning contradictions twice), the density of information justifies the length. Slight trimming could improve conciseness 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 (multi-source, multi-facet research with parallel execution, multiple depth levels, and rich output), the description is complete. It covers account prerequisites, alternative tools, behavioral details, output format (though no output schema), timing, and edge cases (breaking news, gaps). No gaps are left unaddressed.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning beyond schema: for 'depth', it explains the number of facets (3/5/8) and the gap-recovery and contradiction-scan behaviors for each level; for 'question', it clarifies that broad/multi-part questions are encouraged and decomposition is inherent. This is rich, actionable context.

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

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

The description clearly states the tool performs grounded multi-source research across 1369 structured data sources, decomposing questions into facets and routing to 5,245 tools in parallel. It explicitly distinguishes itself from sibling tool ask_pipeworx, which is for single lookups or breaking news. The verb 'research' and resource 'Pipeworx structured data sources' are specific and unambiguous.

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

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

Provides explicit guidance on when to use this tool vs. alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. Also notes account requirement and suggests ask_pipeworx for unsigned-in users. Includes prerequisites (free sign-in, paid plan for 'thorough') and context for second-hop iteration in 'standard' and 'thorough' depths.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds that it returns top-N relevant tools with full input schemas and curated examples, ready to call. No contradictions; behavioral details extend 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 (~100 words) and well-structured: first sentence states purpose, second lists domains, third explains return format, and final sentence gives usage hint. Every sentence contributes necessary information.

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

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

The description explains return format (tools with schemas and examples) and usage directive, but lacks information on error handling or no-results behavior. Given the tool's discovery nature and annotation support, completeness is adequate.

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

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

Schema description coverage is 100%, but the description adds value by explaining the query parameter accepts multiple aliases (task, q, description, search). This clarifies parameter flexibility beyond the schema's individual 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 explicitly states the tool finds tools by describing data or task, lists many domains, and distinguishes itself from sibling tools by instructing to call it first for browsing options.

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

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

The description provides clear usage context ('Use when you need to browse, search, look up, or discover what tools exist') and a specific directive to call it first. It lacks explicit when-not scenarios but is sufficient for the intended discovery role.

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

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

Discloses behavior beyond annotations: mentions soft-fail for patents, data sources, and specific output fields. No contradiction with readOnlyHint and destructiveHint=false.

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 dense but not overly verbose; each sentence adds value. Some internal bullet points would improve readability, but content is well-organized.

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

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

For a complex tool with no output schema, the description fully explains what is returned (filings, fundamentals, patents, news, LEI) and their details. Covers all aspects needed for correct usage.

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

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

Even with 100% schema coverage, description adds meaningful context: explains that type is limited to 'company' and value accepts ticker or CIK, and that names are not supported.

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

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

Description clearly states it provides a holistic profile of a US public company from multiple sources, with specific examples of user queries. It distinguishes from sibling tools that do single-source lookups.

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

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

Explicitly advises to prefer this tool over chaining individual lookups and provides guidance on needing resolve_entity for names. Clear when to use and when not.

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 destructiveHint=true. Description adds value by explaining why you'd use it (clear sensitive data) and that it pairs with other tools. No contradiction with annotations; idempotentHint is not elaborated but not contradicted.

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

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

Two sentences, no wasted words. Front-loaded with the core action. Efficient and to the point.

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 destructive tool with one parameter and no output schema, the description covers purpose, usage, and relationships. No gaps for the intended complexity.

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

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

Schema covers the single parameter 'key' with a description. The tool description does not add new information about the parameter beyond what the schema provides. Baseline 3 is appropriate given 100% schema coverage.

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

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

The description clearly states the verb ('Delete') and the resource ('previously stored memory by key'). It distinguishes from sibling tools 'remember' (store) and 'recall' (retrieve) by explicitly pairing with them.

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 specific scenarios for use: when context is stale, task done, or clearing sensitive data. Implicitly advises against use when memory is still needed. Mentions complementary tools to guide lifecycle.

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 the tool safe (readOnlyHint, idempotentHint, etc.). The description adds behavioral details: fetching the page, extracting title/description/key links, and emitting standard markdown. This goes beyond annotations to explain the exact process.

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

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

The description is concise (3 lines), well-structured, and front-loaded with the tool's primary action. Every sentence adds value, and there is no redundancy or fluff.

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

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

Given the tool's simplicity (2 parameters, no output schema), the description is fully complete. It explains input, output format, and use cases, covering all necessary context for an agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description does not add significant new semantics beyond the schema; it merely reiterates that max_links controls the number of link entries. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates an llms.txt file for any URL, with a specific verb ('generate') and resource ('llms.txt file'). It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on creating the standard file format.

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

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

The description lists concrete use cases (client's site indexing, personal project drafting, competitor auditing), providing clear guidance on when to use. However, it does not explicitly state when not to use or compare with alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds pagination details, field list, and that it is a large list. 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?

Single, well-organized paragraph that front-loads purpose, then usage, then item fields. Every sentence is informative 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?

With no output schema, description explains each item's fields and pagination behavior completely. Adequate for a 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 covers 100% of parameters with descriptions. Description adds context: 'raise limit or page through' and explains 1-based page and response.maxPages. Adds value beyond schema.

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

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

The description clearly states it is a reference list of countries/territories tracked by UNHCR, used to map names to codes for other tools. It distinguishes itself from sibling tools by specifying its role in providing codes for coo/coa parameters.

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

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

Explicitly tells when to use: to map country name to code for filtering in other tools. Mentions pagination behavior. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds default exclusion of inactive subscriptions and lists return fields, which is useful but not essential beyond annotations.

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

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

Two sentences with no wasted words. Front-loaded with the core purpose, then important details.

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

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

Given the tool's simplicity (one optional parameter, read-only, no output schema needed), the description fully covers what the agent needs: what it returns and when to use it.

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

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

Schema coverage is 100% with one optional boolean parameter. Description clarifies default behavior (active only) and purpose of parameter by mentioning 'active' subscriptions, adding value beyond schema.

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

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

Clearly states 'List the caller's active subscriptions' and enumerates return fields. Distinguishes from sibling tools subscribe/unsubscribe by describing its role in review.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel', giving concrete when-to-use 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?

Annotations are basic but the description adds critical behavioral details: rate-limited (5 per identifier per day), free, doesn't count against tool-call quota, and that the team reads digests daily with signal affecting roadmap.

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

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

Every sentence adds value. The description is front-loaded with the key purpose, and the remaining sentences provide precise guidance without fluff.

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

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

For a feedback submission tool, the description covers when to use, how to format messages, constraints (rate limits, quota), and context parameters. 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% so baseline is 3. The description adds value by elaborating on the message parameter (1-2 sentences, 2000 chars max) and clarifying the context object as optional.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb-resource pair and distinguishes it from sibling tools by its feedback and reporting 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 explicitly tells when to use the tool: for bugs, feature requests, data gaps, or praise. It also advises against pasting user prompts and mentions rate limits (5 per day) and that it's free.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value beyond these by noting the data source (CF analytics-engine), no PII, and caching behavior (5min-1h), providing useful behavioral context.

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

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

The description is concise (few sentences) and front-loaded with the main result. Every sentence adds utility, including the use cases and data details. 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 no output schema, the description still explains the return content (top tools, top packs, call volume, with (pack, tool, count) tuples). It mentions caching and data provenance, making it sufficiently complete for a simple read-only tool.

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

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

Schema coverage is 100% with one parameter (window) and enum. The description adds meaning by explaining that shorter windows surface hotness and longer show steady-state demand, providing semantic guidance beyond the enum.

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 returns top tools, top packs, and total call volume over a recent window. It uses specific verbs ('Returns') and resources, and distinguishes itself from sibling tools like ask_pipeworx or discover_tools by focusing on trending signals.

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?

Three explicit use cases are listed (discovering hot data sources, confirming canonical choice, checking alignment). It does not explicitly state when not to use, but the positive guidance is clear and distinguishes from alternatives.

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

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

Discloses extensive behavioral details beyond annotations: trending scan scope (top ~200 markets), mode-specific logic (date-axis ordering, partition check, Jaccard similarity threshold, placeholder filtering), fill check against live CLOB depth, and conditions for not trading. 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 comprehensive and well-organized, starting with overall purpose then detailing each mode. Every sentence adds value, though length is justified by tool complexity. Slight room for more structured formatting.

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 lack of output schema, description fully explains response structure (opportunities array with fields, partition_check object in event mode) and includes fill check safety guidance. Covers all aspects 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 description adds substantial meaning: distinguishes event (single-event mode) vs topic (cross-event mode), provides concrete examples of valid slugs and seed questions, explains recommended usage for event, and details each mode's processing.

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 finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. Distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by detailing unique mechanisms and explicitly referencing the fill check.

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

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

Provides explicit when-to-use guidance for three modes: no args for trending scan, event for a specific market (recommended), and topic for cross-event scanning. Includes examples of valid inputs and explains cross-event mode catches patterns single-event misses.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds rich behavioral details: caching at KV level keyed on all knobs, three model families with specific methodologies, response structure including diagnostics, and warnings for market moves exceeding edge. 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 thorough but verbose, spanning multiple paragraphs. It is well-structured with front-loaded purpose and clear sections for model families, response structure, and knobs. However, some details (e.g., exact gate relaxation parameters) could be trimmed or moved to parameter descriptions for brevity.

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

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

Given the complexity (9 parameters, three segments, no output schema), the description is remarkably complete. It explains the edge calculation, segment compositions, response fields (including diagnostics and Fed candidates), caching behavior, and even why certain bets are excluded. Everything an agent needs to understand and use the tool is present.

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

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

Schema covers all 9 parameters with descriptions (100% coverage). The description adds meaningful context beyond the schema, such as explaining the tradeable-edge filters (max_spread_pp, min_liquidity), the rationale for default slippage (20-50bp due to bid/ask), and how min_partition_leg_kelly works specifically for partition arbs.

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

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

The description clearly states the tool scans top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It is built for 'what should I bet on today' and distinguishes itself from siblings by focusing on data-driven edge discovery without needing to page through hundreds of markets.

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

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

The description provides clear context on when to use ('what should I bet on today'), but does not explicitly exclude alternatives or compare to sibling tools like polymarket_arbitrage or polymarket_edge_tracker. It implies the tool is for initial discovery rather than deep analysis.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds significant behavioral details: response structure (tracked, expired, snapshot_dates), computation of decay, and limitations (60-day TTL, daily closes). 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 verbose but well-structured with clear sections for arguments and response. Every sentence adds value. Slightly longer than necessary but 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 no output schema, the description thoroughly explains the response fields and caveats (history depth, decay calculation). It covers all necessary context for a tool with two optional parameters and no output schema.

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

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

Schema coverage is 100%, so schema already documents both parameters. The description adds marginal value by restating defaults and allowed values for 'window' (24hr, 1wk, 1mo) and 'days' (default 14, max 30). Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay over time, answering whether an edge is fresh or old. It uses specific verbs like 'tracks' and 'answers', and the explanation distinguishes it from sibling 'polymarket_edges' by focusing on time-series rather than a single snapshot.

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

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

The description provides clear context on when to use the tool (when needing historical edge trend), but does not explicitly state when not to use it or mention alternatives. However, the distinction from 'polymarket_edges' is implied, so it earns a 4 rather than 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 mark readOnlyHint, openWorldHint, idempotentHint true. The description adds significant behavioral context: walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage, etc.), explains basket vs single-market logic, warns about thin legs and forced directional risk. No contradictions.

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

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

Description is long but well-structured with clear sections for single-market and basket modes, uses bold for keywords. Every sentence provides unique value; slight redundancy in introducing modes could be trimmed, but overall it's appropriately dense 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 meticulously documents return values for both modes, including edge cases like thin_legs, max_clean_notional_usd, and forced_directional_risk. Covers sizing constraints (default, clamp 10–1,000,000) and the rationale for use. Fully enables correct agent invocation.

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

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

Schema coverage is 100%, but the description adds crucial meaning beyond schema: explains default side logic for baskets, clarifies size_usd interpretation (max spend vs target proceeds for single-market; settlement notional for basket), and emphasizes the mutual exclusivity of market and event parameters.

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

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

The description starts with a clear, specific verb-resource phrase ('Realizable-vs-theoretical edge check against live CLOB order-book depth') and immediately distinguishes two modes: single-market and basket. It differentiates from siblings like polymarket_arbitrage and polymarket_edges by explaining when to use this tool for execution feasibility 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 states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why (theoretical overround not capturable, partial basket fills create unhedged directional risk), providing clear context for when not to skip this check.

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

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

Annotations already declare read-only, idempotent, open-world. Description adds deep behavioral details: compatibility_warning conditions, temporal alignment, skipped cross-type counters. 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 lengthy but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds value, though minor trimming could enhance 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 no output schema, the description fully compensates by detailing response structure, safety fields, temporal alignment, and caveats. No gaps remain for agent understanding.

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 significant meaning: explains both modes, gives examples, and details the topic list. It clarifies parameter interactions and overrides.

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: calculating cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings (e.g., polymarket_arbitrage) by focusing on venue comparison.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers) and when to use each. Warns that most pre-mapped topics return compatibility warnings, guiding the agent to not assume tradeability.

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, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds valuable behavioral context: it explains the breakdown behavior of boolean parameters (coo_all/coa_all break totals down by dimension) and warns about code format differences (UNHCR vs. ISO3). No contradictions with annotations.

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

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

The description is a single, well-structured paragraph. It front-loads the main purpose, lists categories, then explains filtering and the important code note. Every sentence adds value with no repetition or fluff. Efficient and concise.

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

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

Given the complexity of the tool (8 parameters, no output schema), the description covers the key aspects: categories, filtering, breakdown behavior, and code format. It does not describe the return format (e.g., paginated table), which is a minor gap, but the annotations and examples partly compensate. Overall, it is quite complete for a read-only data retrieval tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the breakdown behavior of coo_all/coa_all ('breaks the totals DOWN by that dimension') and clarifying the code format for coo/coa. It also provides examples with parameters. This adds value beyond the schema definitions.

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

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

The description clearly states it retrieves data on forcibly displaced and stateless persons by year and country, with specific categories (refugees, asylum_seekers, etc.). The verb 'forcibly displaced & stateless persons by year and country' is specific, and it distinguishes itself from siblings like asylum_applications by focusing on population stocks rather than flows.

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 using UNHCR 3-letter codes (not ISO3) and recommends using list_countries first. It explains the filtering by coo/coa and the breakdown behavior of coo_all/coa_all. However, it does not explicitly state when to use this tool vs. sibling tools like asylum_applications or asylum_decisions, leaving the comparison implicit.

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 that data is scoped to the user's identifier and that omitting key lists all keys, both useful behavioral 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 three sentences, each adding value: function, usage context, and scope/pairing. It is 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 the simple 1-param read-only tool, the description covers retrieval, listing, scoping, and relationships to sibling tools, providing sufficient context for correct usage.

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

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

The schema already describes the key parameter and its behavior (omit to list all). The description restates this without adding new semantic details, so no extra value beyond schema.

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

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

The description clearly states the tool's function: retrieve a saved value by key, or list all keys when key is omitted. It provides specific examples like 'user's target ticker' and distinguishes from related tools remember and forget.

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

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

It explicitly advises using recall when needing to look up previously stored context without re-deriving it. It mentions pairing with remember and forget but does not directly contrast with sibling tools beyond that.

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 states that setting mark_read:true flags events as read, implying state modification, but annotations declare readOnlyHint=true, indicating the tool does not change state. This is a direct contradiction, so score is 1.

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 purpose, uses clear language, and every sentence adds useful information without redundancy. Six sentences efficiently cover functionality, alternatives, and parameters.

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

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

Despite no output schema, the description explains return fields and mark_read behavior. It covers filtering, limits, and provides an alternative access method. The tool is fairly complete for understanding usage.

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

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

Schema coverage is 100%, and the description adds value by providing examples (e.g., filter type 'sec_8k') and explanatory context for parameters like since and mark_read, beyond the schema's brief 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 pulls fired events from a subscription feed, specifying the return fields (source, citation_uri, payload) and filtering options. It distinguishes itself from sibling tools like 'ask_pipeworx' and 'subscribe' by focusing on retrieving existing alerts.

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 usage context: mentions polling works fine and gives an alternative API endpoint for scripts/dashboards. However, it does not explicitly compare to sibling tools or state when not to use this tool.

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

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

The description adds substantial behavioral context beyond annotations: multi-source fan-out, fallback logic (GDELT → GNews), API sunset status (USPTO soft-fail), and return format structure (changes grouped by source, total_changes count, pipeworx:// URIs). The annotations (readOnlyHint, idempotentHint) are consistent and reinforced by the description.

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

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

The description is front-loaded with query examples and structured into sources, parameters, and sibling comparison. It is slightly verbose but every sentence adds value; no redundancy. The length is justified by the tool's complexity.

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

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

Despite the tool's complexity (multiple sources, fallback, sunset, no output schema), the description covers all critical aspects: input parameter semantics, output structure, source behavior, and alternative tool. It provides complete guidance for an AI agent to understand and invoke the tool correctly.

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

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

All three parameters have descriptions in the schema (100% coverage). The description adds practical usage details: 'since' accepts ISO date or relative shorthand with examples, recommends '30d' or '1m', and clarifies that 'value' can be a ticker or zero-padded CIK. This goes slightly beyond schema but not dramatically.

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 begins with specific query patterns ('What's new with X', 'latest on Y'), then clearly states the tool returns a change feed for a company in a recent window, fanning out to SEC EDGAR, GDELT/GNews, and USPTO. It distinctly differentiates from sibling entity_profile by stating when to use that instead, achieving high specificity and resource identification.

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 when to use the tool (for 'What's new' queries with a time window) and when not to (use entity_profile for static profile regardless of window). It also provides fallback behavior for news sources, giving clear context for selection among sibling tools.

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

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

Adds key behavioral context beyond annotations: scoping by identifier, persistence differences between authenticated (permanent) and anonymous (24-hour) sessions. Annotations declare idempotentHint=true, which aligns with the description's implication that overwriting the same key replaces value. 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?

Extremely concise: 4 sentences covering purpose, usage context, behavioral details, and companion tools. No filler, every sentence adds value. Front-loaded with the primary 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?

For a simple write tool with no output schema and only two required parameters, the description covers all necessary context: data type, scope, persistence, and integration with related tools. Complete and self-contained.

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

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

Schema coverage is 100%, so the description provides limited added parameter meaning beyond schemas. It gives examples of possible values for the 'value' parameter (findings, addresses, etc.), which is helpful but not substantial. Baseline of 3 is appropriate.

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

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

Description clearly states the tool saves data for later reuse, specifying key-value pairs and scoping. It distinguishes from siblings 'recall' and 'forget' by directly mentioning them as companions. The verb 'save' and resource 'data' are specific and actionable.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward' with concrete examples (ticker, address, preference). Mentions pairing with recall and forget. Lacks explicit when-not-to-use or comparison to alternative tools beyond these siblings, but sufficient for practical 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 mark it as read-only, idempotent, and non-destructive. The description adds that it cascades through several endpoints internally and details the output for each type (company: ticker+CIK+name+URI; drug: RxCUI+ingredient+brand+URI), providing transparency 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 informative but slightly verbose. It is front-loaded with examples, then states purpose and details. Every sentence adds value, but could be trimmed slightly without loss.

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

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

Despite no output schema, the description fully explains the return format for both entity types, including citation URIs. It also covers inputs thoroughly. For a lookup tool, this is complete and actionable.

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

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

Schema coverage is 100% with descriptions, but the description adds significant value: explains 'type' enum values (company/drug), gives example inputs for 'value' (ticker, CIK, name for company; brand/generic for drug), and notes auto-disambiguation for company. This exceeds 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 resolves names to official identifiers, with examples like ticker, CIK, RxCUI. It distinguishes from siblings by advising 'use FIRST whenever you have a name but need an ID.'

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

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

Explicitly says to use when you have a name but need an ID, and that it replaces 2-3 manual lookups. However, it does not mention alternatives or when not to use it, though the sibling list is present for 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 declare readOnly, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity. No contradiction.

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

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

Two sentences, no wasted words, front-loaded purpose. 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?

No output schema, but description specifies return: ranked list with score, confidence, signal density per entity. Parameters fully covered by schema (100%). Sufficient for selection and invocation.

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

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

Schema coverage is 100%, baseline 3. Description adds context for 'entities' (first entry treated as subject) and 'context' (disambiguates common names), but does not significantly augment the schema for models or _apiKey.

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

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

Description uses specific verb 'compare' and resource 'AI visibility across multiple entities', with clear outcome: 'ranks by score, surfaces which is most/least recognized'. Distinct from sibling ai_visibility_check which is single-entity.

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

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

Explicitly states use case 'competitive AI-marketing audits' and gives example question. Could be improved by stating when not to use (e.g., single entity), 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 cover safety and idempotency. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia timing (5-30s), and the sources_failed field. This goes beyond the annotations, though it could explicitly mention that the tool is safe to call repeatedly.

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 a front-loaded purpose, though it is somewhat lengthy. Every sentence adds value, but some could be tightened slightly (e.g., the list of fields could be abbreviated).

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

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

Given no output schema, the description comprehensively details return values (summary fields, per-advisory detail, links, alternative versions) and error behavior (sources_failed). It covers all essential aspects for agent decision-making.

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 nuance: scoped packages are accepted, and version defaults to latest published. This provides clarity beyond the schema alone.

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

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

The description clearly states the tool's purpose: a composite check for npm packages covering license, advisories, bundle size, and tree-shake support. It uses a specific verb ('scan') and distinguishes from siblings by noting the NPM-only scope in v1.

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

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

Explicitly provides usage scenarios ('is X safe / popular / small', 'what does adding lodash cost me'). Also specifies when not to use (non-npm packages should use deps.dev:version directly), giving clear guidance on alternatives.

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

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

The description reveals key behavioral traits beyond annotations: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, input cap of 200K chars with truncation warning, and output includes character offsets. This adds substantial value beyond readOnlyHint and idempotentHint 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 well-structured paragraph that front-loads purpose, then provides usage guidance, and ends with technical details. Every sentence adds value without redundancy.

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

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

For a tool with no output schema, the description still mentions output contains passages with character offsets and similarity scores. While a full return structure isn't specified, it gives sufficient info for an agent to use the outputs. Input parameters and behavior are fully covered.

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

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

With 100% schema description coverage, the baseline is 3. However, the description adds meaningful context: explains query as 'natural-language query' with examples, specifies default/range for limit, and clarifies text max size. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool performs 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from sibling tools like ask_pipeworx_grounded by explaining the difference in usage patterns, making it easy for an agent to select appropriately.

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

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

Explicitly advises to use when a record is too big for the prompt, explains how it saves context, and directly pairs with ask_pipeworx_grounded for a clear workflow. This provides strong guidance on when and how to use the tool vs 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 idempotentHint=true and destructiveHint=false, and the description adds context: subscription creation is not a read operation, it is idempotent, and it requires authentication. It also discloses that webhooks return a secret once and auto-disable after failures. 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 thorough yet well-structured: it opens with the core action and return value, then covers requirements, types, and delivery options. It is slightly long but every sentence adds value, and the most critical information (purpose) is 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?

Given the tool's complexity (multiple subscription types, nested parameters, multiple delivery channels, authentication requirements, and rate limits), the description covers all essential aspects: what it does, prerequisites, type-specific details, delivery configuration, and behavioral notes (webhook signing, auto-disable). No output schema exists, but the return value is stated. The description is complete for an AI 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 coverage is 100% with decent descriptions, but the tool description goes much further: it provides concrete examples for each subscription type (e.g., sec_8k with items, polymarket_edge with topics), format specifications for delivery (SMS, email, webhook with HMAC details), and additional constraints (phone verification, rate limits). This adds significant 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 creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes from sibling tools like list_subscriptions, recent_alerts, and unsubscribe by specifying its role as creation.

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

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

The description explicitly mentions the requirement of a Pipeworx OAuth account and that anonymous/BYO cannot persist subscriptions. It also details delivery channels with their constraints (SMS verification, 10/day cap). While it doesn't explicitly contrast with sibling tools like recent_alerts for pulling, the context is strong enough for informed 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 indicate read-only, idempotent, non-destructive. Description adds that the response includes category-bucketed questions and exact tool+argument shapes, providing useful behavioral context beyond annotations. No contradictions.

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

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

Description is clear and well-structured with examples, though moderately lengthy. Every sentence adds value, but 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 simple tool with one optional parameter, no output schema, and robust annotations, the description fully explains the response format, usage scenarios, and integration with other tools.

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

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

Schema coverage is 100% with one optional string parameter. Description elaborates on possible topic values and effect of omission, adding practical context beyond the schema description.

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

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

The description clearly states the tool's purpose as the onboarding entry point, returning categorized example questions with tool argument shapes. It distinguishes itself from siblings like discover_tools by positioning itself as the first call for new users.

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

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

Explicitly says to call with no arguments for full spread or pass a topic to focus, and to use this tool first when unsure of Pipeworx capabilities. Provides clear guidance on when and how to use.

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

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

Discloses that the row is deactivated (not deleted) and historical events remain available via recent_alerts, adding significant 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?

Three concise sentences, each providing essential information with no redundancy or fluff.

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

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

Given 1 parameter, no output schema, and annotations, the description covers purpose, usage, behavior, and parameter semantics completely.

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

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

Schema has 100% coverage for the single 'id' parameter. Description adds context about ownership enforcement, which is parameter-related and valuable 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools 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 ('you can only cancel your own subscriptions'), providing clear usage context. Lacks explicit alternatives, but the ownership constraint is a strong guideline.

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

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

Annotations indicate readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds detail about returning a verdict (with five options), actual value with citations, and the two internal pathways (exact percent-delta math for SEC, grounded pipeline for others). 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 dense paragraph with all key information front-loaded (example queries, use case). However, it could be more structured with bullet points for readability. Still, every sentence adds value.

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

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

Given the tool's complexity (2 params, no output schema), the description fully explains the return values (verdict, value, reasoning), the two processing pathways, constraints on tolerance, and efficiency gains. The agent has sufficient information to use 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% with descriptions for both 'claim' and 'tolerance_pct'. The description adds context: tolerance overrides the default implied by wording, capped at 5%, and suggests using 1-2 for hallucination detection. Examples for 'claim' are given.

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

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

The description clearly states the tool performs natural-language claim verification against authoritative sources, with example queries and two distinct pipelines (SEC EDGAR for financial claims, grounded pipeline for others). It distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on fact-checking specific claims.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains the two sub-cases (financial vs other claims). It also notes efficiency benefits replacing multiple calls. However, it 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.