Uk Gazette

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by disclosing cost implications (free model vs. BYO Anthropic key), that it returns per-model data including score, confidence, signals, and raw_response, and that it's a read-only probe. 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 a single, well-structured paragraph. It front-loads the main purpose (probe LLMs, score visibility), then adds usage details (default model, BYO key) and output format. No redundant sentences; every sentence adds value.

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

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

Given the moderate complexity (4 parameters, all documented) and no output schema, the description provides sufficient context by explaining the return format (per-model results including score, confidence, signals, raw_response). It covers why you'd use this tool and how the parameters work, making it complete for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: clarifies 'entity' examples, specifies supported models ('workers-ai' and 'anthropic'), explains that '_apiKey' is passed directly to Anthropic, and that 'context' helps disambiguate. This provides useful operational guidance beyond parameter names and 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 probes LLMs for knowledge about an entity and scores visibility (0-100). It specifies a default model (Workers AI Llama-3.3-70b) and optional Anthropic probing. This purpose is distinct from siblings like 'ask_pipeworx' which focus on specific queries rather than visibility scoring.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, and competitive monitoring. It explains when to provide an API key (to also probe Anthropic) and notes the default is free. It does not explicitly state when NOT to use, but the context is clear enough.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds meaningful behavioral context: it routes across 5,501 tools, fills arguments automatically, returns structured answers with pipeworx:// citation URIs, and works on every tier. It also hints at a limitation by implying the grounded variant is more suitable when verbatim evidence and confidence scores are required. This goes well beyond what annotations provide, though it does not disclose potential failure modes or rate limits.

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

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

The description is verbose and repetitive. Key directives like 'PREFER OVER WEB SEARCH' and 'START HERE' are stated multiple times, and marketing phrasing ('works on every tier, one fast call') adds bulk without unique value. It is front-loaded with important information but overlong; it could be cut by half without losing clarity. This is not a concise, tightly written description.

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

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

For a tool with no output schema and high complexity, the description is quite complete: it covers the question domain, source scope, output format (structured answer with citation URIs), and clear alternative escalation paths. It does not explain disambiguation behavior or error handling, but these are secondary for a natural-language query tool. Overall it provides enough context for an agent to invoke it confidently.

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 six parameters are aliases for the same natural-language question field, and each alias has a description. The description adds example queries and clarifies that the input is natural language, but it does not provide new parameter-level meaning beyond the schema. Baseline 3 is appropriate since the schema already documents the parameters thoroughly.

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

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

The description clearly identifies the tool as a natural-language question-answering agent that routes to hundreds of thousands of tools across verified sources and returns cited answers. It distinguishes itself from sibling tools by positioning itself as the default entry point, and explicitly contrasts with ask_pipeworx_grounded and deep_research. The verb 'ask' plus resource scope is 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 is exemplary in usage guidance. It explicitly says 'PREFER OVER WEB SEARCH', lists a broad set of query types and example questions, and then provides clear escalation paths: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded' and 'for a broad/multi-part question... use deep_research'. This gives the agent clear when-to-use, when-not-to-use, and alternative selection 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 readOnly, idempotent, and openWorld. The description adds the behavioral context of experimentation: candidate routing improvements may be active, currently none, so it matches the stable version. It also clarifies the purpose of comparing results against the stable router. 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 three sentences, all dense with information: beta status, identical nature, current state, usage guidance, and experimental purpose. No fluff or redundancy.

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

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

Given the tool's simplicity (one required parameter) and rich annotations, the description covers the beta behavior, usage context, and relationship to the stable router. It references the response shape via 'same response shape' as ask_pipeworx, which suffices without an output schema.

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

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

All six parameters are documented in the schema with 100% coverage, including aliases for the question field. The description doesn't add extra semantic detail beyond saying 'same arguments' as ask_pipeworx, which is helpful but not needed given the schema completeness.

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 identifies it as a beta version of ask_pipeworx, a universal router that handles natural language queries across 5,501 tools. It distinguishes from the stable ask_pipeworx and ask_pipeworx_grounded siblings by emphasizing experimental routing improvements.

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

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

Explicitly states when to use: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the comparison process. It also clarifies that it is a full working router, so no special fallback handling is needed.

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 already indicate readOnlyHint=true and idempotentHint=true, but the description goes further by detailing the success return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and the explicit refusal modes (not_in_source, no_tool_match, etc.). It also discloses the extra LLM call cost. This is beyond annotation coverage and provides clear behavioral expectations. No contradiction with annotations is present.

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 rich but efficiently structured: it opens with a concise definition, explains the process, lists the return format and refusal reasons, then provides context on when to use and the cost. Every sentence provides distinct value, and the information is well-organized and easy to parse.

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

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

Even though there is no output schema, the description fully specifies the return object on success and failure, including refusal reasons. It covers when to use, how it differs from siblings, and the cost tradeoff. This makes the description self-sufficient for an agent to understand the tool's behavior and limitations comprehensively.

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 six parameters (all aliases for the required question) with 100% description coverage, so the baseline is 3. The description does not add parameter-specific semantics, but none are needed since the schema already documents that any alias can be used. The description's focus on answer behavior compensates appropriately.

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

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

The description clearly defines the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains its mechanism: it routes to the appropriate tool, fetches data, and extracts answers using only the tool result. It also distinguishes this tool from its sibling 'ask_pipeworx' by emphasizing the grounding/evidence approach, making its unique 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 usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists example domains (financial verdicts, legal claims, medical lookups, public statements). It also names the alternative ('prefer ask_pipeworx for casual lookups') and notes the cost tradeoff, giving clear criteria for when to use this tool versus the sibling.

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

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

The description goes far beyond annotations by detailing resolution steps, classification fan-out, response structure, safety mechanisms (low-confidence short-circuit, closed market detection, wide spread warnings), and resolution rule risk. No contradiction with annotations; readOnlyHint and idempotentHint are consistent.

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

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

The description is extremely detailed and covers many aspects, but it is overly long and dense, mixing high-level purpose with low-level implementation details like specific data sources and response shapes. While structured, it could be more concise for quick agent comprehension.

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 (resolving, classifying, fanning out, returning evidence), the description is remarkably complete: covers inputs, behavior, output shapes (market, analysis, evidence), resolver contract, parent event extraction, news fallback, and safety edge cases. No output schema, but response shapes are thoroughly documented.

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

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

Schema coverage is 100% with each parameter described. The description enriches the schema by explaining how the 'market' parameter is resolved, the 'depth' parameter's effect (quick vs thorough), and 'include_raw' behavior (summarized vs full payloads). Examples and edge cases add significant meaning.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and distinguishes from sibling tools by focusing on a single bet research, unlike polymarket_arbitrage or 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?

Explicit usage guidance is given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It does not explicitly state when not to use or list alternatives, but the context and sibling names imply this is the primary research tool for individual bets.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years correctly (e.g., AAPL Sep, NVDA Jan), sorts results by primary metric, and returns paired data with citation URIs. This far exceeds what annotations provide.

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

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

The description is front-loaded with the most important trigger queries. Every sentence adds distinct value—entity type behavior, data sources, sorting, output format, and performance comparison. It is appropriately sized for a complex tool, with 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?

Despite having no output schema, the description explains what is returned ('paired data + pipeworx:// citation URIs per entity') and that results are sorted. It covers both entity types, their data sources, and the handling of fiscal years. For a tool of this complexity, the description is complete and self-contained.

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

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

Schema description coverage is 100% (both parameters described). The description enriches the schema: for 'type', it explains exactly what data is pulled (company → 10-K metrics; drug → FAERS, FDA, trials). For 'values', it gives concrete examples (tickers, drug names) and the allowed range (2–5). This adds substantial meaning beyond the raw 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 begins with concrete example queries ('Compare X and Y', 'X vs Y', etc.) and explicitly states the tool does side-by-side comparison of 2–5 companies or drugs. It distinguishes itself from sequential single-pack lookups by saying 'ALWAYS PREFER over sequential single-pack lookups' and explains the specific data sources per entity type, making the purpose highly specific and clear.

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

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

The description gives explicit when-to-use instruction: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It also provides example queries that trigger usage, and contrasts with alternative approaches (sequential lookups). No when-not is needed given the clear domain of comparison.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description discloses auth/account requirements, paid-plan limitations, latency expectations (15-60s up to ~90s), the gaps[]/contradictions[] behaviors, semantic excerpting rather than head-truncation, and that citations are only included when they are fetchable. 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 extremely dense and well-structured. It front-loads the critical account requirement and differentiator, and every subsequent sentence adds unique value (behavior, latency, return format, limitations). It earns its length given the tool's complexity.

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

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

Given the tool's complexity, a rich schema (enums, defaults), and no output schema, the description carries the full burden of explaining return shape (findings packet, gaps[], contradictions[], hop, citation_uri), behavior, limitations, and latency. It covers all necessary context for an agent to select and use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds modest extra meaning by explaining that depth:'standard' re-angles gaps, depth:'thorough' chases leads and requires a paid plan, and that the question can be broad/multi-part. However, most depth semantics are already in the schema, so the added value beyond schema is limited.

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

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

The description clearly states that this tool performs 'grounded multi-source research' across 1,441 structured data sources in one call, and explicitly distinguishes itself from siblings: 'this is NOT open-web search' and 'For a single lookup use ask_pipeworx'. The verb+resource+scope is 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?

It provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' with concrete examples, and when-not-to-use: 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also names alternatives and account requirements, telling unsigned-in users to use ask_pipeworx instead.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true. Description adds beyond: returns top-N relevant tools with names, descriptions, full schemas with curated examples, and that results are ready to call directly. No contradictions.

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

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

Description is front-loaded with purpose and usage. While somewhat long, every sentence adds value (use case, examples, return format). Could be slightly tighter but still effective.

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

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

Fully addresses when to use, what it returns, and provides examples. Despite lacking output schema, the description clearly states the return structure (names, descriptions, schemas, examples) and that results are callable, making it complete for this discovery tool.

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

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

Schema coverage 100%; description clarifies the main 'query' parameter accepts natural language and lists all aliases (task, q, search, description). Also documents default and max for 'limit'. Adds value beyond schema.

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

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

Clear verb 'Find tools' with specific resource ('tools by describing the data or task'). Lists many example domains (SEC filings, FDA drugs, etc.) and explicitly distinguishes from siblings by being the discovery tool.

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

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

Explicitly states 'Call this FIRST when you have many tools available and want to see the option set', providing clear when-to-use guidance. Implies alternatives by offering to return tools ready to call.

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, openWorldHint, and idempotentHint. The description adds value by detailing the data sources (SEC, XBRL, USPTO, news, GLEIF), the soft-fail for patents, and the return fields, which goes beyond what annotations provide.

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

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

The description is dense with information but well-structured, starting with examples, then core functionality, followed by return details and caveats. Every sentence adds value, though it could be slightly more concise.

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

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

Given the complexity and absence of an output schema, the description thoroughly explains all return components (CIK, filings, fundamentals, patents, news, LEI) and limitations (patent sunset, name requirement). It provides a complete picture for the agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds useful examples (e.g., 'AAPL', '0000320193') and reiterates that names are not supported, which enhances understanding beyond the schema alone.

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

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

The description clearly states the tool provides a 'full cross-source profile of a US public company' with example queries like 'Tell me about X' and distinguishes it from chaining individual lookups.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and advises using resolve_entity if only a name is available, providing clear context for when to use this tool versus alternatives.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and is consistent with 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 concise sentences. First states purpose immediately; second provides usage context. 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?

Simple delete tool with 1 param and annotations. Description covers purpose, usage context, and pairing. Fully adequate for correct tool selection.

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

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

Schema coverage is 100% with parameter description 'Memory key to delete'. Description only adds 'by key' which restates schema. Minimal extra value beyond schema.

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

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

Description explicitly states 'Delete a previously stored memory by key' with a specific verb, resource, and method. It distinguishes from siblings 'remember' (store) and 'recall' (read).

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

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

Provides clear context: 'Use when context is stale, the task is done, or you want to clear sensitive data...' and suggests pairing with 'remember and recall', guiding when and 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, destructiveHint. The description adds context about the legal notice type and claim deadlines, which aligns with annotations. No contradictions.

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

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

Two concise sentences plus an example call. Every sentence adds value, front-loaded with purpose and use cases. 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 search tool with 9 parameters and no output schema, the description explains the legal context and use cases sufficiently. It covers what the tool does and why it's useful, though it could briefly mention the return format.

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

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

Schema coverage is 100%, so the schema documents all parameters. The description does not add extra semantics beyond the schema's field descriptions; it only provides example usage. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool searches UK deceased-estates notices under Trustee Act 1925 s.27, and lists specific use cases like probate research and tracing an estate. It distinguishes itself from sibling tools (e.g., gazette_insolvency_notices) by focusing on deceased estates.

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

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

The description specifies the tool is used for probate research, tracing an estate, checking death notices, and finding claim deadlines. It provides clear context, though it does not explicitly mention when not to use it or call out alternative 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?

Annotations already indicate readOnly, idempotent, and non-destructive behavior. The description adds value by listing the detailed fields returned (notice type, publication date, companies, etc.), which goes beyond 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, well-structured paragraph with no wasted words. Key information is front-loaded, and the example is included efficiently.

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

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

Despite lacking an output schema, the description lists all major return fields sufficiently for a simple retrieval tool. Combined with annotations, it provides complete guidance for 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% with a clear description of notice_id. The description reinforces the parameter meaning with two example values and explains the numeric/legacy format, adding practical context 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 retrieves a structured record for one Gazette notice by ID, with specific verb 'Get' and resource 'Gazette notice'. It distinguishes from sibling search tools by requiring an existing ID.

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

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

The description explains when to use: when you have a notice ID from a search or URL. It provides an example invocation. It does not explicitly state when not to use, but the context implies prior search is needed.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds context about the statutory nature of the data and indexing, but does not add behavioral traits beyond what annotations provide. No contradiction.

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

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

Three sentences plus an example, all front-loaded with the most critical information. No unnecessary words. The example helps illustrate usage. Efficient and clear.

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

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

Given 7 parameters with full schema descriptions and comprehensive annotations, the description covers use cases, example, and search strategies. No output schema exists, but the rules state description needn't explain return values. Complete for effective agent usage.

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

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

All 7 parameters are documented in the schema. The description adds value by explaining that 'company' accepts both names and Companies House numbers (both indexed), and that 'scope' narrows to corporate or personal insolvency, enhancing the schema descriptions.

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

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

The description clearly states it searches official UK insolvency notices in The Gazette, listing specific notice types and providing example usage. It distinguishes from sibling tools like gazette_deceased_estates and gazette_get_notice by its specific focus on insolvency.

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

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

Provides explicit use cases ('go-to source for checking company liquidation/administration, monitoring distress, tracking personal bankruptcies') and search strategies (by name or Companies House number). Lacks explicit when-not-to-use guidance but implies context through scope parameter.

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 minimal behavioral context beyond being a browser and optionally filtering. It is consistent but does not provide significant new behavioral details.

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

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

The description is two sentences plus an example, front-loaded with purpose, and contains no wasted words. Every sentence adds value.

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

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

For a simple category listing tool, the description adequately explains what categories cover and how to filter. It provides enough context despite no output schema. Could mention return format, but not critical.

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

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

Schema coverage is 100%, so the schema already documents the search parameter. The description adds context by giving examples and stating it filters category names, but this does not substantially exceed the schema's description.

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

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

The description clearly states the tool browses The Gazette's notice-category taxonomy and specifically notes it provides codes accepted by gazette_search_notices. It distinguishes from siblings by listing category examples and giving an example call with a filter parameter.

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 use before gazette_search_notices to obtain valid category codes. It mentions optional filtering but does not explicitly state when not to use or name alternatives. Still, the context is clear enough for an agent.

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

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

Annotations indicate the tool is read-only, idempotent, and non-destructive. The description adds behavioral details about full-text search, filters, and the scope of notices covered, which 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 a single, concise paragraph that front-loads the main purpose and efficiently covers key features, examples, and usage suggestions 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?

For a search tool with 11 parameters and no output schema, the description adequately covers the input purpose and parameters. It could be improved by briefly describing the expected output format, but overall it provides sufficient context for an AI agent.

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

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

Schema coverage is 100%, so the description does not need to repeat parameter details. It adds value by providing an example call and explaining the category types, but this is minimal additional semantic context.

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

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

The description clearly states the tool searches The Gazette, the UK's official public record of statutory notices, covering multiple editions and a wide range of notice types. It distinguishes itself from sibling tools like gazette_deceased_estates and gazette_insolvency_notices by being a general search tool.

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

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

The description provides specific use cases such as 'official UK notices about X' and 'gazette notices for company Y', and gives an example query. However, it does not explicitly state when not to use this tool versus its more specialized siblings.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint false. Description adds that it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', clarifying it is a read-only operation with no side effects. No contradiction found.

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

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

The description is concise (~70 words), front-loaded with the primary action, and structured with a bullet list of use cases. Every sentence serves a purpose with no redundancy.

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

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

For a simple tool with 2 parameters and no output schema, the description covers core functionality, use cases, and output format. It could mention error handling (e.g., invalid URL) but overall is sufficiently complete.

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

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

Schema coverage is 100% with 2 parameters. The description mentions 'for any URL' implying the url parameter but does not explain max_links beyond schema. While baseline is 3 due to full schema coverage, no additional meaning is added, so score remains 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 generates a production-ready llms.txt file for AI crawlers, with specific verb 'generate' and resource 'llms.txt'. It differentiates from sibling tools like scan_competitor_ai_presence and ai_visibility_check by focusing on the output file format.

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

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

The description explicitly lists use cases: getting client's site indexed, drafting llms.txt, or auditing competitor visibility. It provides clear context but does not include when not to use it or alternatives, which would elevate to a 5.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint, openWorldHint. Description adds return fields and default behavior (active subscriptions), which adds some context but not significant beyond annotations.

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

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

Two concise sentences: first states purpose and return fields, second provides usage guidance. No extraneous text, front-loaded with key 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?

Lists return fields, clarifies default scope, and covers usage. Though no output schema, the description compensates adequately. Slightly lacking on pagination info, but tool is simple.

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

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

100% schema coverage for the single parameter. Description does not elaborate on the parameter beyond what schema provides, so baseline score applies.

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 verb 'List', resource 'subscriptions', and scope 'caller's active', with specific return fields. This distinguishes it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more' and 'find an id to cancel'. Provides clear context, though does not mention 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 provide no safety hints (all false), so the description carries full responsibility. It discloses rate limiting (5 per identifier per day), that it is free and doesn't count against quota, the claim_token flow for anonymous filing, that digests are read daily, and that signals affect roadmap. This is rich behavioral disclosure beyond annotations.

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

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

Though the description is longer than average, every sentence earns its place: purpose, usage triggers, exclusions, framing guidance, claim_token mechanics, team process, rate limits, and cost. It is front-loaded with the core purpose and structured logically. No fluff or redundancy.

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

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

Given the tool has 4 parameters (0 required), nested object properties, no output schema, and relatively involved follow-up behavior, the description covers all necessary ground: what feedback types exist, how to frame messages, what happens without an account, how to check resolution status, rate limits, and scope boundaries. It leaves no critical gap for an agent deciding whether to use this 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 meaningful context beyond schema: it instructs users to describe issues in terms of Pipeworx tools/packs rather than pasting end-user prompts, and explains how to use claim_token for follow-up ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'). This significantly enhances parameter semantics.

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

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

The description opens with a clear statement: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb, resource, and scope, and clearly differentiates from sibling tools like ask_pipeworx (which queries information) and discover_tools (which lists tools). The supported feedback types (bug, feature, data_gap, praise) add further precision.

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 for each feedback type ('Use when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well'). It also gives a clear exclusion: tools from other MCP servers should be reported elsewhere, and advises how to identify Pipeworx tools. This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context: caching ('Cached 5min-1h depending on window'), data source ('CF analytics-engine'), and privacy ('no PII'). This exceeds what annotations provide.

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

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

The description is concise: two sentences plus a bullet list, front-loaded with the main purpose. Every sentence adds value without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description provides everything needed: what is returned (top tools, top packs, total call volume), caching, use cases, and data source. It is complete.

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

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

Schema coverage is 100% and the description adds meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose the window value. Could mention the default (24h) explicitly, but still helpful.

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: 'What other AI agents are calling on Pipeworx right now. Returns the top tools, top packs, and total call volume over a recent window.' It specifies the verb ('Returns') and resource (top tools, packs, call volume), distinguishing it from sibling tools like 'discover_tools' or 'scan_competitor_ai_presence'.

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 three specific use cases: discovering hot data sources, confirming canonical tool choice, and checking use case alignment. While it does not explicitly state when not to use, the context is clear and sufficient for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds rich behavioral context: the scanning process, Jaccard similarity filter, partition placeholder filter, and fill check with book depth. It warns about realizable_edge_pp <= 0 indicating non-tradable overround. 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 lengthy but well-structured with clear sections for each mode. Every sentence adds value, and key information is front-loaded. Could be slightly more concise, but effective.

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

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

Given no output schema, the description fully explains the response structure (opportunities[], partition_check, fill check). It covers inputs, behavior, edge cases (placeholder filtering, similarity threshold), and caveats (do not trade if book edge poor). Complete for a complex arbitrage tool.

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

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

Schema description coverage is 100%, so baseline 3. The description adds value by explaining the difference between event and topic parameters, giving example slugs and seed questions, and clarifying cross-event semantics. This raises it to 4.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending scan, event-specific, cross-event topic), making the purpose specific and differentiating it from sibling tools like polymarket_edges.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for a specific market, topic for cross-event scanning. It explains trade-offs (cross-event catches patterns single-event misses) and provides concrete examples, satisfying when-to-use and 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, idempotentHint, and destructiveHint false, so the tool is safe and non-destructive. The description adds valuable behavior details: caching at KV level for 1 hour keyed on knobs, explanation of diagnostic output (funnel counters, filter_skips), and the Fed market exclusion note. 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 well-structured with clear sections (segments, knobs, response fields). Every sentence adds value, though it could be slightly more concise without losing detail. Still highly functional for an AI agent.

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

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

Given the tool's complexity (three segments, multiple knobs, diagnostics, caching) and lack of output schema, the description thoroughly covers input, internal logic, output structure, and edge cases (e.g., Fed markets excluded from ranking). It is complete and leaves no significant gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning beyond the schema, such as explaining how min_partition_leg_kelly works specifically for partition arb legs and clarifying the tradeable-edge knobs' impact on realizing edge.

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

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

The description clearly states the tool scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, providing a specific verb+resource and distinguishing it from similar tools like polymarket_arbitrage and polymarket_edge_tracker.

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 targets 'what should I bet on today' and explains the three opportunity segments (model-driven, structural arbitrage, concentrated longshot) with details on when to use tradeable-edge knobs like min_liquidity and max_spread_pp. While it doesn't compare directly to siblings, it provides strong usage context.

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

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

Annotations declare readOnlyHint true and idempotentHint true. The description adds substantial context: snapshot gaps, TTL limits, decay computation (daily closes, not intraday), and explains that expired opportunities are those missing from the latest snapshot. 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 relatively long but well-structured: first a concise question-answer, then args, then response fields in bullet-like style. Every sentence adds value, though some could be trimmed without losing meaning.

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 (time-series, multiple arrays, decay trends) and no output schema, the description is remarkably complete. It explains each response field (tracked, expired, snapshot_dates), limitations (60-day TTL, intraday not included), and edge cases (gaps in snapshots).

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

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

Schema coverage is 100%, but the description adds meaning: defaults (14 days, '1wk'), maximum (30 days), and clarifies that snapshots are written on cache-miss. The response structure is also detailed, helping the agent understand parameter effects.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes itself from sibling tools like polymarket_edges by focusing on historical persistence vs. current edges, using the specific metaphor of a fresh wide edge vs. a 3-week-old edge.

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 implicitly guides when to use the tool: when analyzing edge persistence over time. It contrasts with sibling tools by explaining the difference between fresh and old edges, but does not explicitly state when not to use it or name 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 indicate readOnlyHint=true and idempotentHint=true, so the tool is safe and non-mutative. The description adds valuable behavioral details: it walks the ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and explains the dominant loss mode. 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 long but well-structured with clear sections for single-market and basket modes. It front-loads the purpose and uses capitalization for emphasis. Every sentence provides necessary detail; however, it could be slightly more concise without losing clarity.

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

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

Given the complexity of the tool (two modes, no output schema), the description covers all necessary details: return fields for both modes, default behaviors, edge cases like thin legs and forced directional risk. It fully prepares the agent to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds meaning beyond the schema: it explains how size_usd is interpreted differently in single-market (spend or target proceeds) vs basket (settlement notional), and that side defaults to auto in basket mode. This additional context is valuable.

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 distinguishes between single-market and basket modes with specific details. It uses specific verbs and resources, differentiating it 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 tells 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 also explains when not to use it implicitly by warning about partial basket fills converting arb into unhedged directional positions, providing strong 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?

Beyond annotations (readOnly, idempotent, openWorld), the description adds rich behavioral context: compatibility warning scenarios, temporal alignment checks, skipped cross-type/subtype counters, and the note that real spreads are rarer than shortcuts suggest. No contradictions with annotations.

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

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

The description is lengthy but well-structured with sections for modes, response, safety fields, and warnings. Every sentence adds value, though minor redundancy exists (e.g., explaining pre-mapped topics twice). Still, it remains concise for the complexity covered.

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 (cross-venue matching, safety checks, temporal alignment) and the absence of an output schema, the description compensates thoroughly. It explains key response fields (top_spreads_pp), compatibility warnings, and temporal constraints, making the tool usable without additional documentation.

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

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

All 3 parameters are fully described in the schema (100% coverage). The description adds value by explaining the two operational modes and providing concrete examples like 'fed' and 'btc'. Schema descriptions are sufficient but the tool description reinforces usage context.

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

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

The description clearly defines the tool as a cross-venue spread calculator between Kalshi and Polymarket for the same resolving question. It specifies two modes (topic shortcuts and explicit tickers) and distinguishes itself from siblings like polymarket_arbitrage by focusing on spread analysis.

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

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

The description provides clear when-to-use guidance (spread analysis for same questions) and includes important caveats (compatibility warnings, temporal alignment). It lacks explicit mention of alternative tools but the context makes the tool's niche 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 read-only and idempotent behavior. Description adds context on scoping, listing, and pairing with related tools, with 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?

Description is efficient and front-loaded with main action. Slightly dense but concise; no extraneous 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 one optional parameter, no output schema, and clear annotations, the description provides sufficient context on usage, scope, and related tools. Complete for this complexity level.

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

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

Schema coverage is 100% with a description for the key parameter. The description adds context about omitting the key for listing, but no additional details 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 purpose: retrieving a value saved via remember or listing all keys. It distinguishes itself from sibling tools like remember and forget.

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

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

Explicitly states when to use (look up context without re-deriving) and mentions alternatives (remember, forget). Provides context on scoping and behavior when key is omitted.

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

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

Description contradicts annotation readOnlyHint=true by stating mark_read:true flags events as read, which modifies state. This is a serious contradiction. Otherwise, description does add context about mark_read behavior but fails to align with annotations.

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

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

Three sentences with front-loaded purpose. Every sentence adds value. No redundancy. Example usage integrated naturally.

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?

Returns fields are described (source, citation_uri, payload). Filtering and side effect explained. No output schema, but return fields are sufficient. Missing mention of unread_only and limit, but schema covers them. Overall good for a 5-param tool with rich annotations.

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

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

Schema coverage is 100%, so baseline 3. Description adds value by providing an example for type ('sec_8k'), explaining mark_read behavior, and specifying since as ISO timestamp. Adds useful context beyond schema, though unread_only is not mentioned.

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 starts with 'Pull fired events from your subscription feed,' clearly stating the verb and resource. It specifies it returns recent alerts with details on fields. It distinguishes from siblings like 'recent_changes' and 'list_subscriptions' by focusing on alert events.

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

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

No explicit guidance on when to use this tool vs alternatives. It mentions an alternative endpoint but not tool siblings. No when-not or comparative context.

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

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

Annotations already indicate read-only, idempotent, non-destructive, and open-world. The description adds valuable behavioral details: parallel fan-out to multiple sources, GDELT→GNews fallback on rate limit/5xx, USPTO soft-fail due to sunset, and return structure (grouped changes, total count, citation URIs). No contradiction.

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

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

The description is not purely concise—it includes many query examples and details—but every sentence adds value. It front-loads common use cases, making it easy for an agent to understand quickly. Slightly longer than necessary but well-structured.

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

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

Given the tool's complexity (multiple data sources, fallback, soft-fail) and the absence of an output schema, the description is remarkably complete. It covers parameter syntax, data source behavior, and return format, leaving no ambiguity 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 descriptions cover 100% of parameters with clear explanations. The description adds extra value by providing relative shorthand examples for 'since' (e.g., '7d', '30d', '1y') and a typical usage note ('Use "30d" or "1m" for typical monitoring'). While schema already does well, the description enriches understanding.

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

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

The description clearly defines the tool as a change feed for companies over a time window, aggregating from SEC EDGAR, GDELT/GNews, and USPTO. It explicitly distinguishes itself from the sibling tool 'entity_profile' 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 concrete query examples (e.g., 'What's new with X') and directly tells the agent to use 'entity_profile' when a static profile is needed instead of recent changes.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds important context: memory scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. 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?

Three sentences, front-loaded with purpose, no wasted words. Efficient and well-structured.

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

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

No output schema, but description covers persistence, scope, and pairing. Could mention overwrite behavior, but idempotent hint implies upsert. Still highly complete.

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

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

Schema has 100% description coverage, so baseline is 3. Description adds examples but no additional meaning beyond schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from sibling tools recall and forget 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?

The description explicitly says when to use ('when you discover something worth carrying forward') and pairs with recall and forget. It also clarifies scoping and persistence duration.

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

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

Beyond the read-only and idempotent annotations, the description discloses internal cascading across lookup endpoints, specific return fields (ticker, CIK, RxCUI, citation URIs), and auto-disambiguation behavior. This adds meaningful context not inferable from schema or annotations alone.

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

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

The description is well-structured and front-loaded: it opens with relatable user queries, states the action, then breaks down supported types with clear outputs. It is detailed yet every sentence earns its place, with no redundancy or unnecessary fluff.

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

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

Given the tool's simplicity, full schema, and strong annotations, the description is complete: it covers purpose, usage timing, input types, output contents, and internal behavior. It lacks only explicit error/edge-case handling, but that is not essential for a resolve tool of this 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?

The schema already documents both parameters with full coverage, but the description enriches semantics by explaining that 'company' accepts ticker/CIK/name with auto-disambiguation and 'drug' accepts brand or generic names with examples. This goes beyond the schema's terse descriptions.

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

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

The description explicitly states the tool resolves user-spoken names to canonical identifiers, with concrete examples (ticker, CIK, RxCUI) and a clear action verb ('resolve'). It positions itself as the first step when an ID is needed, distinguishing it from sibling tools like entity_profile or compare_entities that serve different purposes.

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: 'Use FIRST whenever you have a name but need an ID.' It also details supported entity types (company, drug) and accepted input formats, giving clear context for when to use. However, it does not explicitly name alternatives or exclusion cases, stopping short of a 5.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral detail: it probes each entity using ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. It also notes the first entity is treated as the subject, which is helpful for narrative interpretation.

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

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

The description is three sentences with no wasted words. It front-loads the core purpose in the first sentence, then provides process details and an example. Every sentence contributes meaning.

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

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

Although there is no output schema, the description explains the return format (ranked list with score, confidence, signal density). It also covers the process and use case. However, it could briefly mention that the models and _apiKey parameters are optional for advanced use, which would make it more complete for agents needing to decide on those inputs.

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 all parameters are documented in the schema. The description does not add additional parameter-level details beyond what is in the schema, so it meets the baseline but provides no extra value.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, ranks by score, and identifies most/least recognized. It provides a specific use case example ('does Claude know about us as well as our competitors?'), effectively distinguishing it from the sibling tool ai_visibility_check which checks a single entity.

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

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

The description explicitly states it is useful for competitive AI-marketing audits, providing clear context. It does not explicitly exclude alternatives or state when not to use it, but the sibling list implicitly offers alternative single-entity checks. The given example suggests a clear 'when-to-use' scenario.

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, openWorldHint, and destructiveHint false. The description adds valuable behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds, and sources_failed will list any timeout.

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

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

The description is longer than typical but well-structured: it front-loads the core purpose, then details the return format, constraints, and failure behavior. Every sentence adds value, though slightly verbose.

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

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

Despite having no output schema, the description fully explains the return format (summary block, per-advisory detail, links, alternative versions) and handles edge cases (partial failures, timeout behavior). Highly informative for a composite 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 the schema already explains both parameters. The description adds marginal value by explicitly noting that scoped packages are accepted for the 'package' parameter, which goes beyond the schema's basic 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 uses a specific verb structure ('composite check') and clearly identifies the resource (npm package) via two external APIs. It distinguishes from siblings by noting that other ecosystems (PyPI, Maven, etc.) fall under a different tool (deps.dev:version).

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 criteria are provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states NPM-only in v1 and directs to an 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?

Discloses embedding model, window size, similarity metric, input cap (200K chars), truncation behavior, and that passages include offsets. Annotations already indicate read-only, idempotent, etc., and description adds rich behavioral detail 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?

Extremely concise: four sentences that cover purpose, use case, pairing, and technical details. Every sentence adds value with zero filler.

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

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

For a tool with no output schema, the description explains return structure (passages, offsets, scores) and behavior (truncation). All parameters are covered, and the cap is flagged. Completes the picture well.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value with query examples and explains why text parameter has max chars. Offsets and similarity scores are mentioned but not fully detailed for return value.

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

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

Description clearly states 'Semantic search INSIDE a fetched record' with specific verbs: pass text + query, get back top-N passages with offsets and scores. It distinguishes from sibling 'ask_pipeworx_grounded' by explaining pairing.

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

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

Explicitly tells when to use ('record too big to cram into prompt') and pairs with a sibling tool for grounding. Does not explicitly state when NOT to use, but context is clear.

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

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

The description provides significant behavioral details beyond annotations, such as authentication requirements, type-specific parameters, delivery constraints (SMS daily cap, webhook auto-disable), and the one-time return of webhook signing secret. Annotations (e.g., idempotentHint=true) are not contradicted.

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

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

The description is well-structured, starting with core purpose, then prerequisites, type details, and delivery options. While dense, every sentence adds value; however, it could be slightly more concise.

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

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

Given the tool's complexity (multiple types, nested params, delivery channels) and no output schema, the description covers essential aspects: return value, auth, type-specifics, and delivery constraints. A minor gap is the feed channel reference (points to siblings) but overall complete.

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

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

Schema coverage is 100%, and the description adds substantial value by explaining each parameter's usage with examples, constraints, and context (e.g., phone verification, email pattern, webhook signing). This goes well beyond the schema definitions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the new subscription ID. It uses a specific verb-resource combination and distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

The description explains when to use the tool (creating subscriptions) and details prerequisites (Pipeworx OAuth account, no anonymous/BYO). It covers supported types and delivery channels but does not explicitly mention when not to use or compare directly to siblings.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds context that results are drawn from a live catalog and include exact tool+argument shapes, which is valuable beyond annotations. No contradictions.

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

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

The description is comprehensive but somewhat long. It uses parenthetical examples and clear structure, but could be slightly more concise without losing clarity.

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

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

Given no output schema, the description adequately explains what the tool returns (category-bucketed questions with tool+argument shapes). It covers the optional parameter and provides sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100% for the single optional parameter 'topic'. The description adds value by listing example topic values (finance, pharma, etc.) and explaining the effect of omitting vs. providing a topic, though it doesn't enumerate all possible values.

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: returning category-bucketed example questions with tool+argument shapes. It also positions it as the onboarding entry point, distinguishing it from siblings like ask_pipeworx and discover_tools.

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

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

The description clearly states when to use this tool first ('Use this FIRST when you do not yet know what Pipeworx can do for you') and when to pass the optional topic parameter. It does not explicitly mention when not to use it, but the guidance is strong.

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

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

Discloses mutation behavior (deactivated, not deleted) and links to historical availability via recent_alerts, adding value beyond annotations.

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

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

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

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

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

Complete for a single-param mutation tool with annotations and clear behavioral notes.

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 parameter fully; description adds context that id comes from subscribe, but no extra syntax or format details 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?

Clearly states 'Cancel a subscription by id' with specific verb and resource, and distinguishes from siblings like subscribe and list_subscriptions.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding proper usage, though no explicit alternatives listed.

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. The description adds significant behavioral context: how company-financial vs other claims are handled, the use of exact math for financials, and what the return includes (verdict, value, citation, reasoning). No contradiction.

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

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

The description is moderately long but front-loaded with examples and clear purpose. Each sentence adds information; however, it could be slightly more concise. Still well-structured.

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

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

No output schema exists, but the description fully explains the return (verdict, actual value with citation, reasoning). It covers both pipelines, parameter behavior, and use cases, making it complete for a complex verification tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining tolerance_pct overrides implied tolerance and its use for hallucination detection, and reinforces that claim is natural language. 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 uses specific verbs and resources: 'natural-language claim verification against authoritative sources.' It provides example queries and clearly distinguishes two pipelines (SEC/XBRL vs grounded pipeline), making the tool's purpose unmistakable.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies when not to use (e.g., for non-factual queries) but does not directly compare with sibling tools like deep_research or ask_pipeworx.

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