Gov Uk Content

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by explaining the return format (per-model and combined view), cost implications (free default, BYO key for Anthropic), and that the Anthropic probing requires a separate API key. This goes beyond the structured annotations.

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

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

The description is a single paragraph of three sentences, front-loaded with the core action and output. 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?

Despite lacking output schema, the description adequately explains the return structure ({score, confidence, signals, raw_response} + combined view). It also covers default behavior, optional parameters, and use cases, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the purpose of _apiKey (BYO key, direct billing) and context (disambiguation). This extra context justifies a 4.

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

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

The description clearly states the tool probes LLMs for knowledge about entities and returns a visibility score (0-100). It distinguishes itself from sibling tools by focusing on AI visibility across multiple models, unlike other tools that are for pipeworx queries, scanning competitors, etc.

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 when to use the tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides context on default vs. paid model usage. However, it does not explicitly exclude alternatives or mention when not to use it, which prevents a perfect score.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds meaningful behavioral context: it routes to other tools, fills arguments, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. It also implies a tradeoff by noting ask_pipeworx_grounded is for 'hallucination-resistant' answers, which helps set expectations. 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 long but front-loaded with the key directive ('PREFER OVER WEB SEARCH') and structured into: what it does, when to use, examples, and alternatives. Each section carries information, though some redundancy exists ('START HERE' echoes the preference). For a default entry point, the length is justified.

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

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

With no output schema, the description compensates by specifying the return type (structured answer with citations) and covering a vast domain range via examples. It also clarifies integration with alternatives and mentions performance ('one fast call'). For a routing tool of this complexity, the description is remarkably 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% — the 'question' parameter description documents the natural language request and lists all six aliases. The description's examples illustrate question phrasing but add no new parameter semantics. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the tool's function: answer factual questions by routing to 5,439 tools across 1,412 verified sources. It distinguishes itself from siblings like ask_pipeworx_grounded (hallucination-resistant) and deep_research (broad multi-part fan-out), and explicitly contrasts with web search. The verb 'ask' plus the specific data domains and citation output make purpose unambiguous.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', providing concrete triggers ('what is', 'look up', 'find', etc.) and numerous examples. It also gives clear when-not-to-use guidance: 'Step up only when needed' for grounded or deep research. This is textbook usage differentiation.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable context: it may have candidate routing improvements enabled live, currently matches ask_pipeworx exactly, and is a full working router rather than a fallback. This goes beyond the annotations without contradicting them.

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

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

The description is somewhat verbose but well-structured: it opens with the beta relationship, explains the current inactive candidate state, gives explicit usage direction, and clarifies it's fully functional. Each sentence adds distinct information, and the front-loading of 'Beta version of ask_pipeworx' sets immediate context.

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

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

Given the tool's complexity (a router over 5,439 tools) and lack of output schema, the description covers the essential points: it's identical to ask_pipeworx, matches its response shape, has no fallback, and includes live candidate routing when active. It relies on ask_pipeworx for full return details, which is reasonable for a beta sibling. The description is adequate but could briefly mention potential risks of using an experimental router.

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 provides 100% coverage for all 6 parameters, all documented as aliases for the same 'question' field. The description adds no additional parameter semantics—it only mentions 'same arguments' as ask_pipeworx, which is redundant. Since the schema does the heavy lifting, 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 identifies this as a beta version of ask_pipeworx, a universal router with 5,439 tools and the same response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge for candidate routing improvements. However, it relies on the reader knowing what ask_pipeworx does; it doesn't independently state that it answers questions by routing to tools.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also clarifies that results are compared against the stable router, implying it's the experimental alternative to ask_pipeworx. This gives clear usage context and differentiates from sibling tools.

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

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

Goes far beyond the readOnly/openWorld/idempotent annotations by describing the exact return shape on success (answer, evidence, confidence, source, etc.) and failure (refusal_reason with enumerated values), the cost of one extra LLM call, and the constraint of using ONLY the tool result content. 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 front-loaded with purpose and well-structured with clauses, but it is somewhat long. However, every sentence adds valuable behavioral or usage information, so it earns a 4 rather than a 3.

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

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

Despite no output schema, the description fully documents success and refusal return shapes, refusal reason codes, use cases, and cost tradeoff. It is self-contained and leaves no major gaps for an agent to invoke the tool correctly.

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

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

The input schema covers all 6 parameters with full descriptions (aliases for question), so schema coverage is 100%. The description does not add parameter-level detail, which is acceptable since the schema already does the heavy lifting. Baseline 3 is appropriate.

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

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

The description clearly defines the tool as a 'hallucination-resistant answer mode' with a specific process: routing to tools, fetching data, and extracting answers only from tool results. It distinguishes itself from ask_pipeworx by emphasizing the grounded, evidence-based extraction and explicit refusal 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?

Explicitly states when to use ('whenever an answer will be quoted, cited, or acted on...') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), citing the extra LLM call cost. This provides clear decision guidance versus 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?

The description discloses many behavioral traits beyond the annotations: low-confidence resolutions short-circuit with status, closed markets return a status, wide-spread markets carry a tradeability note, and cancellation rules are parsed. It details response shapes and field semantics. Annotations already state readOnlyHint, openWorldHint, idempotentHint, and destructiveHint; the description adds depth 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 clear sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). It is front-loaded with the main purpose and input guidance. While every sentence adds value, it could be slightly more concise; however, the detail is justified for the tool's complexity.

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

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

The description is comprehensive, covering classifiers, fan-out examples, response shapes, resolver contract, parent events, news fallback, safety conditions, closed markets, and cancellation rules. No output schema exists, so the description fully explains return fields and edge cases, making it complete for correct invocation.

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

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

Schema coverage is 100% (all 3 parameters have descriptions). The description adds significant value: explains 'market' accepts slug, URL, or question text; clarifies 'depth' enum values (quick vs thorough) with default; and describes 'include_raw' with size implications (summarized ~20KB vs full 50-500KB). This exceeds what the schema alone provides.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet), action (research/data pull), and input types (slug, URL, question). It also differentiates from sibling tools like polymarket_edges and polymarket_arbitrage by stating use cases ('should I bet on X', 'what does the data say about Y').

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 recommends the tool for specific queries ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). It also warns about inspecting the resolver contract before trusting results, and describes safety mechanisms (low-confidence short-circuit, closed market handling). While it doesn't explicitly state when not to use, the context is clear enough for an agent to differentiate.

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

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

Adds value beyond annotations by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of fiscal years, and sorting behavior. Annotations already indicate read-only, idempotent, non-destructive behavior, so description complements 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 front-loaded with trigger phrases and examples, then provides details on behavior. It is fairly long but without fluff; each sentence adds unique value. A slight reduction in length could improve conciseness.

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

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

Covers purpose, input format, data sources, output (paired data with citation URIs), and efficiency gains. No output schema exists, but the description gives sufficient insight into return values. Lacks mention of error cases or limitations.

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

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

Schema coverage is 100%, and the description enriches meaning by explaining entity types ('company' uses tickers/CIKs, 'drug' uses names) and specifying constraints (2–5 items). This goes beyond the schema's enum and array descriptions.

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

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

The description clearly states the tool performs side-by-side comparisons of 2–5 entities, specifying 'compare', 'rank', 'head to head' as trigger phrases. It distinguishes itself from sibling tools like entity_profile by emphasizing parallelism over sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing clear usage context. However, it does not mention when not to use or alternatives like entity_profile for single entities, which could improve clarity.

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, non-destructive, idempotent behavior. The description adds no extra behavioral context (e.g., rate limits, data freshness). For a simple retrieval tool with rich annotations, a 3 is adequate.

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

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

Extremely concise (6 words), but it lacks a full sentence structure and could be considered under-specified. Every word earns its place, but more context would improve usability.

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

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

Given a single parameter, comprehensive annotations, and an output schema, the description is minimally complete. However, it does not explain what 'content' includes (e.g., metadata, body), though the output schema likely covers that.

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?

Only one parameter (base_path) with no schema description. The description adds minimal semantic value by stating 'by base_path', but does not clarify what the parameter represents beyond its name.

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 it provides 'Content for a gov.uk page by base_path', but lacks a clear verb like 'retrieve' or 'get'. It distinguishes from siblings by focusing on content retrieval, but the purpose is implied rather than explicit.

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

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

No guidance on when to use this tool versus alternatives (e.g., search tools). No context about prerequisites, limitations, or exclusions is provided.

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

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

The description goes far beyond the annotations by disclosing the research pipeline (decomposition, parallel routing), the output structure (findings packet, verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), time expectations, and the distinction from open-web search. It also explains semantic excerpting and the second-hop iteration. No contradiction with annotations.

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

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

The description is long but densely packed with essential information, covering account requirements, use cases, output format, and timing in a logical order. Every sentence serves a purpose, but the single-paragraph wall of text could be slightly better structured (e.g., breaking into bullets) for readability. Still, the length is justified by the tool's complexity.

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

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

Given the tool's complexity and the absence of an output schema, the description thoroughly compensates: it explains the return packet, gaps and contradictions fields, execution duration, and prerequisites. It also covers alternatives and limitations (e.g., breaking news), making the description self-sufficient for an agent to invoke the tool correctly.

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

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

Although the schema already documents both parameters, the description enriches them significantly: it explains the depth enum's behavioral differences (standard re-angles gaps, thorough adds lead-chasing), and clarifies that the question should be broad/multi-part. This adds meaning well beyond the schema's basic parameter descriptions.

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

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

The description clearly identifies deep_research as a multi-source research tool over Pipeworx's structured data sources, gives concrete example questions, and explicitly distinguishes it from ask_pipeworx and open-web search. The verb 'research' and the resource '1412 STRUCTURED data sources' make the purpose unambiguous.

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

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

The description provides explicit guidance on when to use deep_research vs ask_pipeworx (single lookup, breaking/current news), and notes the account requirement with a fallback if not signed in. It also explains the depth options and when each is appropriate, making selection criteria clear.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output structure and reusability, going beyond the annotations.

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

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

The description is a single, well-structured paragraph that front-loads the main purpose and then provides specifics. It is dense but not verbose; every sentence adds information. No unnecessary repetition or fluff.

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

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

Given 6 parameters (1 required), no output schema, and the tool's complexity, the description adequately explains the input (natural language query, limit, aliases) and output (top-N tools with schemas). It also provides contextual guidance on when to use it. The missing detail on return value structure is compensated by the explicit statement that each result is ready to call directly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining that 'query' is a natural language description, providing examples in the schema, and noting aliases. It also mentions the 'limit' parameter's default and max. However, it does not elaborate on each alias beyond listing them, so there is some redundancy.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It provides specific domains (SEC filings, financials, etc.) and explains the output format (top-N relevant tools with names, descriptions, full schemas). This effectively distinguishes it from siblings like 'search' or 'search_within' by positioning it as a discovery tool to use first.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for: ...' and advises 'Call this FIRST when you have many tools available and want to see the option set.' This provides clear guidance on its role as a precursor to other tools, though it does not explicitly mention when not to use it.

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

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

Annotations already declare the tool as read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: patents soft-fail due to API sunset, names are not supported, and the return structure includes specific fields like CIK, filings with URIs, fundamentals, etc. No contradictions with annotations.

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

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

The description is a single paragraph but well-structured: starts with example queries, then states preference over other tools, then lists data sources and return fields. It is slightly verbose but every sentence adds value. Could be broken into smaller sections 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 the complexity (multiple data sources, fallbacks, limitations) and absence of an output schema, the description covers all essential aspects: what the tool does, when to use, input constraints, output structure, and known limitations (patents soft-fail, name resolution need). No missing critical information.

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

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

Schema covers 100% of parameters with descriptions. The description adds detail beyond schema: for 'value' it explains ticker or zero-padded CIK, reinforces that names are not supported, and for 'type' it confirms only 'company' is supported. This helps the agent correctly format inputs.

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

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

The description begins with concrete example queries and clearly states it provides a 'full cross-source profile of a US public company'. It lists data sources and return fields, distinguishing it from single-pack lookups. The verb 'profile' combined with 'cross-source' precisely defines the tool's purpose.

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

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

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also warns that names are not supported and instructs to use resolve_entity first if only a name is available. This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint=true. The description adds context (clearing sensitive data) but does not elaborate on behavior for missing keys or idempotency, which is hinted at by idempotentHint=true.

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

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

Two concise sentences with no fluff: first states purpose, second gives usage context and sibling tool pairing. Every sentence is valuable.

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

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

Given a single parameter with full schema coverage and annotations covering destructiveness, the description is complete. It also adds context on when to use and why, including security considerations (sensitive data). No output schema needed.

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

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

Schema coverage is 100%, and the schema already describes the 'key' parameter as 'Memory key to delete'. The tool description does not add further semantic meaning beyond what the schema provides.

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

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

The description uses a specific verb 'delete' and identifies the resource as 'previously stored memory by key', clearly distinguishing it from sibling tools like 'remember' and 'recall' by explicitly pairing with them.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also recommends pairing with 'remember and recall', providing clear alternatives.

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

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

The description discloses behavioral traits beyond annotations: it fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. Annotations already declare readOnlyHint and idempotentHint, so description adds value 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 a single, well-structured paragraph with three sentences. It front-loads the main purpose and includes usage examples. Every sentence is informative and earns its place.

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

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

Given the tool's simplicity and lack of output schema, the description adequately explains the output format (standard llms.txt markdown, single text blob) and the process. It covers all necessary context for a straightforward 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%, so baseline is 3. The description adds minimal extra meaning beyond the schema, only that max_links limits link entries. It does not provide syntax or format details.

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

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

The description clearly states it generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource. 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?

The description lists explicit use cases (getting a client's site indexed, drafting for own project, auditing competitor). It does not explicitly state when not to use it or compare to alternatives, but the examples provide clear context.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds return format and default behavior (active subscriptions), supplementing annotations without contradiction.

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

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

Two sentences, front-loaded with purpose and return fields, followed by usage guidance. 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?

For a simple list tool with one optional parameter and no output schema, the description adequately covers what it returns and when to use it. Minor gap: doesn't mention pagination or ordering.

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 implicitly references the 'include_inactive' parameter by mentioning 'active' and 'cancelled', but doesn't add new info beyond schema definition.

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 states 'List the caller's active subscriptions' with specific verb 'list' and resource 'subscriptions'. It also lists return fields, clearly distinguishing from sibling tools '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?

Explicitly advises using this tool 'to review what you're monitoring before adding more or to find an id to cancel', providing clear when-to-use guidance.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds pagination behavior (default 20, max 100) and specifies returned fields, which provides useful context beyond the annotations.

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

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

The description is a single sentence that is front-loaded with the core purpose and efficiently covers key details without unnecessary words.

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

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

Given the existence of an output schema, the description adequately explains what the tool does, what fields are returned, and pagination. It is complete for a list endpoint with two optional parameters.

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 0%, so the description compensates by explaining count and start as pagination parameters with default and max values. However, it does not specify the default for start (likely 0) and does not describe the parameters in the schema properties. Partial coverage.

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

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

The description clearly states the action (list), the resource (GOV.UK government organisations), and specifies the fields returned (title, URL path, acronym, operational state). It also includes pagination details, which distinguishes it from other tools like search or content.

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

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

The description implies usage for listing organisations but does not explicitly state when to use this tool versus alternatives like search or content. No exclusions or prerequisites are mentioned.

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 annotations are all false, so the description carries the full burden of behavioral disclosure. It transparently discloses rate limits ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and downstream impact ('The team reads digests daily and signal directly affects roadmap'). It also sets content expectations ('don't paste the end-user's prompt'), making the tool's behavior and constraints fully apparent.

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 the core purpose and then covers usage, exclusions, formatting, and limits. Every sentence contributes meaningful information and avoids fluff. While it is longer than typical descriptions, the tool's multifaceted nature (scope, exclusions, rate limits) justifies the length. It could be slightly more structured with bullets, but it remains readable 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?

The description is fully complete for this tool's complexity. It covers what the tool does, when to use it, when not to use it, how to format feedback, what limits apply, and what happens after submission. No output schema exists, but the description doesn't need to explain return values for a feedback tool—its behavior and impact are sufficiently transparent. The inclusion of rate limits and scope exclusions makes the context comprehensively complete.

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

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

The input schema already provides 100% coverage for all parameters, including descriptions for the 'type' enum, 'context' object, and 'message' string. The description adds valuable semantics beyond the schema by instructing users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies how to populate the message and context parameters. This raises it above the baseline of 3 for schema-heavy tools.

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

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

The description clearly states the tool's function: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the resource (Pipeworx team) and the action (send feedback), and distinguishes it from sibling tools by focusing on feedback submission rather than data retrieval or analysis. It even enumerates feedback types (bug, feature, data_gap, praise), leaving no ambiguity about the tool's purpose.

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

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

The description provides explicit when-to-use guidance: '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 gives a clear exclusion: 'ONLY for tools served by this Pipeworx connection — if the tool came from a different MCP server... file it with that server instead.' This directly addresses alternatives and edge cases, offering unambiguous usage direction.

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

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

Annotations already indicate safe, read-only, idempotent behavior. Description adds valuable context: self-aggregating from analytics, no PII, cached 5min-1h. No contradictions.

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

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

Concise, well-structured with bullet points for use cases. Every sentence adds value; no repetition or fluff.

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

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

With one optional param, rich annotations, and no output schema, the description fully covers purpose, usage, source, caching, and output summary. No gaps for this tool's complexity.

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

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

Single parameter with 100% schema coverage. Description adds behavioral guidance: shorter windows for hot items, longer for steady-state, plus default. Adds value beyond schema enum.

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

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

The description clearly states the tool returns trending data from Pipeworx: top tools, top packs, and call volume over a window. It distinguishes from siblings like ask_pipeworx or discover_tools by focusing on popularity metrics.

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?

Lists three specific use cases (discovering hot data, confirming canonical tools, aligning use cases) and explains window choice trade-offs. Lacks explicit 'when not to use' or alternative tool names, but context is clear.

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

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

Annotations declare readOnlyHint, idempotentHint, and destructiveHint, which the description does not contradict. The description adds extensive behavioral context: semantic anchor (Jaccard similarity ≥0.30), partition filter (placeholder fraction >20% returns null), fill check against live CLOB depth, and handling of skipped_low_similarity. This significantly enriches transparency beyond the annotations.

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

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

The description is detailed and well-structured with clear section labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While it is longer than ideal, every sentence adds necessary information. It is front-loaded with the core purpose and modes. Minor redundancy could be trimmed, but overall efficient.

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

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

No output schema exists, so the description fully explains the response format: opportunities array with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and partition_check object in event mode. It also covers edge cases like skipped_low_similarity and placeholder filter, ensuring the agent has complete understanding despite the tool's complexity.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra meaning: explains that 'event' accepts full Polymarket URLs (not in schema), provides examples for both parameters, and gives context about how each mode works. This additional information is valuable but the schema already covers the basics, hence a 4.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It explicitly distinguishes three modes (trending_scan, event, topic) with specific verbs and resources, differentiating it from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit guidance on when to use each mode: no args for trending_scan, 'event' for a specific market slug, 'topic' for cross-event scanning. It includes rationale, examples, and even warns when not to trade (realizable_edge_pp ≤ 0). It references sibling tool polymarket_fill_risk for custom sizing, offering complete usage directives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, indicating a safe, read-only operation. The description adds significant behavioral context beyond annotations: caching behavior (1h at KV level), detailed explanation of three model families and their internal mechanics, and diagnostics structure. No contradictions with annotations.

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

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

The description is front-loaded with the main purpose and well-structured with sections for each model family, knobs, and diagnostics. However, it is overly long (approximately 300 words) and contains excessive detail about internal model mechanics that could be relegated to external documentation.

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

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

Given the complexity (9 parameters, no output schema, multiple model segments), the description is extremely complete. It explains the output structure (by_segment, fed_candidates, _diagnostics), caching behavior, model families in detail, and how knobs affect results. The diagnostics field helps callers understand empty segments.

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 covers all 9 parameters with descriptions, so schema_description_coverage is 100%. The description does not add much new information for parameter semantics beyond what the schema provides; it mainly restates the purpose of some knobs. 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 that the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It identifies the three model segments. However, it does not explicitly differentiate from sibling tools like polymarket_arbitrage, which could cause confusion.

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

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

The description provides a clear use case and explains when to use the tool ('what should I bet on today'), but it lacks explicit guidance on when not to use it or direct comparisons to alternatives. The context is implied through the detailed description, but no exclusions or alternatives are mentioned.

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 details data sources (daily snapshots), TTL (60-day), decay calculation methodology (daily closes, not intraday), and response structure. No contradictions with annotations.

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

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

The description is well-structured with inline labels (tracked[], expired[], snapshot_dates[]) and front-loaded with the core question. It is verbose but every sentence contributes necessary context.

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

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

Despite no output schema, the description exhaustively explains all return fields, including behavior for edge entry/expiry, trend classification, and snapshot gaps. Limitations are also mentioned, making it self-contained.

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

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

Schema coverage is 100% with parameter descriptions. The description reaffirms defaults and constraints (days default 14, max 30; window default '1wk') but does not add significant new 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 provides edge persistence and decay telemetry, answering specific questions about edge longevity. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw edge 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 explains when to use this tool—to assess how long an edge has existed and whether it's decaying. It implicitly contrasts with fresh-wide-edge scenarios, but does not explicitly list when-not-to-use or 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?

The description explains behavioral traits beyond annotations: it walks the order-book ladder, returns a verdict (clean/degraded/cannot_fill), and details per-leg fill information. Annotations already mark it as read-only, idempotent, and non-destructive. The description adds meaningful 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 well-structured with clear sections for single-market and basket modes, and it front-loads the core purpose. However, it is somewhat lengthy (several sentences) and could be slightly more concise while retaining all necessary details.

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

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

Given the tool's complexity (multiple modes, no output schema), the description is remarkably complete. It enumerates all return fields for both modes (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single; theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg fill detail, thin_legs, max_clean_notional_usd, forced_directional_risk for basket) and warns about edge cases like partial fills and stranded positions.

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

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

Schema description coverage is 100%, but the description adds significant meaning by explaining the two modes (single-market vs basket), default behaviors (side auto-detection for basket), and different interpretations of size_usd (max spend on buys, target proceeds on sells for single; settlement notional for basket). This exceeds baseline expectations.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and explicitly distinguishes between single-market and basket modes. This sets it apart from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why alternatives would be insufficient, such as 'theoretical overround on thin books is not capturable' and 'partial basket fills convert an arb into an unhedged directional position.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context: compatibility_warning conditions, temporal alignment, skipped cross types, and the note that most pre-mapped topics are not tradeable. This goes beyond the annotations to inform the agent of edge cases.

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 verbose. Important information is front-loaded, but the many details (e.g., specific safety field names and their conditions) could be streamlined. It earns its place, but some sentences are dense and may overwhelm an agent.

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

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

Given the tool's complexity (two modes, safety checks, no output schema), the description covers return values (leg-by-leg prices, spreads, safety fields) and explains when spreads are meaningful. It is complete enough for an agent to use the tool effectively without needing additional context.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the two modes (topic vs. explicit tickers) and how parameters interact (overrides). It also mentions that the topic parameter has 10 pre-mapped shortcuts, which the schema implies but does not fully explain.

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: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It uses a specific verb ('spread') and resource ('cross-venue'), and distinguishes it from sibling tools like polymarket_arbitrage by focusing on two different prediction markets.

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

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

The description explains two modes of use (topic shortcuts and explicit tickers) and provides clear context on when the spread is meaningful versus when it's not via compatibility_warning and temporal_alignment fields. However, it does not explicitly compare against alternatives among sibling tools, missing a clear 'when-to-use vs. when-not-to' statement.

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 scoping (by identifier) and the behavior of omitting the key to list all, which is not in annotations. No contradiction.

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

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

Two sentences, front-loaded with the primary function, then use cases and context. Every sentence is valuable; 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?

Description is nearly complete given the tool's simplicity and existing annotations. It covers purpose, usage, and scoping. Could explicitly state the return format but the examples imply it, so minor gap.

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

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

Schema coverage is 100% but description adds meaning: explains the optionality of 'key' (omit to list all, provide to retrieve specific value). This goes beyond the schema's brief description and clarifies behavior.

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 retrieves a value by key or lists all keys, with specific examples (ticker, address, notes). It distinguishes from siblings 'remember' (saves) and 'forget' (deletes).

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 (look up stored context) and when not (use 'remember' to save, 'forget' to delete). Mentions pairing with siblings, providing clear alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context about return fields and side effect of mark_read, complementing annotations without contradiction.

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

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

Concise, front-loaded with purpose, then details. Every sentence adds value without redundancy. Efficient use of words.

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

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

Given no output schema, description adequately describes return fields (source, citation_uri, raw event payload). Also explains mark_read side effect and provides an alternative access method. Fully covers what an agent needs.

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?

Description clarifies filtering with examples ('sec_8k', ISO timestamp) and explains mark_read effect. Schema has 100% coverage, and description adds usage context beyond parameter names.

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

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

Clearly states the verb 'Pull' and 'Returns', specifies resource as 'fired events from your subscription feed', and distinguishes itself by mentioning filtering and mark_read behavior. No ambiguity.

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

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

Provides explicit guidance on filtering by type and since, mark_read usage, and notes that polling works. Also mentions an alternative HTTP endpoint. However, does not explicitly contrast with sibling tools like 'subscribe' or 'search'.

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 it's read-only and idempotent. The description adds valuable behavioral details: fans out to multiple sources, uses GDELT→GNews fallback, and USPTO soft-fails. No contradiction with annotations.

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

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

The description is a single, dense paragraph that front-loads examples and purpose. It is concise without missing key information, though it could be broken into clearer sections 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?

The tool has 3 parameters and no output schema. The description covers all essential aspects: inputs, sources, fallback behavior, return structure, and when to use an alternative. It is comprehensive for an AI agent's needs.

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

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

Schema coverage is 100%, baseline 3. The description enhances parameter meaning with examples for 'since' (ISO dates and relative shorthands) and 'value' (ticker or CIK), and clarifies that 'type' currently only supports 'company'. This adds value beyond the schema.

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

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

The description explicitly states the tool's purpose as a change feed for a company over a recent window, with specific examples of queries. It distinguishes from the sibling tool entity_profile by noting that entity_profile is for static profiles.

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

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

The description provides clear usage examples ('What's new with X') and explicitly directs users to entity_profile for static profiles. It mentions the USPTO soft-failure, offering context on when results may be incomplete.

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 show readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds key-value pair scoping by identifier and retention details (persistent for authenticated, 24h for anonymous), which are useful behavioral traits beyond annotations.

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

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

Three focused sentences with no redundancy. Front-loaded with the core purpose, followed by usage guidance and behavioral details. 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?

For a simple two-parameter tool with full schema coverage and explicit annotations, the description covers purpose, usage, behavior, and sibling relationships. No output schema needed. Complete for the agent's needs.

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. Description provides examples of key patterns (e.g., 'subject_property', 'target_ticker') and value types, adding context beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose with a specific verb ('save data') and resource ('data the agent will need to reuse later'), and distinguishes it from siblings like 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 states when to use ('when you discover something worth carrying forward') and implies alternatives by mentioning recall (retrieve) and forget (delete). Also provides context on session persistence for authenticated vs. 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 declare the tool as read-only, idempotent, and non-destructive. The description adds valuable detail about internal cascading lookups and return values (e.g., ticker, CIK, RxCUI, citation URIs), which is beyond what annotations provide. No contradiction exists.

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

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

The description is front-loaded with examples and a clear action statement. It is logically structured: usage scenario, supported types with details. While it is moderately long, every sentence adds value; a slight reduction could improve conciseness.

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

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

Given no output schema, the description adequately covers what the tool returns for each entity type and mentions internal complexity. It is comprehensive for a resolution tool but omits error handling or edge cases like ambiguous names, leaving minor 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%, describing both parameters. The description adds real-world context for the 'type' and 'value' fields, explains valid inputs (ticker, CIK, names for company; brand or generic for drug), and clarifies output per type. This goes beyond the schema, justifying a score above the baseline of 3.

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

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

The description opens with concrete examples ('What's the ticker for…') and clearly defines the tool as resolving a name to a canonical identifier. It distinguishes from sibling tools by stating 'Use FIRST whenever you have a name but need an ID.' The verb and resource are specific and unambiguous.

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

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

The description explicitly instructs to use this tool first when a name needs to be converted to an ID. It provides the context with examples and notes that it replaces multiple manual lookups, giving clear usage guidance, though it does not explicitly list when not to use it or 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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds valuable behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, signal density. 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 are front-loaded with the main action and outcomes. Every sentence adds value: first defines purpose and output, second provides use case and return details. No wasted words.

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

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

No output schema, but description sufficiently describes return values (ranked list, score, confidence, signal density). It also explains behavior with models and apiKey. Leaves no major gaps for an agent to understand tool function.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds some context (e.g., first entity treated as subject for narrative) but does not significantly extend beyond what schema descriptions already provide. Parameter meaning is clear from schema.

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

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

The description uses specific verb ('Compare AI visibility') and identifies the resource ('multiple entities'). It explicitly differentiates from sibling 'ai_visibility_check' by stating it probes each entity with that tool and ranks results, making it a clear multi-entity comparison tool.

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

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

The description states usage for 'competitive AI-marketing audits' and provides a concrete example question. It implicitly indicates that for a single entity, one should use 'ai_visibility_check' instead, but does not explicitly mention 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, openWorldHint, idempotentHint, and destructiveHint false. Description adds critical context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed lists timed-out sources. No contradiction with annotations.

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

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

Description is dense but well-structured. First sentence gives core purpose, then details sources, use cases, ecosystem limits, and behavior notes. Slightly long but every sentence adds value. Good front-loading.

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

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

No output schema exists, so description must explain return values fully. It does: summary block (properties listed), per-advisory detail, links, and alternative versions. Also covers error handling (partial failures) and timing considerations. Very complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. Description adds little beyond schema for parameters, but mentions version-dependent behavior (bundlephobia delay on new versions). No additional semantic enrichment needed.

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

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

The description clearly states it performs a composite check for npm packages using deps.dev and bundlephobia, answering 'should I add this package'. It specifies the verb 'scan' and resource 'dependency', and distinguishes from unrelated sibling tools.

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

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

Explicit usage guidance: 'Use whenever an agent asks is X safe / popular / small or what does adding lodash cost me'. Also clarifies ecosystem scope: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing alternative for other ecosystems.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no behavioral context beyond these annotations, such as pagination, rate limits, or result truncation.

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 short phrase, lacking substance. Conciseness is valued but not at the expense of informativeness.

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 and an output schema, the description is drastically incomplete. It provides no information about what is searched, how results are returned, or how to use parameters effectively.

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

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

Schema description coverage is 0%, but the description does not explain any of the 4 parameters (count, query, start, filter_format). Examples in the schema are not part of the 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 'GOV.UK full search' is vague. It names the resource (GOV.UK) and action (search) but does not specify the scope or differentiate from siblings like search_autocomplete or search_within.

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

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

No guidance on when to use this tool vs alternatives. No mention of context, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds no behavioral context beyond these, such as response format, rate limits, or side effects. With no additional value, the score is low.

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 short (3 words) but under-informative; it sacrifices substance for brevity. Every sentence should add value, but here the single sentence barely repeats the tool name.

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 an output schema, the description omits context about usage, such as expected input format, whether results are limited, or how autocomplete differs from search. The tool is simple, but the description barely covers its purpose.

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 0%, and the sole parameter 'query' is only typed as string. The description does not explain what the query represents (e.g., a partial search term) or any constraints, failing to compensate for the lacking schema detail.

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

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

The description 'Autocomplete suggestions' vaguely indicates the tool's function but lacks specificity about what is being autocompleted (e.g., search queries, entities). It distinguishes from siblings like 'search' only by naming the feature, offering minimal clarity.

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

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

No guidance on when to use this tool versus alternatives like 'search' or 'search_within'. The description does not provide context, exclusions, or prerequisites, leaving the agent without decision support.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char limit with truncation flags, and character offsets for verification. 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 (4-5 sentences) and well-structured: it starts with the core purpose, gives concrete examples, explains usage context with the sibling, then adds technical implementation details. No redundant 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?

Despite having no output schema, the description fully explains what is returned (top-N passages with offsets and similarity scores) and covers technical details (embeddings, window size, character limit). It also explains how to pair with a sibling tool, making it complete for a tool with 3 parameters.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides example queries for the 'query' parameter but adds little new meaning beyond what the schema already provides. The 'text' and 'limit' parameters are adequately described in schema; description reinforces the cap but does not add novel information.

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 search_within performs semantic search inside a fetched record, using examples like SEC 10-K body and articles. It distinguishes itself from sibling tool ask_pipeworx_grounded by stating that the two pair together: fetch with gateway, ground over relevant passages.

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

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

The description explicitly advises using the tool when the record is too large for the prompt, saving context by returning only relevant passages. It also notes the 200K character cap and mentions pairing with ask_pipeworx_grounded for grounding, providing clear when-to-use guidance.

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

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

The description implies non-idempotent creation ('Returns the new subscription id') contradicting the annotation idempotentHint=true. According to rules, description contradicts annotations, so score is 1.

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

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

Well-structured with front-loaded purpose, then requirements, types, and delivery. Though lengthy, each sentence adds value and the organization aids 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?

Comprehensively covers prerequisites, multiple subscription types, parameter formats, delivery channels with limitations, and return value. No output schema, but return value is described. Leaves no major gaps for a complex tool.

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

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

Schema coverage is 100%, but description adds significant value with type-specific examples (e.g., items:['5.02']), delivery channel details, and constraints, exceeding the baseline of 3.

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

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

The description clearly states the tool's verb ('Create a proactive monitoring subscription') and resource ('live-data event stream') and distinguishes it from sibling tools like list_subscriptions and unsubscribe by focusing on creation and returning a new subscription 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?

Provides explicit prerequisites (Pipeworx OAuth account, phone verification), supported types with examples, and delivery channel constraints. However, it does not explicitly contrast with sibling tools for when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable context beyond these: it explains the tool returns 'the exact tool + argument shape that answers each question' and is drawn from a live catalog, which informs the agent about the richness and dynamism of the output. No contradictions with annotations.

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

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

The description is relatively long but front-loaded with common user phrases. Every sentence contributes useful information, though some redundancy exists (e.g., the list of categories is repeated in the description and in the parameter options). A slightly tighter structure could improve scannability.

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

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

For a simple tool with one optional parameter and no output schema, the description is remarkably complete. It covers purpose, when to use it, what the output contains (category-bucketed examples with tool and argument shapes), how to focus the query, and sets expectations about the live catalog. Nothing essential is missing.

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 'topic'. The description adds substantial meaning: it lists the exact allowed topics as examples ('finance', 'pharma', etc.) and explains the default behavior when omitted ('full spread'). This goes well beyond the schema's generic description 'Optional focus area'.

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 returns 'category-bucketed example questions' about Pipeworx's capabilities, positioning it as the onboarding entry point. The list of user intents ('what can I ask', 'show me examples', etc.) and the full catalog of categories make the purpose unmistakably clear and distinct from sibling tools.

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

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

The description clearly 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,' providing strong when-to-use guidance. However, it does not explicitly state when not to use it (e.g., if you already know what to ask, skip this tool), so it loses a point for lacking exclusion criteria.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds specific return fields and default behavior but does not go beyond what annotations already convey in terms of safety.

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

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

The description is a single, well-structured sentence that front-loads the action and default, then lists return values. Every word adds value.

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

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

Given the tool's simplicity (one optional parameter, clear annotations, output schema present), the description is complete and covers all necessary aspects.

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 0%, so the description carries the full burden. It explains the parameter 'base_path' and its default value, adding meaning beyond the schema's type-only definition.

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 fetches a GOV.UK taxonomy tree node by base_path, with default to root, and lists the returned fields. It is specific and distinguishes from sibling tools like 'content' or 'search'.

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

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

The description implies usage for fetching taxonomy nodes but provides no explicit guidance on when to use this vs alternatives, nor when not to use it.

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

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

Adds beyond annotations: ownership enforced, deactivation not deletion, and persistence of historical events. No contradiction with annotations (readOnlyHint=false, destructiveHint=false).

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

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

Two concise sentences. Front-loaded with main action; 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 simple tool (1 param, no output schema), description covers purpose, ownership, side effects, and links to recent_alerts for historical data.

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

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

Schema already describes 'id' fully. Description adds 'by id' but no new meaning beyond schema. Baseline 3 due to high 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?

Clear verb 'Cancel' and resource 'subscription'. Distinguishes from sibling 'subscribe' and notes ownership enforcement.

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?

States context for cancellation and mentions historical data availability via recent_alerts, but does not explicitly contrast with other tools like list_subscriptions for finding IDs.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds: it returns a verdict, actual value with citation, and reasoning. It explains the dual pipeline (structured vs grounded), which goes beyond annotations.

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

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

The description is informative but somewhat lengthy, with multiple sentences including examples and pipeline details. It is front-loaded with query patterns, but could be more concise while retaining essential info.

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

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

Given no output schema, the description explains the return shape: verdict, actual value with citation, reasoning. For a tool with 2 parameters and clear purpose, this provides sufficient context for an agent to understand and invoke it correctly.

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

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

Both parameters are described in the schema with 100% coverage. The description adds context: tolerance_pct overrides implied wording default, capped at 5. Examples for claim are given. This enriches understanding beyond the schema.

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

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

The description clearly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes its two paths (structured SEC for financials, grounded pipeline for others). However, it could more explicitly differentiate from sibling tools like ask_pipeworx_grounded or deep_research, which might also handle factual queries.

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 whenever the agent needs to check whether something a user said is factually correct.' Also describes when the structured vs grounded path applies. No explicit 'when not to use' or alternatives, but the guidance is clear enough.

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