Uk Gazette

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds behavioral details: default free model, BYO key for Anthropic (with cost implications), and return structure (score, confidence, signals, raw_response). 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 concise at 4 sentences, front-loading the core action and key details. Every sentence adds value: purpose, default vs. paid option, return format, and use cases. No redundancy.

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

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

With 4 parameters, no output schema, and no nested objects, the description fully explains input requirements, optional parameters, and output structure (per-model + combined view). It provides sufficient information for correct invocation and interpretation of results.

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

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

Schema coverage is 100%. Description adds helpful context beyond schema: e.g., 'Passed straight through to api.anthropic.com' for _apiKey, and 'Helps disambiguate common names' for context. It effectively enriches parameter understanding.

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

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

The description clearly states the tool's purpose: probing LLMs for knowledge about a business/brand/product/topic and scoring visibility (0-100). It uses specific verbs ('probe', 'score') and distinguishes from siblings like entity_profile and scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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 usage context: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains default model and optional Anthropic key. However, it doesn't explicitly state when not to use or compare to alternatives like scan_competitor_ai_presence, leaving some ambiguity.

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

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

Adds context beyond annotations: returns structured answer with citation URIs, routes to thousands of tools, fast, works on all tiers. No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Description is verbose with many examples and guidance, which may be redundant for an AI agent. Front-loads key preference but could be more concise.

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

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

Thoroughly covers purpose, behavior, usage guidelines, and parameter semantics for a complex meta-routing tool without output schema. Complete 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% (all parameters described). Description provides examples and clarifies the question parameter with aliases, adding value beyond schema.

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

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

The description clearly states the tool as a meta-routing tool for factual queries, specifying the verb 'ask' and resource 'Pipeworx'. It distinguishes from siblings by naming alternatives like ask_pipeworx_grounded and 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?

Explicit guidance to prefer over web search, start here, and step up only when needed with specific alternatives. Provides numerous examples and signals for when to use.

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

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

Discloses source-preference ranking behavior and confirms it's a full working router. Annotations indicate safe, idempotent read operation, and description adds behavioral context beyond that.

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 detailed but not excessive; key points like routing improvements and usage are front-loaded. 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 no output schema, the description adequately explains tool behavior, routing improvements, and usage context. It is complete for an experimental router 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 all parameters described as aliases for question. Description doesn't add new parameter info, but schema already provides sufficient meaning.

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

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

The description clearly states it's a beta version of ask_pipeworx with identical scope but improved routing. It distinguishes from the stable version by mentioning 'source-preference ranking' behavior.

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

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

Specifies to use it 'exactly like ask_pipeworx when you want the newest routing' and mentions comparison against stable router. Implicitly suggests it's for experimental use but doesn't explicitly state when not to use.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description discloses the internal process (tool routing, data fetching, extraction), the exact return format including refusal reasons, and the cost of an extra LLM call.

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

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

The description is somewhat long but well-structured, front-loading the critical property and then explaining mechanism, return format, usage, and trade-offs in a logical order with no wasted sentences.

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

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

Given the tool's complexity (tool selection from 5000+ sources, structured return with refusal modes), the description covers all essential aspects: behavior, return format, use cases, and cost. The lack of an output schema is compensated by a detailed return field list.

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

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

The input schema has 100% description coverage for all parameters, so the description adds little beyond noting that the question is in natural language. The baseline of 3 is appropriate as the schema already documents parameter semantics adequately.

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's purpose as a 'hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling 'ask_pipeworx' by noting the extra LLM call and the use of exact extraction from tool results.

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 when-to-use guidance for scenarios where answers must be quoted, cited, or acted upon without fabrication, and explicitly recommends preferring 'ask_pipeworx' for casual lookups, making alternative selection easy.

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?

Extensive detail beyond annotations: fan-out behavior, response shapes, resolver contracts, parent event extraction, news fallback, safety mechanisms, resolution-rule risk. No contradiction with readOnlyHint, openWorldHint, idempotentHint.

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?

Long but dense with essential information. Front-loaded with purpose and usage, then detailed breakdowns. Every sentence adds value, though a bit verbose; better structure could improve scanability.

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?

Remarkably comprehensive for a complex tool with no output schema. Covers fan-out logic, response fields, safety edge cases, resolution rules, parent events, and error handling. Leaves minimal gaps.

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

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

Schema covers 100% of parameters with descriptions. The tool description adds behavioral context (e.g., depth meaning, include_raw response size impact) that supplements the schema well.

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

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

The description clearly states it researches a Polymarket bet by pulling Pipeworx data, and lists input types. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edges, though the purpose is distinct enough.

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

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

Provides explicit use cases ('should I bet on X', 'what does the data say about Y') and examples. Lacks explicit when-not-to-use or alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true, and destructiveHint false. The description adds valuable behavioral context: off-calendar fiscal years are handled correctly, results sorted by primary metric, and returns paired data with pipeworx:// citation URIs. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with user-facing triggers. Every sentence earns its place: triggers, operation, data sources, sorting, return format. No redundancy or filler.

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

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

Given only two parameters, comprehensive annotations, and no output schema, the description covers all needed context: entity types, data per type, ordering, return format, and citations. It fully enables correct and efficient tool use.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond schema: explains enum values (company/drug) with concrete examples, specifies that company tickers can be CIKs, and notes that drug names are common names. Also adds context about off-calendar fiscal year handling.

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

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

The description starts with multiple natural language triggers ("Compare X and Y", "X vs Y", etc.) and clearly states it performs side-by-side comparison of 2–5 companies or drugs. It specifies what data is pulled for each type, distinguishing this tool clearly from siblings 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?

The description explicitly states "ALWAYS PREFER over sequential single-pack lookups when comparing entities," providing a strong usage directive. It also differentiates when to use type='company' vs type='drug' and explains the data sources, leaving no ambiguity about appropriate use.

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

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

Annotations already declare read-only and idempotent, but description adds extensive behavioral context: not open-web, parallel decomposition, return format (findings with evidence, confidence, gaps), depth levels, hop field, contradictions, latency. No contradictions with annotations.

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

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

The description is comprehensive but somewhat verbose and nested; however, it front-loads the critical account requirement. Each sentence adds value, but could be more structured for quicker scanning.

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

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

Given the tool's complexity and lack of output schema, the description covers all necessary aspects: purpose, behavior, parameters, return format, alternatives, latency, and limitations. Nothing major is missing for an agent 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%, yet description adds significant meaning: explains depth enum values in detail (quick=3 facets, standard=5+gap recovery, thorough=8+iterative) and clarifies question parameter as broad/multi-part natural language.

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

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

The description clearly states it performs grounded multi-source research across Pipeworx's structured data sources, distinguishing it from siblings like ask_pipeworx. The verb 'research' and resource 'structured data sources' are specific.

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

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

Explicitly says when to use (broad/multi-part over structured data), when not to (single lookup or breaking news), and provides fallback alternatives (ask_pipeworx). Also mentions account requirements for different tiers.

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

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

Description adds value beyond annotations: explains it returns top-N relevant tools with names, descriptions, and full input schemas (with examples), and that results are ready to call directly. No contradiction with readOnlyHint, etc.

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

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

Description is well-structured: starts with purpose, then usage context, then return value, then when to call. Slightly long but each sentence is earned; no redundancy.

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

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

Despite no output schema, description sufficiently explains return format (names, descriptions, schemas, examples, ready to call). Also mentions default limit (20, max 50) which is in schema. Covers essential context for a discovery tool.

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

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

Schema description coverage is 100% with detailed property descriptions. Description adds context about aliases and natural language use, but this is already partially covered in schema. Baseline 3, marginal added value.

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 'Find tools by describing the data or task' and specifies domains. Explicitly differentiates from sibling tools by stating 'Call this FIRST when you have many tools available and want to see the option set'.

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

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

Description provides explicit context for when to use (browse, search, look up, discover tools) and when to call first. Does not give negative guidance but positive context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. Description adds behavioral details: fans out across multiple sources, returns specific fields, patents may soft-fail due to USPTO sunset, news uses GDELT→GNews fallback. 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 relatively long but front-loaded with example queries. Every sentence adds value, though could benefit from slight structural partitioning (e.g., bullet list of return fields). Still concise given complexity.

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

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

No output schema, but description thoroughly explains all return components (cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents with sunset note, news, LEI). Lists limitations and data source details.

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

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

Schema coverage is 100% (both parameters described). Description adds meaning beyond schema: clarifies that type only supports 'company' today, value accepts ticker or zero-padded CIK, explicitly states names not supported. Provides examples.

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

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

Description uses specific verb-resource pairs (e.g., 'Tell me about X', 'research Acme') and lists concrete data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It clearly distinguishes from sibling tools like resolve_entity by noting name support limitations.

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 prefer this tool ('ALWAYS PREFER over chaining...') and when not to use it ('Names not supported — use resolve_entity first'). Also provides alternative approach for names.

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 context about clearing sensitive data and mentions pairing with remember/recall, which adds behavioral insight 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 concise sentences, front-loaded with purpose. Each sentence earns its place, no filler.

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

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

For a simple single-parameter tool with no output schema, the description fully covers purpose, usage scenarios, and links to sibling tools. No gaps remain.

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

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

Schema already describes the 'key' parameter with 100% coverage. The description does not add new details about parameter format or constraints, 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 verb 'delete' and resource 'previously stored memory by key'. It distinguishes from siblings by mentioning 'Pair with remember and recall', providing specificity.

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 lists three use cases: when context is stale, task is done, or to clear sensitive data. Also advises pairing with related tools, giving clear context for when 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?

Annotations already indicate safe, read-only, idempotent operations. The description adds value by explaining the legal background (Trustee Act s.27) and the purpose of the notices, which goes beyond what annotations provide. 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 concise: two sentences plus a code example, all front-loaded with purpose. Every sentence adds value, and the example is directly helpful.

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

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

Given 9 parameters fully described in schema, no output schema, and annotations present, the description provides sufficient context via use cases, legal background, and an example. It effectively complements the structured fields.

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 an example usage and clarifies the 'claim_expires_after' parameter as useful for finding estates still open to claims, providing extra meaning beyond the schema.

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

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

The description clearly states it searches UK deceased-estates notices in The Gazette under the Trustee Act 1925, specifying the resource and context. It distinguishes from sibling tools like gazette_insolvency_notices by focusing on deceased estates.

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

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

The description provides explicit use cases (probate research, tracing estates, checking death notices, finding claim deadlines) and lists filters. It does not mention when not to use or alternatives, but the context is clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds beyond annotations by listing specific return fields (notice type, publication date, companies, people, addresses, legislation, dates) and explaining input sources (search tools or URLs). No contradictions with annotations.

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

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

Two sentences plus an example, front-loading the purpose and listing return fields. No unnecessary words; 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?

The description is fully complete for this simple tool: covers input, output, and usage context. No missing aspects given the lack of an output schema and the low complexity.

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

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

Schema coverage is 100% with a short description. The tool description adds significant value: it explains the two formats for notice_id (numeric or alphanumeric with examples), shows the parameter in an example call, and details the return fields, compensating for the lack of an output schema.

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

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

The description clearly states the verb (Get), resource (structured record for one Gazette notice), and scope (by ID). It distinguishes itself from siblings like gazette_search_notices by specifying that it retrieves a single notice by 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?

The description indicates when to use the tool: after a gazette search or when a notice ID is available. It provides an example call. While it doesn't explicitly state when not to use it, the context is clear and no alternative is needed given the narrow purpose.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds that results come from The Gazette and are indexed by company name or number, with no contradictions.

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

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

Three focused sentences plus an example. Front-loaded with purpose, 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?

Covered search scope, indexed fields, and example. Lacks description of return format, but for a search tool this 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?

100% schema coverage means schema already describes parameters. The description adds that 'company' accepts name or number, and 'scope' narrows to corporate/personal, plus an example.

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

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

The description explicitly states it searches official UK insolvency notices in The Gazette, listing specific notice types. It clearly differentiates from sibling tools like gazette_deceased_estates and gazette_search_notices.

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 identifies it as the go-to source for checking company liquidation/administration, monitoring distress, or tracking bankruptcies. It implies usage context but does not explicitly exclude alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no contradictions and provides behavioral context (browsing taxonomy, no side effects). It enriches understanding by listing category domains (companies, people, etc.) beyond what annotations cover.

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

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

The description is extremely concise: two sentences and an example. It front-loads the primary purpose, then adds context and an illustrative example. Every sentence is informative without waste.

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

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

For a simple lookup tool with no output schema, the description reasonably conveys what the tool returns (taxonomy codes) and how to filter. It could specify the output format (e.g., list of code/name pairs), but the example and category listing partially compensate. Annotations cover behavioral aspects well.

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

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

Schema coverage is 100% for the single optional parameter 'search'. The description adds the same information ('optionally filter by a search word') plus an example. While it gives context about category content, it does not significantly enhance understanding of the parameter itself 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: to browse The Gazette's notice-category taxonomy. It specifies that these are the category codes accepted by gazette_search_notices, distinguishing it from sibling search tools. Examples of categories (e.g., insolvency, roads) further clarify scope.

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

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

The description implies usage context by noting the categories are for gazette_search_notices. It does not explicitly state when not to use this tool, but the sibling list (e.g., gazette_search_notices) provides implicit differentiation. A clear use case is given: filtering by a search word.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds full-text search, filtering, date range, editions, location search. Adds value beyond annotations.

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

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

Single paragraph with clear structure: purpose, scope, filters, example. Every sentence adds value. No unnecessary words.

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

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

With 11 parameters all described in schema and description covering use cases, filters, and example, the description is complete for the tool's search purpose. No output schema makes the description 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 coverage is 100%, so baseline 3. Description enriches parameters by giving examples (e.g., category 'corporate insolvency') and clarifying usage (e.g., location needs distance_miles).

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 searches The Gazette (UK official public record), enumerates notice categories, and provides use cases, distinguishing it from sibling tools like gazette_deceased_estates.

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 suggests when to use (e.g., 'official UK notices about X', 'gazette notices for company Y') and gives an example. Does not explicitly state when not to use, but context from siblings implies 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?

Description discloses fetching the page, extracting title/description/key links, and emitting standard markdown. Annotations (readOnlyHint, idempotentHint) are consistent, and no contradictions exist.

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

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

Four sentences covering action, format, and use cases. Efficient but two sentences could be tighter; still well-structured and 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 no output schema and only two parameters, the description provides adequate behavioral and usage context. Minor gaps in error handling or performance details, but overall complete for the tool's simplicity.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description adds no new parameter information beyond the schema, earning the baseline score.

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

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

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

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 use cases: getting a client's site indexed, drafting llms.txt, auditing competitor visibility. This gives clear guidance on when to use this tool versus 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 provide readOnlyHint:true, idempotentHint:true, and destructiveHint:false. The description adds value by detailing the return fields and mentioning the optional include_inactive parameter. It does not contradict annotations.

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

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

Two concise sentences: the first states purpose and return fields, the second gives usage guidance. No superfluous information.

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

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

For a simple list tool with no output schema, the description covers return fields, parameter behavior, and usage context. It is complete enough for the tool's complexity, though pagination or ordering is not mentioned.

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

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

Schema coverage is 100% with a single boolean parameter described. The description adds minimal value beyond the schema, only implying that active subscriptions are listed by default.

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 'list' and the resource 'the caller's active subscriptions', specifying the returned fields. It implicitly distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit context for when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It does not explicitly state when not to use it, but the guidance is clear.

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

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

The description discloses rate-limiting ('Rate-limited to 5 per identifier per day'), that it is free and doesn't count against quota, and that feedback signals directly affect the roadmap. These details add behavioral context beyond the annotations, which only indicate it's not read-only, not idempotent, etc.

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

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

The description is concise (4-5 sentences) and front-loaded with the core purpose. Every sentence earns its place, providing usage guidance, behavioral details, and constraints without redundancy.

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

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

Given the tool's simplicity (3 parameters, no output schema), the description is complete. It covers the purpose, when to use, how to use, limitations, and what happens with the feedback. No additional information 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 description coverage is 100%, so the schema already documents parameters well. The description adds value by clarifying how to construct the message (e.g., 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'), which goes beyond the schema's 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's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific use cases (bug, feature, data_gap, praise) and distinguishes itself from sibling tools, which are mostly retrieval or analysis tools.

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

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

The description provides explicit guidance on when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises not to paste the end-user's prompt, which helps the agent use the tool correctly.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive. The description adds that data comes from CF analytics-engine, is aggregated with no PII, and cached 5min-1h, providing valuable context beyond annotations.

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

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

Four sentences, each essential. First sentence states purpose, second lists returns, third enumerates use cases, fourth explains data source and caching. Front-loaded, no redundancy.

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

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

For a simple tool with one parameter and no output schema, the description fully covers returns, use cases, data source, and caching. No gaps in context 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% and includes descriptions. The description adds nuance about short vs. long windows, helping agents choose the right parameter. Baseline 3, plus extra guidance justifies 4.

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

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

The description clearly states the tool returns trending tools, packs, and call volume, with specific use cases. It distinguishes itself from siblings by focusing on aggregate trending data.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tools, and aligning use cases. Also provides guidance on window selection and mentions caching behavior.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description adds extensive behavioral details: internal checks (monotonicity, partition_sum, Jaccard similarity, placeholders filter, fill check), response structure, and a warning that realizable edge ≤ 0 means the opportunity is not tradable. 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 lengthy (multiple paragraphs) but each sentence adds value, covering distinct aspects. It could be shortened slightly, but the complexity of the tool justifies the detail. The structure is logical: purpose, modes, internal checks, output description, fill check. No redundancy.

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

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

The description covers all major aspects: modes, internal algorithms, response format, and edge cases (placeholder filter, fill check). There is no output schema, but the description details the expected response fields. Minor omissions include error handling or rate limits, but these are not critical given the annotations. Overall, very thorough.

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

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

Both parameters have schema descriptions, but the tool description vastly enriches them. It explains the purpose of 'event' (single-event mode with examples), 'topic' (cross-event mode with seed questions), and how each triggers different internal logic. It also clarifies accepted formats (slugs or full URLs). This goes well beyond the schema alone.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges and polymarket_edge_tracker by focusing on arbitrage detection. It also details three modes (no args, event, topic), making the purpose very specific and actionable.

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

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

The description explicitly tells when to use each mode: call with no args for a trending scan of top ~200 markets, pass an event slug for per-event partition checks, or pass a topic for cross-event scanning. It also recommends using polymarket_fill_risk for custom sizing, guiding the agent away from this tool when appropriate. This provides clear context for selection among siblings.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds extensive behavioral details: three model families, response structure, caching, 24h-move warning, Fed bet exclusion - far exceeding what annotations provide.

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

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

Very dense and informative but lengthy. Front-loaded with purpose, yet many specifics could be summarized. Still, every sentence adds value given the complexity of the 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?

No output schema but description thoroughly details response structure (by_segment, diagnostics, Fed caveat) and caching. Fully compensates for lack of output schema, making it self-contained for agent 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 covers all 9 parameters with descriptions. Description adds nuanced context for slippage_pp and min_partition_leg_kelly (explaining why min_kelly doesn't apply to partition arbs). Very good coverage; marginal extra value.

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 verb 'scan' and resource 'Polymarket markets', and specifies the unique value of identifying where Pipeworx data disagrees with market price. Differentiates from siblings like polymarket_arbitrage by focusing on edge opportunities from Pipeworx.

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

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

Explicitly states the tool is for 'what should I bet on today' and 'agents discover opportunities without paging hundreds of markets'. Provides guidance on knobs but lacks explicit alternatives or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral details: response structure (tracked, expired, snapshot_dates), trend classifications, decay calculation method, and data freshness limits. 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 moderately long but well-structured. It front-loads the core purpose and answer, then covers parameters and response format. Each sentence adds value; no redundancy. Could be slightly more concise, but appropriate 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 no output schema, the description thoroughly explains the response structure (tracked, expired, snapshot_dates) with field details. It also covers limits (60-day TTL, snapshot start date, decay from daily closes). This is complete for a data retrieval tool with high complexity.

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

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

Schema coverage is 100% with days and window described. The description adds meaning beyond schema: explains defaults, clamping, and window family options. Also contextualizes the snapshot cache-miss behavior and data gaps, which helps the agent interpret results.

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 telemetry built from daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from the sibling polymarket_edges by focusing on historical trends rather than raw 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?

Provides clear context on when to use this tool (to understand edge persistence vs. raw data). Implies that polymarket_edges is the alternative for raw edge data, though not explicitly stated. No exclusions or prerequisites are given, but the use case 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?

Discloses detailed behavioral traits: walks the order book ladder, returns specific fields like top_of_book, vwap_fill_price, slippage_pp, and verdict, and warns about thin legs and forced directional risk. Annotations already indicate read-only and idempotent, but the description adds rich 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 a single dense paragraph but front-loads the core purpose and uses bold for key terms. Every sentence adds value, though it could be slightly more structured with headings for readability.

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

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

Given no output schema, the description thoroughly enumerates all return fields for both modes, explains danger scenarios, and covers parameter behavior. Complete and self-contained 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% with decent descriptions, but the description adds significant meaning: explains mode-dependent defaults (side default auto for basket, size_usd interpreted as shares per leg in basket), and clarifies mutual exclusivity of market and event. Lifts baseline from 3 to 4.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by advising use before acting on their 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?

Provides explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains the consequences of not using it (partial fills causing directional risk).

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

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

Discloses internal logic: leg-by-leg prices, spread calculation (Kalshi - Polymarket), safety fields like compatibility_warning, temporal alignment, and skipped cross-type counters. Annotations already indicate read-only and idempotent, and the description adds rich context without contradiction.

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

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

The description is lengthy but well-structured with bold headers (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds necessary detail. Slightly verbose but justified given the complexity of the 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 the tool's complexity (multi-venue, multiple modes, safety warnings) and absence of output schema, the description is remarkably complete. It explains response structure, warning conditions, and temporal alignment, leaving no major gaps.

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

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

Input schema covers all 3 parameters with descriptions. The description adds significant value beyond schema by listing valid topic values, explaining override semantics, and providing examples. Baseline 3 from 100% coverage, plus extra credit for the detailed topic list and usage notes.

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

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

The description states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparisons. Two modes (topic shortcuts and explicit pairs) are clearly delineated.

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 when to use each mode, provides a list of pre-mapped topics, and warns that real spreads are rare and most shortcuts return a compatibility_warning. Also explains conditions that make spreads meaningless (temporal misalignment, non-equivalent bet shapes), guiding the agent to avoid misuse.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context about scoping (anonymous IP, BYO key hash, or account ID) and pairing with related tools, enhancing transparency beyond what annotations provide.

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

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

The description is three sentences, no filler, front-loaded with the main action. Every sentence adds value, and the structure is clear 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 tool's simplicity (one optional parameter, no output schema), the description fully explains behavior, usage, and scope. It is complete for an agent to select 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?

With 100% schema coverage, the baseline is 3. The description adds meaning by clarifying that omitting the key lists all keys, which is not fully captured in the schema's description. This addition justifies a score of 4.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys if omitted. It uses a specific verb ('Retrieve') and resource ('value previously saved via remember'), and distinguishes from siblings like '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?

The description explains when to use it (look up stored context without re-deriving) and mentions pairing with 'remember' and 'forget', providing clear context. It does not explicitly state when not to use it, but the usage scenario 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?

The description states that setting 'mark_read:true' flags events as read, which is a state-mutating side effect. This contradicts the annotation 'readOnlyHint=true', which implies no side effects. The contradiction is clear and must be flagged.

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 four sentences, front-loaded with the main purpose. Every sentence adds useful information without redundancy. It is well-structured and easy to parse.

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 5 optional parameters and no output schema, the description covers the return structure (source, citation_uri, raw payload), the effect of mark_read, and provides an alternative HTTP endpoint. It lacks mention of error handling or rate limits, but given the annotation hints, it is fairly complete.

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

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

The schema coverage is 100%, so baseline is 3. However, the description adds value by explaining the purpose of key parameters: 'type', 'since' (ISO timestamp), and especially 'mark_read' (flags read state). The 'unread_only' parameter is not mentioned in the description, but overall the description enhances understanding.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed'. It lists key fields returned and filter options, distinguishing it from sibling tools like recall or recent_changes which handle different types of data.

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

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

The description explicitly mentions that the same feed is available via an HTTP endpoint for scripts/dashboards, providing an alternative usage path. However, it does not explicitly state when to use this tool versus other sibling tools, leaving some room for ambiguity.

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

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

Description discloses all key behaviors: parallel fan-out to multiple sources, GDELT→GNews fallback on rate limits/5xx, USPTO soft-failure due to API sunset, and return structure (changes[], total_changes, citation URIs). Annotations already declare readOnly, openWorld, idempotent, non-destructive; description adds context not contradicting them.

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

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

Description is dense with information but every sentence adds value. Front-loaded with user query examples. Slightly long but necessary given complexity. No fluff.

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

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

Given the tool's complexity (multiple sources, fallback, relative dates) and absence of output schema, the description is remarkably complete. It explains input format, data sources, fallback logic, failure behavior, and return structure.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining 'since' format with examples (ISO date and relative shorthand like '7d', '30d') and recommending '30d' or '1m' for typical monitoring. Also clarifies 'value' can be ticker or CIK.

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

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

Description clearly states the tool provides a change feed for a company over a time window, listing specific data sources (SEC, GDELT/GNews, USPTO) and differentiating from entity_profile. Verb 'fans out' and resource 'change feed' are specific.

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 example queries ('What's new with X'), guidance on when to use entity_profile instead, and explains fallback behavior for GDELT/GNews. Also gives format guidance for 'since' parameter with typical values.

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

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

Description adds scope (key-value, identifier-scoped) and persistence (24-hour vs persistent) beyond annotations. Annotations already indicate idempotent, non-destructive, and non-read-only. No contradictions, but could note key overwrite behavior.

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

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

Description is efficient with 4 sentences, front-loaded with the core purpose, and each sentence adds value without redundancy.

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

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

Given the simple key-value nature and no output schema, the description covers use cases, scope, persistence, and sibling relationships completely.

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

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

Schema coverage is 100% with parameter descriptions. The tool description does not add new parameter-specific information beyond what the schema provides, so baseline 3 is appropriate.

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

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

Description clearly states the tool saves data for reuse across conversations/sessions, with specific verb (Save), resource (data), and distinguishes from sibling tools recall and forget.

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

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

Explicitly tells when to use (discover something worth carrying forward), mentions paired tools (recall, forget), and clarifies persistence differences between authenticated and anonymous users.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds that each call cascades through multiple endpoints, which is valuable context beyond annotations. No contradictions, though detailed limits or disambiguation specifics are omitted.

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 a single well-structured paragraph with bullet-like formatting for types. It front-loads query examples and efficiently conveys all key information. Minor verbosity could be trimmed, but overall concise.

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

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

Given no output schema, the description adequately explains return values for each type (ticker, CIK, company name for company; RxCUI, ingredient, brand for drug) and mentions citation URIs. Could benefit from output format details, but sufficient 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 covers both parameters with descriptions, but the description adds concrete examples and acceptable input formats (ticker/CIK/name for company, brand/generic for drug), enhancing 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?

Description clearly states the tool resolves names to official identifiers, with specific query examples and supported entity types (company, drug). It distinguishes itself from sibling tools by explicitly positioning it as the first step when an ID is needed.

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?

Directly instructs 'Use FIRST whenever you have a name but need an ID.' and explains it replaces multiple manual lookups. Context and alternative are clear, though no explicit when-not-to-use is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds that it internally probes each entity with ai_visibility_check, ranks results, and surfaces most/least recognized. This provides useful 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?

Two-sentence description is concise and front-loaded: first sentence states core purpose, second adds usage and return details. No unnecessary words.

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

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

Description explains functionality (probes, ranks, returns ranked list with score/confidence/signal density) despite no output schema. It covers most aspects for a comparison tool; minor gap on edge cases like entity count constraints (2-8 mentioned in schema but not in description).

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 critical context: first entity is treated as subject, models default to workers-ai, _apiKey usage, context disambiguates. This significantly enhances meaning beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities, with a specific verb 'Compare' and resource 'AI visibility'. It distinguishes from sibling tools like ai_visibility_check (single entity) and gives an example use case ('does Claude know about us as well as our competitors?').

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

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

Description states it is useful for competitive AI-marketing audits and implies comparison use case. It differentiates from ai_visibility_check by mentioning multiple entities. However, it lacks explicit when-not-to-use or alternatives guidance.

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

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

The description adds behavioral details beyond annotations: partial failures degrade gracefully with sources_failed, bundlephobia first measurement may take 5-30s. Annotations already mark it as readOnly, idempotent, and non-destructive, so the description enriches this.

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 that front-loads purpose and usage, then adds details. It could be slightly more structured (e.g., bullet points), but it remains concise and informative 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?

Even without an output schema, the description fully explains the return value: summary block, per-advisory detail, links, alternatives. It also covers error behavior, partial failures, and ecosystem limitations. This provides a complete mental model.

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 does not add new meaning beyond what the schema already provides (e.g., scoped packages, default version). It repeats the schema's info without further elaboration, 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 it is a composite npm package check for safety, popularity, and size. It distinguishes itself by combining deps.dev and bundlephobia in one call, and is distinct from sibling tools which are unrelated.

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

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

Explicitly tells when to use: when an agent asks about package safety, popularity, size, or cost. Also specifies scope (NPM only in v1; other ecosystems fall under a different tool). This provides clear guidance.

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

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

The description provides significant technical details beyond the annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging. This gives the agent a clear understanding of behavior and limitations.

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

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

The description is concise (4-5 sentences) and front-loaded with the core purpose, followed by usage guidance and 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?

Given the tool's complexity (semantic search, character cap, offset output) and the absence of an output schema, the description covers all necessary aspects: embedding details, windowing, truncation, and integration with a sibling 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 the description adds limited value for parameters. The 'text' parameter's max size is mentioned but already in the schema. The query examples are helpful but not strictly necessary. Baseline score of 3 is appropriate.

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

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

The description clearly states that this tool performs semantic search inside a fetched record. It provides concrete examples (SEC 10-K body, article) and specifies outputs (top-N passages with offsets and similarity scores). The distinction from sibling tool ask_pipeworx_grounded is explicitly mentioned.

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 advises using this tool when a record is too large for the prompt, effectively setting context. It also suggests pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use it or list alternatives beyond the mentioned sibling.

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

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

Beyond annotations (idempotent, not read-only), the description adds significant behavior: OAuth requirement, delivery channel details, SMS rate limit (10/day), phone verification, webhook auto-disable, and return of subscription id. It does not explicitly clarify idempotency behavior (e.g., re-subscribing same parameters returns existing id), but overall transparency is high.

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 moderately long but well-structured with a clear lead sentence and subsequent details in bullets. Each section adds necessary information, though some redundancy exists (e.g., SMS cap mentioned twice). Overall efficient.

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

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

Given the complexity (3 parameters, nested objects, no output schema), the description is comprehensive. It covers prerequisites, types, params, delivery options, and return value. Missing explicit explanation of idempotency behavior and potential error states, but still quite complete.

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

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

Schema coverage is 100% with descriptions, and the description adds substantial value by providing concrete examples for each type (e.g., sec_8k with items codes), detailed structure for params, and extra context for delivery (e.g., webhook signing, phone verification requirement). This greatly aids parameter understanding.

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

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

The description clearly states the action ('Create a proactive monitoring subscription') and the resource ('live-data event stream'). It also mentions the return value (subscription id), distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

The description specifies the required OAuth account and lists supported types with example parameters, providing clear context for use. However, it does not explicitly state when not to use it or compare with alternative tools.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: returns category-bucketed examples with exact tool+argument shapes, onboarding entry point.

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

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

Well-structured and front-loaded, but slightly verbose with repeated topic list. Still effective and clear.

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

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

Given one optional parameter and no output schema, description fully covers purpose, usage, and return format (categorized examples with tool shapes). No gaps.

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

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

Schema coverage is 100% with parameter description. Description enriches by listing topic options and clarifying omission gives full spread, 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?

Description clearly states the tool returns example questions categorized by topics for onboarding. It distinguishes from siblings like ask_pipeworx (which answers questions) and discover_tools.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also explains when to pass topic vs omit.

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 value beyond annotations by explaining that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. This clarifies the non-destructive nature and data lifecycle.

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

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

The description is two sentences with no wasted words. It efficiently conveys cancellation, ownership enforcement, and the deactivation behavior in a front-loaded structure.

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

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

For a simple one-parameter mutation tool with annotations and no output schema, the description covers the key behavioral and post-condition aspects. It could optionally mention expected return value, but current 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?

The single parameter 'id' is well-described in the schema as 'Subscription id returned by subscribe.' The description adds no additional detail, and schema coverage is 100%, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool cancels a subscription by ID, with ownership enforcement and deactivation behavior. It explicitly distinguishes the outcome (deactivate not delete) from siblings like subscribe or list_subscriptions, though it does not name 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?

The description includes the important constraint that only own subscriptions can be cancelled, but does not provide guidance on when to use this tool versus alternatives like subscribe or list_subscriptions.

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 include readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, which are consistent. The description adds behavioral context: it returns a verdict (with specific categories), grounded/structured actual value with citation, and reasoning. It also details the exact percent-delta math for financial claims, going beyond annotation hints.

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, front-loaded with query examples. It packs significant detail (two verification paths, output components, replacement benefit) without unnecessary words. While dense, it could be slightly restructured for easier scanning, but it remains efficient.

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

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

Despite having no output schema, the description clearly explains return values (verdict, actual value with citation, reasoning). With low complexity (2 simple params, no nested objects) and good annotations, the description is comprehensive. It even notes the efficiency gain over sequential calls, fully covering the tool's 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 parameter descriptions for 'claim' and 'tolerance_pct'. The description adds meaningful context: examples for claim, tolerance usage (overrides implied tolerance, default capped at 5), and hints for hallucination detection. This extra detail justifies a 4 despite baseline 3 due to full 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 starts with explicit query patterns ('Is it true that…', 'fact check', etc.) and clearly defines the tool as natural-language claim verification against authoritative sources. It distinguishes between company-financial claims (SEC EDGAR) and other factual claims, providing specific pipeline details. This specificity differentiates it from sibling tools like deep_research or ask_pipeworx_grounded.

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

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

The description states 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear usage context. It explains the two-path handling based on claim type and mentions it replaces sequential calls, though it doesn't explicitly list when not to use it or name alternatives beyond implicit differentiation.

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