Legislation Uk

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) are complemented by description detailing default model, BYO key for Anthropic, and return structure (per-model score, confidence, signals, raw_response). 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 sentences: first states core purpose and default, second adds optional behavior and return format. No superfluous 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?

Covers all 4 parameters, describes return structure despite missing output schema, and links to practical use cases. Adequate for agent decision.

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% so baseline 3. Description adds meaningful guidance: explains _apiKey as optional and its billing implication, provides entity example, clarifies context use for disambiguation.

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?

Describes specific action: probe LLMs for knowledge about a topic and score visibility (0-100). Distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on AI visibility audits rather than Q&A or research.

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

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

Lists use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Also specifies when to provide _apiKey for Anthropic probing. No explicit when-not-to-use but clear enough for selection.

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

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

Annotations already establish readOnly/openWorld/idempotent/non-destructive behavior. The description adds valuable context beyond them: it routes across 5,718 tools and 1,496 sources, fills arguments automatically, returns structured answers with stable citation URIs, works on every tier, and is a single fast call. It also hints at a trade-off by directing hallucination-resistant needs to ask_pipeworx_grounded.

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 average, but nearly every sentence earns its place by conveying coverage scope, default behavior, and escalation paths. Some redundancy exists between 'Use whenever...' and 'START HERE for most questions', but the front-loaded structure and concrete examples keep it 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?

For a single-parameter natural-language router with no output schema, the description is remarkably complete: it covers supported domains, invocation style, examples, default status, tier behavior, alternatives, and what the response will contain. Nothing essential for selecting or invoking the tool 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% and the schema already documents the question parameter and its aliases clearly. The description adds broad examples and situates the tool for factual questions, but it does not add substantial parameter-level detail beyond what the schema provides. 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 states a clear verb and resource: it routes natural-language questions to structured data sources and returns answers with pipeworx:// citation URIs. It also explicitly differentiates itself from web search and from siblings like ask_pipeworx_grounded and deep_research, so an agent can distinguish it without opening 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?

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'Use whenever the user asks...', 'START HERE for most questions', and 'Step up only when needed' with named alternatives and the conditions that select them. This leaves no ambiguity about 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?

The description discloses meaningful behavioral context beyond the annotations: candidate routing improvements can be enabled live, no candidate is currently active as of 2026-07-26, and it currently matches ask_pipeworx exactly. It also clarifies that it falls back to nothing and is a fully working router, not a degraded preview.

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 identity and difference, then adds current state, usage guidance, and a clarifying fallback note. Every sentence carries distinct information without fluff.

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

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

Given the lack of an output schema, the description compensates by stating that the response shape is identical to ask_pipeworx. It covers purpose, current behavioral state, usage instructions, and expected equivalence, making the tool fully actionable for an agent.

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

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

Schema coverage is 100%, so the parameter semantics are already fully documented in the schema. The description adds the useful note that arguments are identical to ask_pipeworx, but otherwise does not need to compensate for any coverage gap.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx and an identical universal router with the same 5,718 tools, arguments, and response shape. It distinguishes this beta from the stable ask_pipeworx by emphasizing that candidate routing improvements are tested live.

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

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

It explicitly says to use it exactly like ask_pipeworx when the newest routing is desired, and notes that results are compared with the stable router to determine merges. The experimental edge is implied as a caution, though it does not explicitly state a when-not-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?

The description adds substantial behavioral detail beyond the annotations: same routing as ask_pipeworx, extraction limited to tool result contents, explicit success/refusal return shapes with refusal_reason enum, and an additional LLM call cost. This is far more than the readOnlyHint/openWorldHint/idempotentHint already declare, and it does not contradict any annotation.

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 average but every sentence carries unique value: mode classification, routing behavior, return/refusal contracts, usage context, and cost trade-off. It is front-loaded with the most important trait (hallucination resistance) and structured with clear return-shape 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?

With no output schema, the description fully covers return values, refusal reasons, and the conditions under which refusals occur. It also mentions the extra cost and sibling relationship, making the tool's behavior predictable. No critical operational detail is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100% with the question parameter and all aliases clearly documented. The description doesn't add new parameter-level meaning beyond reinforcing that the input is a natural-language question, which the schema already states. The baseline 3 is appropriate here.

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 core function: a hallucination-resistant answer mode that routes like ask_pipeworx and extracts answers only from tool results. It defines specific verbs and resources (picks tool, fetches data, extracts answer) and distinguishes itself from the sibling ask_pipeworx by its grounded behavior.

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

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

Explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and provides concrete examples of high-stakes domains. It also gives clear guidance to prefer ask_pipeworx for casual lookups due to the extra LLM call cost.

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 readOnly and idempotent, and the description adds extensive behavioral context: low-confidence resolution short-circuit, closed market handling, wide-spread warnings, resolution-rule risk parsing, and fan-out patterns. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). Every sentence adds value, but the length may be slightly overwhelming for agents needing quick scanning.

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

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

No output schema, but the description fully explains response shapes (result.market, result.analysis, result.evidence) and special behaviors (low-confidence match, closed market, wide spread, cancellation rule). The tool is complex, and the description covers all necessary aspects.

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

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

Schema coverage is 100%, and the description enriches each parameter: market examples (slug, URL, question), depth enum explained, include_raw with default and size impact. Schema alone would be insufficient; the description adds critical usage nuance.

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 inputs (slug, URL, question text) and outputs (evidence packet + market-vs-model comparison), distinguishing 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?

The description provides explicit use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also covers blocking scenarios and safety, but does not explicitly contrast with sibling tools or list 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?

Adds rich behavioral context beyond annotations: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, return of paired data with citation URIs. No contradiction with annotations.

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

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

Single paragraph with dense information, front-loaded with examples and use cases. Could be slightly more structured but no wasted sentences.

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

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

Covers purpose, data sources, parameter semantics, and return format (paired data + URIs). Missing explicit mention of output format but sufficient given no output schema.

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

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

Despite 100% schema coverage, description adds significant meaning: explains what each type pulls (company: financials, drug: adverse events and trials), and gives concrete examples for values (tickers, drug names). Goes beyond 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?

Description explicitly states it performs side-by-side comparison of 2-5 companies or drugs in a single call, with specific examples of use cases ('which is bigger', 'head to head'). Clearly distinguishes from sibling tools like entity_profile.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing strong when-to-use guidance. Implicitly excludes single-entity lookups.

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 readOnly/openWorld/idempotent annotations, the description discloses latency ranges, gap-recovery behavior per depth, contradictions[] results, semantic excerpting, citation_uri fetchability, and the 'never invented' grounding policy. These are rich behavioral details not visible in structured fields.

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 every sentence carries information—no filler. It front-loads the critical sign-in/fallback note and then builds from core behavior to depth semantics to output format. A little dense as a single block, but appropriately sized for the tool's complexity.

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

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

With no output schema, the description fully documents the return packet (verbatim evidence, confidence, source, fetched_at, citation, gaps[], contradictions[], hop, citation_uri) and even explains citation resolvability. It covers account prerequisites, alternatives, depth modes, latency, and edge cases—nothing an agent needs to call 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% for both parameters, so baseline is 3. The description adds meaningful enrichment: depth's paid tier, 'standard' vs 'thorough' hop behavior, contradictions scan, and expected latency. 'question' examples are also provided, pushing this above baseline.

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

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

Description states a specific verb (research) and resource (Pipeworx's 1496 structured data sources), mentions decomposition into facets and parallel routing to 5,718 tools. It explicitly contrasts with ask_pipeworx and clarifies 'this is NOT open-web search,' making the purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: use ask_pipeworx for single lookups or breaking news, and use deep_research for broad/multi-part structured-data questions. It even warns that unsupported topics yield empty gaps[], plus a sign-in prerequisite and fallback instruction.

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 provided annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable behavioral details: it returns top-N tools with full schemas and curated examples, and notes that each result is 'ready to call directly, no second schema lookup needed.' This gives the agent clear expectations of output format and usage flow.

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

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

The description is front-loaded with purpose and usage context, followed by specific examples. It contains multiple sentences but each adds value (examples, behavior, call-to-action). Could be slightly more concise, but structure is 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?

For a discovery tool with rich schema and annotations, the description covers what the tool does, when to use it, what it returns (tools with schemas), and how to use results. There is no output schema, but the description suffices. A minor gap: no mention of pagination or sorting, but within acceptable range.

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

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

Schema description coverage is 100% with clear parameter descriptions (including aliases for query). The description does not add new semantic details beyond re-stating the tool's purpose, which is adequate given high schema coverage. 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 starts with a clear verb+resource ('Find tools by describing the data or task') and provides extensive concrete examples (SEC filings, FDA drugs, etc.), which both clarifies purpose and distinguishes it from sibling tools (e.g., ai_visibility_check, deep_research) by positioning it as a first call for browsing the tool set.

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

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

The description explicitly states when to use ('Use when you need to browse, search, look up, or discover what tools exist') and includes a directive to call it first when many tools are available. However, it does not explicitly state when not to use it or provide direct alternatives, though sibling names are listed in 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?

The description discloses behavioral traits beyond annotations: parallel fan-out across multiple sources, specific returned data items, potential soft-failure for patents, and unsupported inputs. Annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) are consistent, 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 front-loaded with examples and purpose, then details data sources and returns. It is slightly lengthy but well-structured, earning its sentences with informative content.

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

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

Given no output schema, the description explains return items (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and limitations. It lacks explicit output format, but is sufficient for a profile 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 description adds significant meaning: explains type constraint ('only company supported'), value formats (ticker or zero-padded CIK), and explicitly states names are not supported, guiding to use resolve_entity. This goes beyond 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 the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific example queries and explicitly states preference over chaining other tools, distinguishing it from siblings.

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

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

The description provides clear guidance on when to use ('when user asks for a holistic view') and what inputs to avoid ('names not supported – use resolve_entity first'). It lacks explicit when-not-to-use scenarios but implies them through the preference statement.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and the purpose of deletion, which goes beyond annotations.

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

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

Two sentences, no fluff. First sentence states action, second provides usage guidance and sibling references. Every sentence earns its place.

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

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

For a simple one-parameter tool with no output schema, the description is complete. It covers purpose, usage, and sibling relationships, complementing 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% with a clear description and example for the 'key' parameter. Tool description does not add extra meaning beyond the schema, so baseline of 3 is appropriate.

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

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

Description clearly states 'delete a previously stored memory by key', specifying verb and resource. It distinguishes from sibling tools 'remember' and 'recall' by explicitly pairing them.

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

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

Provides explicit use cases: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Lacks explicit when-not-to-use but gives sufficient context.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that it 'fetches the page, extracts title/description/key links, and emits standard format', which aligns with annotations. It does not contradict and provides moderate additional detail about the process.

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

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

Three sentences front-loaded with the main action, followed by process details and use cases. Every sentence adds value, no fluff.

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

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

The description covers the output format ('standard llms.txt markdown', 'single text blob') despite no output schema. With only 2 parameters both well-documented in schema, and rich annotations, the description is complete for accurate tool 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%: both parameters have descriptions in the schema. The tool description adds minimal extra beyond the schema (e.g., 'default 25, max 50' for max_links is already in the schema). 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 verb 'generate', the resource 'llms.txt file', and the context 'for any URL so AI crawlers can index the site cleanly'. It distinguishes from sibling tools by specifying the exact output format and use case, such as auditing 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 explicitly lists three use cases: getting a client's site indexed, drafting for own project, or auditing competitors. It does not explicitly state when not to use it or mention alternatives, but the provided examples give clear context for appropriate usage.

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 non-destructive behavior. The description adds further behavioral details: return fields (title, type, year, status, extent, enactment date, long-title summary, full-text URL), content format (XML), and a quality caveat (fields are best-effort parsed with a raw excerpt). This enriches the agent's understanding 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 two sentences with no wasted words. The first sentence states the tool's action and purpose with an example. The second lists return fields and notes the format and caveat. Every sentence adds essential information.

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

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

For a simple tool with three required parameters, no output schema, and rich annotations, the description covers all necessary aspects: what it does, how to call it (example), what it returns (field list), and a quality note (best-effort parsing). There are no gaps in helping an agent decide when to use it and what to expect.

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 each parameter. The description adds value by providing a concrete example of valid parameter combinations (ukpga/2010/15) and explains how the three parameters together identify a unique document, which aids an agent in constructing a valid call.

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 begins with a specific verb ('Get metadata') and identifies the resource (UK legislation) by type, year, and number. It includes a concrete example (Equality Act 2010) which distinguishes it from the sibling search_legislation tool that searches across multiple documents.

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 the required parameters (type, year, number) and format, making it clear that this tool is for retrieving a single, known piece of legislation. It does not explicitly state when not to use it or name alternatives, but the context of siblings implies search_legislation for broader queries, so it's sufficiently directive.

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 and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: version semantics ('current', 'enacted', or date), default behavior, and that every response states the version served and effective date. This goes beyond annotations to describe response 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 compact and front-loaded with the core purpose. It contains 5 sentences, each serving a distinct function: purpose, return scope, identification format, version behavior, and sibling usage. The only minor drawback is slight redundancy with the schema, but overall it is 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?

For a tool with no output schema, the description clearly states the return value ('Returns the full text of that section alone') and the response's version statement. It also covers the critical UK-law versioning nuance and prerequisite lookup steps. Missing edge-case error behavior, but that is not essential for correct invocation.

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

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

Schema coverage is 100% for all 5 parameters, so baseline is 3. The description adds a concrete example ('Data Protection Act 2018 = ukpga/2018/12') and re-explains version options, but most parameter meaning is already fully documented in the schema. The description does not significantly reduce ambiguity beyond what the schema provides.

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

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

The description opens with 'Read the actual WORDS of one section of a UK Act or statutory instrument', giving a specific verb and resource. It distinguishes itself from siblings by emphasizing 'one section' and 'full text of that section alone', and explicitly differentiates from get_legislation as a prerequisite for retrieving year/number.

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 when-to-use guidance: 'a specific provision does not cost a whole statute' implies cost/scope benefit. It also names alternatives directly: 'Use search_legislation or get_legislation first if you need the year and number.' This is explicit exclusion and alternative selection guidance.

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

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

Beyond annotations, the description discloses that it reads a bounded amount and 'says plainly when it stopped short rather than returning a silently clipped statute', and that every response states which version it served. These are valuable behavioral details not present in 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 several sentences long, but every sentence contributes information: purpose, usage guidance, bounded-read behavior, version semantics, response guarantee, and source. It is front-loaded with the core purpose and wastes no 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?

Even without an output schema, the description covers what the tool returns (text, bounded amount, version statement) and its source (legislation.gov.uk). For a read-only retrieval tool with rich annotations and full parameter documentation, this 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%, so baseline is 3. The description adds context that 'UK law exists in VERSIONS that differ in substance', reinforcing why the version parameter matters. While most parameter details are already in the schema, this contextual note elevates the score slightly.

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 verb and resource: 'Read the text of a whole UK Act or statutory instrument'. It also explicitly distinguishes itself from siblings by noting it returns the body of the law rather than a catalogue entry, and contrasts with get_legislation_section which returns just a section.

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 usage guidance: 'Use for short instruments and for reading an Act end to end; for one provision prefer get_legislation_section, which returns just that section.' It also mentions the bounded reading for large Acts, implying a caveat for very large statutes, and names the alternative tool directly.

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

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

Annotations already indicate it's read-only, idempotent, and non-destructive. The description adds that it returns specific fields and is scoped to the caller's subscriptions, which are useful behavioral traits 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 two sentences, front-loads the core action, and contains no extraneous information. Every sentence serves a purpose.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is reasonably complete. It lists the return fields and provides usage context, though it could mention that subscriptions are scoped by default to active ones.

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

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

The input schema has 100% description coverage for its single parameter (include_inactive). The description does not add extra meaning beyond the schema's parameter description, so the 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 identifies the tool as listing the caller's active subscriptions, specifying the returned fields. It distinguishes itself from sibling tools like subscribe and unsubscribe by indicating it's a read-only review operation.

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

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

The description explicitly states when to use the tool: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context, though it doesn't explicitly state when not to use it.

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

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

Beyond the annotations (all false), the description discloses meaningful behavior: rate-limiting to 5 per identifier per day, no tool-call quota impact, daily digest review, and the claim_token round-trip flow for checking resolution status. This fully carries the burden that annotations leave unaddressed.

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 every sentence carries actionable guidance: when to use, when not to, token mechanics, rate limits, and roadmap impact. It is front-loaded with the core purpose and contains no filler or repetition.

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 (nested context object, optional claim_token, no output schema), the description is complete: it explains the claim_token return, the follow-up workflow, the feedback categories, exclusions, and operational constraints. An agent has enough to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the exact claim_token usage pattern and its return semantics ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), which is beyond what the schema alone provides. Other parameters are already well-described in the schema.

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

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

The description opens with a specific verb and target: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly enumerates feedback categories (bug, feature, data_gap, praise) and explicitly scopes the tool to Pipeworx-served tools, distinguishing it from sibling 'ask_pipeworx' variants.

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 triggers: wrong/stale data means bug, a missing desired tool means feature/data_gap, and good results mean praise. It also states when NOT to use it ('if the tool came from a different MCP server... file it with that server instead') and provides a disambiguation rule for identifying Pipeworx tools.

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

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

Adds context beyond annotations: data source (CF analytics), no PII, format, and caching. Annotations already cover read-only/idempotent.

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

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

Four sentences, front-loaded with main purpose, no redundant information.

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

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

Returns format explained, caching noted, no output schema needed. All key aspects covered for a simple read tool.

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

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

Schema covers window parameter with enum and description; description adds context on window trade-offs. No missing parameters.

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

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

Description clearly states the tool returns top tools, packs, and call volume, but does not explicitly differentiate from siblings like 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?

Provides three concrete use cases and explains window parameter behavior, but lacks explicit alternatives or when-not-to-use.

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

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

Annotations declare read-only, open-world, idempotent, non-destructive. Description adds rich behavioral context: semantic anchor, partition filter, fill check against live book, response structure, and conditions for null signals. 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?

Well-structured with clear sections for each mode and bullet-point details. Slightly verbose but every sentence adds value. Front-loaded with main purpose.

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

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

Despite no output schema, the description fully explains the response structure (opportunities array, partition_check fields), fill check algorithm, and filtering criteria (semantic anchor, partition filter). Complete for a complex scanning tool.

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

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

Schema coverage is 100% with descriptions. Description adds meaning: event accepts slug or URL, topic asks seed question; explains how each parameter triggers different scanning logic and processing.

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

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

Clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. Distinguishes three modes (no args, event, topic) and differentiates from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Provides explicit when-to-use guidance for each mode, recommends event mode for specific markets, explains cross-event scanning, and warns against trading when fill check shows non-realizable edge. References sibling for custom sizing.

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

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

The description discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), response structure (by_segment, diagnostics, fed_candidates), and important nuances (Fed bets excluded due to unreliable signal; every opportunity carries specific fields). Annotations already declare readOnly=true, and description adds rich behavioral context without contradiction.

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

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

The description is long but well-structured with clear sections (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT) and front-loaded with purpose. While verbose, every part adds unique value for the complex tool, making it acceptable.

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

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

Despite no output schema, the description fully documents the response structure and field meanings. It explains all parameters, caching, and edge cases (Fed bets, diagnostics). The tool is complex, but the description covers all necessary context 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?

With 100% schema coverage, baseline is 3, but the description adds substantial meaning beyond the schema. It explains defaults, usage, and rationale for each parameter (e.g., slippage_pp discusses Polymarket fees; min_partition_leg_kelly explains why it exists). This elevates the score.

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

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

The description clearly states the action ('Scan top Polymarket markets'), the resource ('Polymarket markets'), and the outcome ('return opportunities where Pipeworx data disagrees with market price'). It explicitly states the intended use case ('what should I bet on today') and distinguishes from siblings by mentioning specific segments and knobs.

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

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

The description provides clear context for when to use the tool ('discover opportunities without paging hundreds of markets') and explains tradeable-edge knobs. However, it does not explicitly mention when not to use it or compare with sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker'.

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

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

The description adds extensive behavioral context beyond annotations: it details the response structure (tracked[], expired[], snapshot_dates[]), explains decay_pp_per_day and signed values, and mentions the 60-day TTL. No contradictions with annotations exist.

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

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

The description is well-structured with sections, but it is somewhat verbose in the response field details. Every sentence adds value, but a bit more conciseness would improve it.

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 absence of an output schema, the description fully covers the response structure, edge cases (expired opportunities, data gaps), and limitations (60-day TTL). It is complete for an agent to understand what the tool returns.

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 by explaining default values and the purpose of each parameter (e.g., 'lookback' for days, 'snapshot family' for window). This adds value beyond 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 the tool provides edge persistence and decay telemetry from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis rather than raw snapshots.

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 the tool's purpose and gives context for when to use it (e.g., comparing fresh vs. old edges), and includes a LIMITS section outlining constraints. However, it does not explicitly state when not to use it or mention direct alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details like walking the order-book ladder, returning verdicts, and listing thin legs and forced directional risk. It enriches the safety profile without contradiction.

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

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

The description is long but well-structured: it front-loads the purpose, then uses labeled sections for SINGLE-MARKET and BASKET modes. Every sentence contributes meaningful information, but some internal repetition could be trimmed.

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, many return fields, no output schema), the description covers all necessary aspects: input modes, parameters with defaults, returned fields per mode, error cases, and usage warnings. It fully equips an agent to decide when and how to call the tool.

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

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

Schema coverage is 100% with good descriptions, so baseline is 3. The description adds extra context such as default auto logic for side, clamp range for size_usd, and explains basket settlement notional as 'shares per leg'. This goes 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 'Realizable-vs-theoretical edge check against live CLOB order-book depth', specifies two distinct modes (single-market and basket), and lists returned fields. It differentiates from sibling tools like polymarket_arbitrage by being a pre-trade risk check.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains why partial fills convert arb into directional risk, providing clear context.

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

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

The description goes far beyond the annotations by explaining compatibility warnings, machine-readable codes, skipped unclassified legs, low-confidence pairs, temporal alignment, and dropped comparison counters. It also details the spread formula and warns that both warning fields can be non-empty even when matched pairs exist. This is excellent behavioral disclosure with no contradiction against the read-only, idempotent 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 it is well organized with explicit mode, response, and safety-field sections. Nearly every sentence carries operational value for a complex tool; the front-loading of purpose and modes helps an agent quickly orient. It is slightly dense, but not wasteful.

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 there is no output schema and the tool has substantial behavioral complexity, the description is remarkably complete. It explains both modes, the response shape, spread sign, safety codes, skipped-leg handling, temporal alignment, and an important real-world caveat. An agent has enough information to call the tool correctly and interpret its results.

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

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

The input schema already covers 100% of the parameters with descriptions, examples, and override behavior, so the baseline is 3. The tool description adds only light context about auto-fetching the matching event and custom pairings, which is useful but not a substantial semantic addition beyond what the schema already states.

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 resource and operation: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It is clear about the two-venue comparison, but it does not explicitly distinguish itself from sibling tools such as polymarket_arbitrage or polymarket_edges, so it stops short of a 5.

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 within-tool guidance: use `topic` for pre-mapped shortcuts and explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings. It also cautions that pre-mapped topics are often not truly tradeable. However, it does not explicitly say when to prefer this tool over sibling alternatives.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds contextual behaviors: the dual behavior of retrieval vs. listing, scoping to user identifier, and the omission of key triggers listing. 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 two sentences, front-loaded with the core purpose, and every sentence earns its place. No wasted words.

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

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

Given no output schema, the description implicitly covers output (value or list of keys), usage context, scoping, and integration with siblings. Complete for a simple 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%, and the description mostly repeats schema info: 'omit the key argument to list all keys'. It adds minimal extra meaning (context of omission) beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool's action: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It specifies the verb (retrieve/list), resource (values/keys), and differentiates from siblings by explicitly mentioning 'remember' and 'forget'.

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

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

The description provides clear context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It mentions scoping and pairing with remember/forget. However, it does not explicitly state when not to use the tool or mention alternatives among siblings.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds behavioral details beyond annotations by explaining the mark_read parameter's effect on the next call and that the feed is persisted. 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 very concise: two sentences plus a third about alternative access. It is front-loaded with the main purpose and contains no redundant information. 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 tool with 5 optional parameters and no output schema, the description covers the main functional aspects: what is returned (source, citation_uri, payload), filtering, mark_read behavior, and alternative access. It could mention the limit parameter or pagination, but the schema covers that. Overall, it is fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving an example for the 'type' parameter ('sec_8k'), clarifying that 'since' expects an ISO timestamp, and explaining the effect of 'mark_read'. This goes beyond the schema's 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 starts with a specific verb 'Pull' and resource 'fired events from your subscription feed'. It clearly distinguishes from sibling tools by focusing on recent alerts from a persisted feed and mentions filtering by type, which is unique among the listed siblings.

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

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

The description provides usage context: it mentions that polling works fine and gives an alternative endpoint for scripts/dashboards. However, it does not explicitly compare with sibling tools or state when not to use this tool, which would make it 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 declare readOnlyHint, idempotentHint, and destructiveHint, establishing safe operation. The description adds valuable context: it fans out to multiple sources, uses fallbacks, and mentions USPTO soft-failure. However, it could disclose rate limits or error handling more explicitly.

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

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

The description is a single paragraph that efficiently front-loads key information with example queries, then provides details. It is slightly verbose but every sentence adds value. Could be improved with more structured formatting (e.g., bullet points for sources).

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

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

Given the tool's complexity (multiple sources, fallback, soft-failure, no output schema), the description is remarkably complete. It describes the output format, constraints on USPTO, and distinguishes from sibling tools. No important gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds significant meaning beyond schema: explains `since` format with examples, recommends typical values, and clarifies that `value` accepts tickers or CIKs. This extra detail justifies a higher score.

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

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

The description clearly states the tool's purpose as a 'change feed for a company in the last N days/weeks/months' with specific verbs and resources. It also distinguishes itself from the sibling 'entity_profile' tool by explicitly noting when the alternative should be used.

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

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

Provides explicit guidance on when to use this tool versus alternatives (e.g., 'Use entity_profile instead when you want the static profile'). Also includes example queries and explains the fallback mechanism (GDELT→GNews) for when to use which data source.

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

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

Adds context beyond annotations: memory scoped by identifier, 24-hour retention for anonymous users, overwrite behavior implied by idempotentHint. No contradictions.

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

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

Three sentences: purpose, usage, details. Front-loaded and no extraneous information.

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

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

For a simple key-value tool with 2 params and no output schema, description covers persistence, scope, and relation to siblings fully.

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

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

Schema coverage is 100%, but description adds value with key naming examples and explicit statement that value can be any text, aiding agent 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?

Uses specific verb 'save data' and resource 'key-value pair'. Clearly distinguishes from sibling tools 'recall' and 'forget' by naming them.

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

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

Explicitly states when to use ('discover something worth carrying forward') and pairs with recall/forget. Provides scoping and persistence details for different user types.

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 signal read-only, open-world, idempotent, and non-destructive behavior. The description goes well beyond these by disclosing ambiguity handling (`figi_candidates` when a name matches multiple instruments), explicit `unresolved` reporting, graceful degradation when GLEIF/OpenFIGI are unavailable, and internal cascading through multiple lookup endpoints.

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 front-loaded with example phrases and the first-use heuristic, then organized into scannable type and behavior sections. Some sentences are dense, but given the tool's complexity and the absence of an output schema, the length is mostly justified.

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

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

For a tool with no output schema, the description is exceptionally complete: it covers input formats, supported types, ambiguity behavior, unresolved identifiers, source provenance, fallback behavior, and why this tool is needed before other tools. An agent has everything required to invoke it correctly.

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

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

Schema coverage is 100%, but the description adds critical semantic detail: examples for ticker/CIK/name, bond issuer exact-print guidance, warning against trailing security-class words, ISIN-to-LEI behavior, and the meaning of candidate vs unresolved results. This materially improves the agent's ability to format inputs correctly.

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 clear verb-resource pair: resolve a user-spoken name to canonical/official identifiers required by other tools. It enumerates concrete example phrases and lists supported entity types, and the distinction from siblings is implicit through the 'other tools require as input' framing.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID,' which is strong when-to-use guidance. It does not name specific sibling tools as alternatives, but it clarifies that this tool replaces 2-3 manual lookups and covers cases other sources may miss, giving the agent enough context to select it.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior. The description adds value by explaining the internal mechanism (probes each entity with 'ai_visibility_check'), ranking logic, and return details (score, confidence, signal density). No contradictions with annotations.

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

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

Three sentences: purpose, procedure, use case, and output summary. Front-loaded with the core action. Every sentence is necessary and efficient. No fluff.

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

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

While no output schema exists, the description covers the return format (ranked list with score, confidence, signal density). For a 4-parameter tool, it adequately explains inputs, behavior, and output. Could be slightly more precise about score range, but sufficient for competent use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds minor context (first entity treated as subject) but does not significantly elaborate on parameters beyond the schema descriptions. It meets the baseline expectation.

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

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

The description uses specific verbs ('Compare', 'Probes', 'ranks') and clearly identifies the resource ('AI visibility') and scope ('multiple entities side-by-side'). It distinguishes itself from sibling tool 'ai_visibility_check' by emphasizing multi-entity comparison and ranking.

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 suggests a use case ('competitive AI-marketing audits') and provides an example question. It implies when to use (comparing multiple entities) but does not state when not to use or list alternatives beyond the implied single-entity case.

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 multi-source fan-out, return fields, per-advisory detail, and performance caveat (5-30s for bundlephobia first measurement). Annotations already indicate readOnly, idempotent, non-destructive; description adds significant context beyond that.

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

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

Description is front-loaded with core purpose, but is somewhat verbose. Each sentence adds value, but could be slightly more concise.

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

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

Comprehensive coverage of return values (summary, per-advisory, links, alternatives), ecosystem restriction, and graceful degradation. No output schema, but description fully compensates.

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). Description adds minimal extra meaning beyond the schema (e.g., default version behavior). Baseline of 3 is appropriate.

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

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

Clearly states the tool performs a composite check for npm packages, covering license, advisories, version history, and bundle size. Distinguishes from siblings by specifying NPM-only scope and mentioning alternatives for other ecosystems.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small"', and provides when-not-to-use: other ecosystems fall under deps.dev:version directly. Also sets expectations for partial failures.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the tool is safe and idempotent. The description adds valuable context: the data source ('legislation.gov.uk Atom feed'), document types, and that results include full-text URLs. This goes beyond annotations without contradiction.

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

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

Two concise sentences plus a list of document types. The main action is front-loaded. No superfluous 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?

Given the complexity of 4 parameters (100% schema coverage) and no output schema, the description adequately explains what is returned (matching Acts/instruments with URLs) and the data source. It is complete for a search 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%—all parameters have clear descriptions in the schema. The description reaffirms the main parameters ('title words and optional year') but does not add significant new semantic meaning beyond the schema.

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

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

The description uses specific verbs ('Search', 'returning') and states the resource ('UK legislation'), distinguishes it from the sibling 'get_legislation' by emphasizing search by title words and optional year. It clearly communicates the tool's function as a 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 mentions 'UK legislation only' and lists document types, implying scope but does not explicitly state when to use this tool versus alternatives like 'get_legislation'. There is no guidance on when not to use it.

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

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

The description discloses the embedding model (BGE-base-en), windowing (500-char overlapping windows), character offset and similarity score in results, and a 200K char limit (with truncation and flagging). These details go well beyond the annotations (readOnly, idempotent, openWorld, non-destructive), fully informing the agent of the tool's 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 well-structured and front-loaded with the core purpose and usage. It contains some technical details that are valuable but could be slightly more concise. Still, it is efficient and every sentence contributes.

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 absence of an output schema, the description thoroughly explains the return value (top-N passages with offsets and similarity scores), constraints (200K char cap, truncation flag), and internal mechanics. This is complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The tool description does not add significant new meaning beyond the schema's parameter descriptions (e.g., it reiterates the max char limit for text). The natural-language query example is helpful but not essential. No score above baseline warranted.

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

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

The description clearly states the tool performs semantic search inside a fetched record. It uses specific verbs ('search', 'pass', 'get back'), specifies the resource ('a fetched record'), and distinguishes from siblings by mentioning that it saves context compared to cramming the full record into the prompt, and explicitly pairs with ask_pipeworx_grounded.

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

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

The description explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It explains the benefit ('saves context, returns only the passages that matter') and provides a pairing strategy with another tool. This gives clear guidance on when and how to use it.

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

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

Annotations indicate idempotentHint=true, but the description says 'Create a new subscription id' suggesting non-idempotent behavior. This contradiction lowers the score. However, the description does add important behavioral details such as delivery channel constraints and webhook signing.

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

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

The description is well-structured with front-loaded purpose and clear sections for requirements, types, and delivery. It is comprehensive without being overly 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?

The description covers all essential aspects: purpose, required account, type-specific parameters, delivery options, and return value (subscription ID). It leaves minor gaps like error handling but is largely complete for a subscription-creation 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?

The description provides extensive context beyond the schema, including examples for each type, format for params, and detailed explanations for delivery channels including verification and limits. This greatly aids the agent in correctly invoking the tool.

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 and returns a subscription ID. It distinguishes itself from sibling tools like unsubscribe, list_subscriptions, and recent_alerts by focusing on creation.

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

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

The description mentions requirements (OAuth account) and explains supported types and delivery options, but does not explicitly guide when to choose subscription over other tools. However, the verb and context imply usage.

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

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

Annotations already cover read-only, idempotent, non-destructive nature. Description adds that it returns category-bucketed examples with tool shapes, but doesn't disclose additional behavioral traits beyond what annotations imply.

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 somewhat lengthy but front-loaded with alternative phrasings and purpose. Every sentence adds value, though it could be slightly more concise.

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

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

Given no output schema and rich annotations, the description fully explains the return format (category-bucketed questions with tool shapes) and use cases, making it complete for a discovery tool.

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

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

Schema coverage is 100% and the description adds meaning by explaining the topick parameter's purpose and listing example 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 clearly states it is an onboarding entry point that returns example questions with exact tool calls, distinguishing it from sibling tools 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?

Explicitly says to use this first when unsure of Pipeworx's capabilities, and describes optional topic parameter to focus on a specific area.

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

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

Adds significant context beyond annotations: ownership enforcement and deactivation (not deletion) behavior. Annotations already indicate non-destructive mutation and idempotency; description complements without contradiction.

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

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

Two concise sentences with no redundancy. Front-loaded with action, 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 one parameter, no output schema, and simple mutation, the description fully covers purpose, usage, side effects (deactivation, historical availability), and ownership constraint.

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

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

Schema has 100% coverage for the single 'id' parameter with description 'Subscription id (uuid) returned by subscribe.' Description uses 'by id' but adds no extra parameter-level meaning. Baseline 3 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?

Describes 'Cancel a subscription by id' with specific verb and resource, clearly differentiating from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions'), giving when-to-use context. Also explains the deactivation behavior, providing implicit guidance on side effects. Lacks explicit alternatives or when-not-to-use, but sufficient for clarity.

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

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

Annotations provide readOnly/openWorld/idempotent, but the description adds critical behavior beyond them: the meaning of 'could_not_verify' (the check did not happen, must not be treated as evidence) and 'unsupported' (looked but no source). It also discloses the mechanism (verbatim evidence, pipeworx:// citation) and the judgment step. This is exactly the behavioral context agents need and goes well beyond structured hints.

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

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

The description is long but every sentence adds unique value: trigger phrases, routing behavior, verdict list, special case warnings, and performance benefit. It is front-loaded with usage signals and structured with clear topic shifts. No filler or repetition.

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 covers return values (all possible verdicts), the grounded/or structured actual value with citation, reasoning, and the error payload for could_not_verify. It also addresses edge cases (unsupported vs cannot verify) and the operational context (replaces multiple calls). This is complete for a complex tool with two parameters.

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

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

Though schema coverage is 100%, the description significantly enhances parameter meaning. It explains that tolerance_pct overrides the wording-implied tolerance, gives concrete guidance (1–2 for hallucination detection), and notes the default cap of 5. The claim parameter is clarified with natural-language examples, reinforcing the schema without redundancy.

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

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

The description opens with explicit trigger phrases and a clear verb+resource: natural-language claim verification against authoritative sources. It distinguishes itself from siblings by describing the SEC EDGAR/XBRL fast path versus the grounded pipeline, and notes it replaces 4–6 sequential calls, making its unique role unmistakable.

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

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

States explicitly to use whenever the agent needs to check whether something a user said is factually correct. It further disambiguates by routing company-financial claims through the structured path and all other claims through the grounded pipeline, giving the agent a complete decision rule with no ambiguity.

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