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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses key runtime behavior: it is an orchestrator that routes to other tools, fills arguments automatically, and returns stable pipeworx:// citation URIs. It also notes that it works even where web search would also answer, and contrasts the grounded variant's stricter citation behavior. 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 front-loaded with the core directive and organized into purpose, examples, and fallback guidance. There is some redundancy around web-search comparison, but every section earns its place in helping an agent select and invoke the tool.

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

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

For a complex router tool with no output schema, the description is unusually complete: it covers input scope, examples, output format (structured answer with citation URIs), and sibling routing. It does not mention failure/error behavior or rate limits, but those are less critical given the rich annotations and the explicit fallback to web search.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces that the parameter is a natural-language question through examples, but adds no new parameter-level meaning beyond the schema's alias explanation. Baseline 3 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?

The description states a specific verb and resource: it routes a natural-language question to one of 5,743 tools across 1,500 verified sources, fills arguments, and returns a structured answer with citation URIs. It clearly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by naming them as alternatives.

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 guidance: prefer over web search for factual/current/historical data, and lists triggered phrases ('what is', 'look up', 'find', 'current', etc.) plus concrete examples. It also states exclusions: use web search for non-factual or creative questions, deep_research/bet_research for multi-step analysis, and ask_pipeworx_grounded when verification with explicit citations 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 description goes well beyond the read-only/idempotent annotations by disclosing that candidate routing improvements may be live, that none are currently active, and that it is a fully functional router with no fallback. The phrase 'Falls back to nothing' is particularly valuable for setting agent expectations about behavior.

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

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

The description is dense and slightly repetitive around 'identical router' and 'currently matches ask_pipeworx exactly', but every sentence conveys meaningful information. The experimental status is front-loaded, making the most important caveat immediately visible.

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 that this is a simple natural-language router with no output schema, the description covers what the agent needs: current behavior, relationship to siblings, parameter compatibility, and the response-shape equivalence to ask_pipeworx. Nothing critical is missing for correct invocation.

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

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

The input schema documents all six parameters and their aliases with 100% coverage, including the main 'question' field description. The description only adds that arguments are identical to ask_pipeworx, which is useful context but does not substantially improve on the schema. Baseline 3 is appropriate.

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

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

The description clearly identifies this as a beta variant of ask_pipeworx, a universal router that routes natural-language queries to 5,743 tools. It distinguishes itself from the stable ask_pipeworx by emphasizing the experimental routing edge and the current no-active-candidate state, leaving no ambiguity about its role.

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

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

The description explicitly says to use it exactly like ask_pipeworx when one wants the newest routing, and mentions that results are compared against the stable router. This provides direct when-to-use guidance and implicitly names the stable ask_pipeworx as the more conservative alternative, which is sufficient for routing decisions.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description adds substantial behavior beyond that: the full success return shape, the explicit refusal contract with all five refusal_reason enum values, the evidence-as-verbatim-quote guarantee, and the cost tradeoff of one extra LLM call. 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?

Purpose is front-loaded in the first sentence and every subsequent clause earns its place — the return shape, refusal reasons, cost note, and usage guidance are all decision-relevant. Slightly verbose in the middle ('picks the right tool from 5,743 across 1500 sources, fills arguments, fetches the data') but this conveys mechanism and scale compactly.

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?

This is a complex tool with no output schema, so the description carries the full burden of explaining return values — it does, with precise success and failure shapes plus all enum values. Combined with annotations covering the safety profile and usage guidance covering selection, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% — all six parameters and the alias relationships are fully documented there. The description adds context (the question gets routed and drives argument filling) but no syntax or format detail, so the baseline of 3 for fully-covered schemas 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 opens with a specific, differentiating purpose — 'Hallucination-resistant answer mode for high-stakes reads' — and describes a concrete mechanism: route via ask_pipeworx's 5,743 tools, fetch data, then extract answers using only tool results. It explicitly contrasts with the sibling ask_pipeworx for casual lookups, so an agent can tell them apart without inspecting schemas.

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?

Gives explicit when-to-use criteria: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' backed by concrete domains (financial verdicts, legal claims, medical lookups, public statements). Also gives an explicit when-not: 'prefer ask_pipeworx for casual lookups,' naming the alternative and the selection condition.

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 readOnly/openWorld/idempotent annotations, the description discloses account and paid-plan requirements, parallel decomposition, latency expectations, gap[] semantics ('never invented'), contradictions[] on standard/thorough, citation_uri fetchability, and semantic excerpting of large records. This richly describes behavior without contradicting the annotations.

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

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

The description is long, but nearly every clause contributes: auth, alternative routing, scope, output packet, gap behavior, depth modes, latencies, and citation guarantees. It front-loads the most important operational constraint (account required) and the primary alternative. A little restructuring would help, but there is no real 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?

With no output schema, the description carries the burden of explaining return values, and it does so thoroughly: findings packet fields, hop, citation_uri, gaps[], contradictions[], and expected latency. It covers auth, depth semantics, and the boundary with ask_pipeworx. Nothing essential for correct invocation or expectation-setting is missing.

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

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

Schema coverage is 100% and already documents both parameters thoroughly. The description adds value by clarifying that 'question' may be broad/multi-part and by elaborating the practical consequences of each depth level (quick vs standard vs thorough passes, paid requirement). This exceeds the baseline for fully-described schemas.

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 names a specific verb ('research'), a precise resource ('Pipeworx's 1500 STRUCTURED data sources'), and a distinctive mechanism (1,500 sources, 5,743 tools, parallel facets). It sharply distinguishes itself from open-web search and from ask_pipeworx, making sibling differentiation trivial.

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 gives explicit when-to-use guidance: broad/multi-part questions over structured data. It also names the alternative ask_pipeworx for single lookups and for users who are not signed in, and explains depth-mode trade-offs. This is exactly the 'when vs alternatives' guidance an agent needs.

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read/idempotent profile is established. The description goes well beyond that by disclosing internal fan-out sources (SEC EDGAR, XBRL, USPTO, USAspending, Purple Book, DOL LCA, GDELT→GNews fallback, GLEIF), soft-fail behavior for USPTO mid-2025, the resolved_from/resolved_to behavior, the resolved:false + notes case for private companies, and that sources_used/sources_failed indicate actual data availability. This is exactly the behavioral context an agent needs.

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 information-dense and front-loaded with trigger phrases and the core directive. Every clause earns its place: the fan-out list, soft-fail caveat, and return-component explanation all prevent misinvocation. It loses one point because it is a single dense block rather than structured, and the extremely long parenthetical about fda_products could be compressed without much information loss, though nothing is truly fluff.

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

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

For a complex multi-source tool with 2 parameters, 100% schema coverage, no output schema, and read-only annotations, the description covers all essential invocation facts: input forms, resolution behavior, fan-out sources, result contents, failure semantics, and the empty-section caveat. There is no output schema, so the detailed listing of returned fields (cik, company_name, recent_filings with pipeworx URIs, fundamentals, sources_used/sources_failed) is necessary and present. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, and the schema descriptions already explain type and value shapes. The description adds meaning beyond the schema by clarifying that 'company' and 'ticker' are interchangeable and both accept the same value shapes, that names resolve via SEC EDGAR's company-name match, that ticker/CIK/company name are all valid, and that a private company returns resolved:false with a notes line rather than a hard failure. This reduces the chance of an agent choosing the wrong type-value combination.

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 names a specific verb and resource — 'full cross-source profile of a US public company in ONE parallel call' — and opens with a rich set of natural-language trigger examples. It clearly differentiates from siblings: it says ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when a holistic view is requested, and the sibling list contains single-purpose tools like resolve_entity, compare_entities, and deep_research, so the agent can distinguish which tool is for comprehensive profile assembly.

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 it ('when the user asks for a holistic view'), states a directive ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'), and explains what inputs are accepted (ticker, CIK, company name) and what happens for private companies. It also notes that empty sections are real 'no data', not bugs, which prevents false-negative interpretation.

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?

Annotations already mark the tool as read-only, idempotent, and non-destructive, and the description fully complements this by disclosing significant behavioral nuances: gross vs net spreads, unmodeled Kalshi fees, temporal alignment uncertainty, compatibility code semantics, skipped-unclassified legs, and the fact that returned pairs are keyword-matched rather than resolving-source-verified. No annotation contradiction exists.

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

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

The description is long, but it is well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, codes, fees_note, skipped counters) and front-loads the core purpose. Every section carries substantive operational or interpretational guidance. Some redundancy and density makes it less concise than ideal, but the structure compensates for the length.

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

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

With no output schema, the description carries the full burden of explaining return semantics, and it does so thoroughly: leg-by-leg prices, top_spreads_pp, compatibility_warning vs compatibility_codes, per-entry flags, temporal_alignment fields, skipped counters, and fee limitations. It also covers edge cases such as unknown metric types never being paired and temporal_alignment null meaning uncomputed, not aligned. This is highly complete for a complex analytical 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%, and the schema already documents the topic values and override behavior. The description adds meaningful context beyond the schema, such as the fact that both modes use an identical token-overlap matcher, that explicit params override the topic-mapped side, and that the same disclosures apply in both modes. This is useful but not dramatically beyond what the schema already supplies.

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 precise statement of what the tool does: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It also distinguishes the two modes (topic shortcuts vs explicit event pairings). However, it does not explicitly differentiate this tool from closely related siblings like polymarket_arbitrage, leaving some differentiation to the name and context.

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 clear invocation guidance: use topic shortcuts for pre-mapped macros, or provide explicit ticker/slug pairings for custom comparisons, and notes that both modes run the same matcher. It also warns that most pre-mapped topics return compatibility warnings and that pre-mapped does not mean tradeable. It does not explicitly state when to prefer this tool over sibling alternatives, but the mode-selection 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?

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?

Annotations already declare readOnly/openWorld/idempotent, and the description adds rich behavioral detail: identifiers are source-labelled, unresolved identifiers are surfaced explicitly, ambiguous matches return figi_candidates, and enrichment degrades gracefully when upstream services are unavailable. This goes well beyond the annotations.

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

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

The description is front-loaded with examples and the 'Use FIRST' directive, but it becomes dense and run-on, with a notably malformed phrase: 'more than one instrument it asserts nothing and returns figi_candidates to pick from.' Some sentences are redundant, such as the final cascading-lookups claim.

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 compensates well by explaining return fields, ambiguity handling, unresolved behavior, citation format for drugs, and degraded enrichment behavior. It is sufficiently complete for an agent to invoke the tool correctly across both supported types.

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

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

Although schema coverage is 100%, the description adds crucial meaning: it accepts ticker, CIK, ISIN, or company name even though the schema only mentions ticker and CIK, and it warns to pass only the entity name, not the full noun phrase. This helps avoid realistic lookup failures.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers and gives concrete examples like ticker, CIK, LEI, and RxCUI. It positions itself as the name-to-ID resolver among sibling tools, and the supported-type breakdown adds useful specificity.

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

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

The phrase 'Use FIRST whenever you have a name but need an ID' gives an explicit when-to-use instruction. It does not explicitly name excluded cases or alternative tools, but the guidance is clear and directly actionable.

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, openWorldHint, idempotentHint, and destructiveHint, but the description adds crucial behavioral context: it defines 'could_not_verify' as a failed check with verification_error, explicitly says it is NOT evidence, and distinguishes 'unsupported' from 'could_not_verify'. It also reveals the two internal routes (SEC EDGAR/XBRL vs. grounded pipeline), which goes beyond the annotations.

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

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

The description is long but densely packed with useful information: trigger phrases, routing rules, return types, and critical caller warnings. It front-loads the core purpose with concrete examples, and every sentence contributes. The structure leads from usage to mechanics to caveats, making it 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?

With no output schema, the description fully documents return values (six verdicts, actual value with citation, reasoning), explains error handling, and clarifies edge cases (could_not_verify vs. unsupported). It also describes the end-to-end pipeline and why it's efficient (replaces 4–6 calls). Nothing critical is missing for a caller.

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 provides full descriptions and examples for both parameters (100% coverage). The description adds value by explaining the strategic use of tolerance_pct (e.g., 'set 1–2 for hallucination detection') and clarifies the default/cap behavior. It does not repeat the schema verbatim but enriches the 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 clearly states the tool performs natural-language claim verification, with concrete trigger phrases like 'is it true that' and 'fact check'. It specifies the resource (authoritative sources) and the outcome (verdict + evidence), and distinguishes it from other tools by describing the fast path and grounded pipeline. This goes well beyond a mere verb+resource 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?

Explicit guidance is given: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains when the fast path applies (company-financial claims) versus the automatic fallback (any other claim), and notes that it replaces multiple sequential calls. This is clear, actionable, and differentiates from sibling tools.

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