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 declare readOnly, openWorld, idempotent, non-destructive. The description adds useful behavioral context: it routes to the right tool, fills arguments, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is 'one fast call'. This goes beyond annotations, though it doesn't cover failure modes or result limits.

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

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

The description is long but front-loaded with the core directive and packed with actionable guidance. Each sentence earns its place: examples, exclusions, and fallbacks. Slightly verbose, but the density of useful information justifies the length.

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

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

Given the tool's routing complexity and absence of output schema, the description is remarkably complete. It explains what to expect (structured answers with citations), when to use it, when to prefer alternatives, and provides examples. The agent has enough context to select and invoke correctly without additional documentation.

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

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

Schema coverage is 100% and the question parameter is well-described with aliases. The description adds value by providing varied examples ('current US unemployment rate', 'Apple's latest 10-K') that illustrate the expected content and range of natural language inputs, which helps an agent formulate effective queries.

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 what the tool does: it routes questions to 5,439 tools across 1,412 sources, fills arguments, and returns structured answers with citation URIs. It lists concrete categories of data (SEC filings, FDA, FRED, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by explaining when to step up.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and gives step-up guidance: use ask_pipeworx_grounded for hallucination-resistant single answers or deep_research for broad/multi-part queries. It also names the breaking-news exception, providing clear when-to-use vs 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 cover readOnly/openWorld/idempotent/non-destructive. The description adds valuable context beyond these: it is an experimental edge with candidate routing improvements enabled live, and it clarifies that it 'Falls back to nothing' (i.e., it's a fully working router, not a stub). This is useful behavioral disclosure beyond the structured annotations.

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

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

The description is four well-structured sentences. It is front-loaded with the core identity ('Beta version of ask_pipeworx'), and every sentence adds necessary context: the experimental nature, current state, usage instructions, and confirmation that it is a working router. No fluff or redundancy.

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

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

Given the tool's complexity (universal router with thousands of tools), the description is remarkably complete. It specifies the exact scope (same tools, arguments, response shape as ask_pipeworx), current candidate status, how results are used, and confirms it is fully functional. Annotations cover safety, and the sibling tool provides reference for output shape, so no critical information 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% with descriptive aliases and a clear 'question' field definition. The description does not add additional parameter-level semantics beyond noting 'same arguments' as ask_pipeworx. Since the schema already explains the parameters thoroughly, the 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?

The description clearly states that this is a beta version of ask_pipeworx, a universal router with the same 5,439 tools, arguments, and response shape. It explicitly distinguishes from the stable ask_pipeworx by its experimental routing improvements, so the purpose is unambiguous and well differentiated.

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 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. It also explains that with no active candidate it currently matches ask_pipeworx exactly, giving clear context for when to use it vs the stable alternative.

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

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

Goes well beyond the annotations, detailing the exact return structure on success and failure, including specific refusal reasons (not_in_source, no_tool_match, etc.). Also discloses the extra LLM call cost and the constraint of using only tool result content, providing deep behavioral insight that annotations alone (readOnlyHint, openWorldHint, idempotentHint) do not cover.

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

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

The description is dense with valuable information but remains well-structured and front-loaded with the core purpose. It is longer than typical, yet each sentence adds critical detail (return types, refusal reasons, cost trade-off, use cases), so it earns its length without being 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?

Despite lacking an output schema, the description fully explains the return values, refusal handling, and cost implications. It also provides sufficient context for an agent to decide when to use this tool versus alternatives, covering both functional and non-functional aspects comprehensively for a tool of this complexity.

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

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

The schema has 100% coverage with clear descriptions for 'question' and its aliases, so the baseline is 3. The description does not add extra parameter-level meaning beyond stating it routes to the right tool and fills arguments, but the existing schema already handles parameter semantics adequately.

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

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

The description clearly identifies this as a hallucination-resistant answer mode for high-stakes reads, distinct from the sibling ask_pipeworx tool. It specifies the exact verb/action ('extracts the answer using ONLY what the tool result contains') and states the target use case, making its purpose unambiguous.

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

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

Provides explicit guidance on when to use ('whenever an answer will be quoted, cited, or acted on') and when not to use ('prefer ask_pipeworx for casual lookups'). This directly distinguishes it from the sibling tool ask_pipeworx, giving clear selection criteria.

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

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

Annotations 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?

The description richly discloses behaviors beyond the readOnly/openWorld/idempotent hints: it requires a free/paid account, returns gaps[] instead of inventing answers, includes contradictions[] for some depths, performs semantic excerpting, and states latency expectations. It also explains hop fields and citation_uri behavior, giving the agent a thorough behavioral model.

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 substantive information about prerequisites, use-cases, behavior, output structure, and performance. It is front-loaded with the most critical account/alternative guidance. Some redundancy exists (e.g., repeating 'gaps[]' and 'not open-web'), but overall the length matches the tool's complexity.

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

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

Given there is no output schema, the description fully covers return semantics: verbatim evidence, confidence, source, fetched_at, pipeworx:// citations, gaps[], contradictions[], hop fields, and excerpting behavior. It also covers timings, account requirements, and fallback recommendations, making the tool self-contained for an agent to invoke correctly.

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

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

Although the schema already documents both parameters, the description adds meaningful operational context: 'question' is fine as broad/multi-part ('decomposition is the point'), and 'depth' semantics are expanded with hop behavior, gap recovery, contradiction scans, and paid-tier implications. This goes well beyond the schema's enum 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 defines deep_research as a grounded multi-source research tool over 1,412 structured data sources, decomposing questions into facets and routing them in parallel. It explicitly contrasts with open-web search and sibling tools like ask_pipeworx, making its purpose and differentiation unambiguous.

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

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

Usage guidance is explicit: use for broad/multi-part questions over structured data; use ask_pipeworx for single lookups and breaking/current-news topics. It also states conditions like account/tier requirements and warns that topics outside the structured catalog yield mostly empty gaps[], providing clear when-to-use and when-not-to-use signals.

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 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?

Annotations provide no hints (all false), so the description carries the burden. It discloses rate limiting (5/day), that it's free and doesn't count against quota, that the team reads digests daily, and that signal affects roadmap, adding behavioral context not in schema.

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?

While longer than average, each sentence adds distinct value (use cases, exclusion, guidance, rate limits). Front-loaded with the core verb, though the 'ONLY for tools...' sentence could be slightly tightened.

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 feedback tool with no output schema, it covers all operational aspects: when to use, what to include, exclusions, rate limits, quota impact, and how feedback is processed. The rich input schema already documents parameters 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% with detailed descriptions for type, context, and message, so baseline is 3. Description adds a general instruction to be specific, but this largely duplicates the message param's description; no extra param semantics.

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

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

Description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' using a specific verb and resource. It clearly distinguishes from siblings by focusing on feedback, unlike data-gathering tools like deep_research or validate_claim.

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

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

Explicitly lists use cases (bug, feature/data_gap, praise) and a clear exclusion: if the tool comes from a different MCP server, file it there instead. Also gives guidance on how to phrase feedback (in terms of Pipeworx tools) and notes the 'not sure?' path.

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?

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds extensive behavioral context: compatibility_warning conditions, temporal_alignment, skipped_cross counters, and the fact that real spreads are rarer than shortcuts suggest. No contradictions with annotations.

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

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

The description is structured with clear sections (MODES, RESPONSE, SAFETY FIELDS) and front-loaded with the main purpose. Every sentence adds necessary information; there is no waste. Despite length, it earns its place with precise terminology and 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 absence of an output schema, the description thoroughly explains return values (leg prices, top spreads, safety fields) and complex scenarios (compatibility warnings, temporal alignment). It covers all necessary context for the agent to invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds significant value by explaining the meaning of topic shortcuts, the overriding behavior of explicit parameters, and the response structure (leg-by-leg prices, top_spreads_pp, safety fields). This compensates well beyond the schema.

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

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

The description clearly states it computes cross-venue spread between Kalshi and Polymarket for the same question, distinguishing it from sibling tools like polymarket_arbitrage. It provides specific verbs ('cross-venue spread') and resource ('between Kalshi and Polymarket'), with additional context about venue differences.

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 explains two modes (topic shortcuts and explicit ticker/slug) and warns that most pre-mapped topics return compatibility warnings, implying they may not be tradeable. It also details when spreads are meaningless (temporal misalignment, bet shape mismatch), guiding appropriate use.

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

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

Annotations already 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by explaining internal cascading through multiple lookup endpoints and auto-disambiguation for company inputs. This context 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 well-structured, starting with example queries and usage guidance, then detailing type-specific outputs. It is slightly verbose but every sentence provides valuable context. The front-loaded use case helps agents quickly determine applicability.

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

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

For a simple lookup tool with two parameters and no output schema, the description is fully complete. It explains input variations for each type, what is returned, and even includes citation URIs. No gaps remain 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%, but the description adds meaning by explaining the output format for each type (e.g., ticker + CIK + company name for company; RxCUI + ingredient + brand for drug) and clarifies that value accepts different formats (ticker, CIK, name). This goes beyond the schema's brief 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 uses a specific verb 'resolve' and defines the resource as 'user-spoken NAME to canonical/official identifier.' It provides clear examples of queries and distinguishes the purpose by noting it replaces 2-3 manual lookups. Although not explicitly contrasted with siblings, the purpose is unambiguous.

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

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

The description explicitly states 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It details the supported entity types and their input/output formats. However, it does not mention when not to use it or identify alternative tools for cases where an ID is already known.

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 already indicate readOnly, openWorld, idempotent, and non-destructive hints. The description adds significant context: it explains the dual processing pipeline (structured SEC EDGAR + XBRL for financial claims, grounded pipeline for others), the return format (verdict, actual value, citation, reasoning), and that it replaces multiple sequential operations. 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 informative but slightly lengthy. However, it is well-structured with examples, clear separation of processing paths, and front-loaded key purpose. Every sentence serves a purpose, though some could be tightened.

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

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

Given the tool has only 2 parameters and no output schema, the description is remarkably complete. It explains the tool's scope, routing logic, return values, and usage context, leaving no ambiguity about what the tool does and when to use it.

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 beyond the schema: it clarifies the claim parameter with natural-language examples and explains the tolerance_pct parameter's role in hallucination detection and its default behavior.

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

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

The description uses specific verbs like 'check', 'verify', 'confirm or refute' and clearly defines the resource as 'natural-language claim verification against authoritative sources'. It provides multiple query examples and distinguishes from sibling tools by noting it replaces 4-6 sequential calls.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct'. It also explains the two distinct processing paths (company financial vs. other claims) but does not explicitly mention when not to use it, though the sibling list provides alternatives.

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