Companies House

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. The description adds significant behavioral context: default model (Workers AI Llama-3.3-70b, free), API key usage (BYO key, direct payment to Anthropic), and return format (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations.

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

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

The description is three sentences, each serving a clear purpose: purpose statement, parameter behavior, and use cases. No redundant words, front-loaded with key action and output, highly efficient.

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

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

Despite no output schema, the description explains the return format in detail. All aspects (purpose, parameters, usage context, limitations of API key) are covered. Given moderate complexity (4 params, 1 required), the description is sufficiently complete.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds value beyond schema by explaining default model behavior for `models`, API key purpose for `_apiKey`, and disambiguation use for `context`. This extra context justifies a score above baseline 3.

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

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

The description uses a specific verb 'probe' and clearly states the resource ('LLMs') with a quantified output ('score visibility 0-100 per model'). It distinguishes itself from sibling tools by focusing on multi-model AI visibility scoring, which is distinct from other tools like ask_pipeworx or scan_competitor_ai_presence.

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

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

The description provides clear use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use additional parameters (e.g., `_apiKey` for Anthropic). However, it does not explicitly state when not to use this tool or contrast with specific siblings, missing a small opportunity for exclusion guidance.

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

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

Annotations already cover readonly/idempotent and non-destructive semantics. The description adds important behavioral context: routing across 5,529 tools, returning stable citation URIs, covering every tier with one fast call, and handling breaking news via live news packs. No contradiction with annotations.

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

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

The description is long but front-loaded with the most important guidance ('PREFER OVER WEB SEARCH') and every sentence adds value: use cases, examples, escalation paths, and note about breaking news. It could be mildly trimmed, but the structure is clear and information-dense.

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

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

For a tool with no output schema and relatively simple input, the description is exceptionally complete: it covers domains, intent-based triggers, examples, routing behavior, citation URIs, tier accessibility, and explicit alternatives. It tells the agent everything needed to invoke and interpret results.

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

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

Schema coverage is 100%: all 6 parameters are aliases for the single 'question' parameter, which is well-described in the schema. The description does not add parameter-specific semantics beyond the schema, but it does clarify the kind of questions to pass. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a routing/answering system for factual questions about real-world entities, explicitly contrasting with web search and naming sibling tools like ask_pipeworx_grounded and deep_research. The verb 'routes' plus the resource (5,529 tools) makes the purpose specific and distinct 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 gives explicit when-to-use guidance ('PREFER OVER WEB SEARCH', 'Use whenever the user asks...'), concrete examples, and when-not-to-use guidance ('Step up only when needed') with named alternatives (ask_pipeworx_grounded, deep_research). This fully differentiates usage from siblings.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds valuable context about the experimental nature, live candidate switching, and that it is a fully working router with no fallback. It stops short of detailing the response format, but 'same response shape' is a useful reference to the stable tool.

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, with the core purpose front-loaded and each sentence adding distinct information (beta status, equivalence, usage guidance, experimental caveat). Slightly verbose in repeating the identical nature, but overall well-structured and free of filler.

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

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

For a beta router with no output schema, the description sufficiently explains its relationship to ask_pipeworx, the current behavior, and the experimental context. It relies on the sibling tool's definition for full understanding, but within the sibling set, this is complete enough for an agent to use it correctly.

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

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

Schema coverage is 100%, with all six parameters documented including aliases. The description only repeats 'same arguments' without adding extra semantic meaning. Baseline of 3 is appropriate as the schema handles the heavy lifting.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx sibling by noting candidate routing improvements. However, it relies on the reader knowing what ask_pipeworx is, and the verb 'ask' is implied rather than explicit.

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

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

The description explicitly states when to use this tool: 'when you want the newest routing.' It also clarifies that no candidate is currently active, so behavior matches ask_pipeworx exactly, and notes that results are compared against the stable router to guide merges. This provides clear usage context and implies when to prefer 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?

Beyond the annotations (readOnly, openWorld, idempotent, not destructive), the description discloses the refusal mechanism with specific refusal_reason values, the return schema (answer, evidence, confidence, source, fetched_at), and the extra LLM call cost. This gives agents a realistic model of behavior 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 moderately long but every sentence provides distinct value: mode, routing, extraction method, return structure, refusal logic, usage scenarios, and cost comparison. It is front-loaded with the core differentiator. A slight reduction could improve conciseness, but no sentence feels redundant.

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 (routing over 5,529 tools, extraction process, potential refusal reasons, cost implications), the description covers all critical aspects: what it does, how it works, what it returns, when to use it, and how it compares to the sibling. No output schema exists, so the description appropriately details return values and refusal cases.

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 all six parameters documented as aliases for 'question.' The description itself does not add additional parameter-level semantics beyond what the schema already states, so a baseline score of 3 is appropriate. No new information about parameter formatting or constraints is provided.

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 a specific verb and resource: 'Ask Pipeworx — Grounded' as a 'hallucination-resistant answer mode.' It explicitly differentiates from the sibling tool ask_pipeworx by highlighting the extraction-based approach and return structure. The purpose is unambiguous and includes scope ('high-stakes reads') and behavior (only uses tool result content).

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

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

Provides explicit usage criteria: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples (financial verdicts, legal claims, medical lookups, public statements). Also gives an alternative: 'prefer ask_pipeworx for casual lookups' and notes the cost trade-off, offering clear decision guidance.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details behavior: market resolution, classification, fan-out, response shapes, safety short-circuits, closed-market handling, illiquidity warnings, and cancellation rule parsing. This is extensive and adds significant value.

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 and front-loaded with purpose. Every sentence adds value given the tool's complexity. Minor room for improvement in formatting, but overall efficient.

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

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

Given no output schema, the description thoroughly explains response shapes, evidence packet, resolver contract, parent event extractor, news fields, and edge cases. It leaves no ambiguity for agent interpretation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for each parameter: examples for market, depth with quick/thorough and default, include_raw with usage guidance. This enriches the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific verb and resource. It distinguishes from siblings like polymarket_edges by being the general research call, covering classifiers and fan-out examples.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' While it does not explicitly exclude alternatives, this guidance is clear and actionable.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, etc. The description adds value by explaining parallel call behavior, correct handling of off-calendar fiscal years, and that the tool returns paired data with pipeworx:// citation URIs—beyond annotations.

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

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

The description is well-structured with example queries upfront, but slightly lengthy. However, every sentence adds value and no redundancy is present.

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 2 parameters, no output schema, and no nested objects, the description fully explains return format (paired data + citation URIs) and behavior for both entity types. No 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 coverage is 100%, but the description enriches parameter meaning: for 'type' it specifies what data is retrieved, and for 'values' it gives examples (tickers, drug names) and reinforces the 2-5 range. It also notes that results are sorted by primary metric, adding useful detail.

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

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

The description explicitly states it performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with examples like 'Compare X and Y'. It clearly distinguishes from sibling tools such as get_company by explaining what each type pulls (company: 10-K financials; drug: FAERS/FDA/trials).

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 includes 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing explicit guidance. It also clarifies the appropriate context for company vs. drug types and notes that results are sorted by primary metric for easy interpretation of comparisons like 'largest' or 'most'.

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: account requirement, paid tier for 'thorough', expected latency (15-60s, up to 90s), behavior like 'never invented', explicit gaps[], contradictions[], citation_uri only when fetchable, and semantic excerpting. No contradiction with annotations; readOnly/idempotent hints are consistent with a read-only research tool.

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 most critical info (account requirement, alternative fallback) before diving into mechanics. Every sentence adds value; the length is justified by the tool's complexity and the need to set expectations for a high-latency, multi-source research operation.

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 thoroughly covers the return format (findings packet with verbatim evidence, confidence, source, fetched_at, citation), gaps[], contradictions[], hop field, and citation_uri fetchability. It also explains performance expectations and the difference between standard/thorough. This is complete 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?

Schema coverage is 100% (both parameters have descriptions), so baseline is 3. The description enriches meaning by explaining depth values' facet counts (quick=3, standard=5, thorough=8), hop behavior, and what the question parameter can contain. This goes beyond the schema's enum labels.

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

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

The description states exactly what the tool does: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources... in ONE call' and explains its decomposition/parallel-routing mechanism. It clearly distinguishes itself from sibling tools like ask_pipeworx by noting 'this is NOT open-web search' and listing its unique capabilities (findings packet, gaps, contradictions).

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 vs. alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. Also explains depth levels and that multi-step questions resolve in one call. No exclusions are missing.

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 (readOnlyHint=true, idempotentHint=true) are consistent. Description adds that results are 'ready to call directly, no second schema lookup needed,' which is useful behavioral information. No contradictions.

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

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

The description is a single paragraph that efficiently conveys purpose, usage, and output. It lists many example domains, which is helpful for understanding scope, but could be slightly more concise. Well-structured with key points front-loaded.

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 (6 params, no output schema), the description adequately covers purpose, when to use, and what results contain. It lacks mention of default limit or error behavior, but overall 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 description coverage is 100%, so baseline is 3. Description mentions query aliases and that results include schemas, but does not add significant new meaning beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and distinguishes from siblings by emphasizing discovery and browsing, which is unique among sibling tools.

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

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

Explicitly states when to use: 'Use when you need to browse, search, look up, or discover what tools exist.' Lists many example domains and advises 'Call this FIRST when you have many tools available.' This provides clear context and implies alternatives (other tools for specific tasks).

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 valuable behavioral context: it fans out across multiple sources (EDGAR, XBRL, USPTO, news, GLEIF), details return fields, warns that USPTO PatentsView API 'soft-fails until reactivated' after May 2025, and notes the parallel nature of calls.

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 fairly long but front-loaded with trigger phrases and key behavioral guidance. Every sentence adds necessary information about sources, returns, and limitations. A minor reduction could be made, but overall it's structured well.

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 a multi-source profile and no output schema, the description is largely complete. It covers all return fields, sources used, and limitations (USPTO sunset, name requirement). It lacks details on error handling or pagination, but annotations cover idempotency and safety.

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 schema by explaining that type must be 'company' only, providing examples of valid values ('AAPL', '0000320193'), and explicitly stating that names are not supported and to use resolve_entity instead.

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 produces a 'full cross-source profile of a US public company in ONE parallel call.' It provides trigger examples ('tell me about X', 'research Acme') and explicitly differentiates itself from sibling tools by recommending it over chaining single-pack lookups.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies when not to use: when only a name is provided, directing to 'resolve_entity first.' This provides clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds context about why to delete (sensitive data, stale task) without contradicting annotations. It doesn't reveal additional behavioral traits beyond what annotations convey, but the usage context is valuable.

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 waste. Purpose, usage, and pairing are front-loaded. Every sentence serves a clear function.

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

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

Given the tool's simplicity (one required param, no output schema), the description covers purpose, usage, and relationship to siblings completely. No gaps remain for effective tool selection.

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

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

Schema coverage is 100% and the description only repeats 'by key' without adding format or type details beyond the schema's 'Memory key to delete.' Baseline 3 is appropriate as schema already documents the single parameter 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 explicitly states 'Delete a previously stored memory by key,' which is a specific verb+resource combination. It distinguishes from sibling tools by mentioning pairing with 'remember' and 'recall,' making its role clear.

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

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

Provides explicit usage conditions: 'when context is stale, the task is done, or you want to clear sensitive data.' Also advises pairing with 'remember and recall,' offering clear when-to-use and alternative context.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the steps (fetches page, extracts title/description/key links, emits markdown) and output format, without contradicting 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 concise with three sentences plus a bullet list, all front-loaded with the main purpose. No unnecessary words or 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?

Despite no output schema, the description explains the output format and usage. Parameters are fully documented in the schema, and the tool's simplicity allows the description to be 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 description coverage is 100% with clear parameter descriptions for 'url' and 'max_links'. The description does not add extra semantics beyond the schema, so 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 it generates a production-ready llms.txt file for any URL, specifying verb and resource. It distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than visibility scanning.

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

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

The description lists three explicit use cases (client indexing, own project drafting, competitor auditing). While it doesn't explicitly state when not to use the tool or name alternatives, the context is clear enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds value by detailing exact return fields (status, type, SIC codes, etc.) and links. Could mention error handling for missing company, but overall good.

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 action, second lists returns. No fluff, efficient, and front-loaded with the key 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 output schema exists and annotations cover safety, description is thorough for a simple read tool. Lists all major return fields. Could mention pagination or rate limits, but not critical.

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

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

Schema coverage is 100% with a good description of the parameter. Description reinforces it's a UK company number but adds no new syntax or format details. 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 verb 'fetch' and the resource 'UK company profile', specifying the input as company number. It lists returned data, distinguishing it from sibling tools like search_companies (search) and get_filings (filings only).

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?

Implied that this tool is for fetching a specific company by number, versus searching. No explicit when-not-to-use or alternatives mentioned, but the context is clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral details such as 'Returns up to 25 filings per page' and lists the returned fields, plus the category filter. It does not contradict annotations and provides value beyond them.

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

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

The description is two sentences, front-loaded with the primary purpose and then succinctly covering return fields and filtering. No filler or redundancy, earning a perfect score for efficiency.

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

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

With a rich output schema, complete parameter descriptions, and strong annotations, the description is largely complete. It covers return fields and filtering but does not mention pagination behavior (start_index) or the name-resolution nuance, though these are present in the schema. Overall, it is adequate for the tool's complexity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions filter by category and company_number from search_companies, but the schema already provides detailed descriptions for all parameters, including the company_number resolution nuance. The description adds only marginal semantic value over the schema.

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

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

The description clearly states the verb 'Retrieve' and the resource 'filing history for a UK company', explicitly linking to search_companies for obtaining the company_number. This distinguishes it from sibling tools like get_officers or get_company, making the purpose unambiguous.

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

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

The description provides clear context by referencing 'from search_companies' and describing the filter categories, which implies when to use this tool. It does not explicitly exclude alternatives or state 'use when you need filings', but the context is strong enough for an agent to infer the appropriate use 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safe-read profile is covered. The description adds useful context on the response fields (name, role, appointment dates, etc.) and the register_type filter, without contradicting annotations. It does not mention automatic name resolution, but that is present in the 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?

The description is three sentences: purpose, return content, and options. It is front-loaded with the verb 'List', contains no filler, and every sentence adds distinct 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?

Given a comprehensive schema (100% coverage), strong annotations, and an output schema, the description covers the essential usage flow (start from search_companies), the data returned, and available filters. It is sufficient 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 description coverage is 100%, with each parameter fully described. The description restates the register_type filter and pagination but adds no new syntactic or semantic details beyond what the schema already provides. The company_number name-resolution behavior is only in the schema, not the description.

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

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

The description opens with 'List directors, secretaries, or LLP members for a UK company by company_number', a specific verb, resource, and scope. It clearly differentiates from sibling tools like get_persons_with_significant_control by naming officer roles explicitly.

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 says 'from search_companies', which implies a prerequisite lookup step and provides clear context for when to use this tool. However, it does not explicitly mention alternatives like get_persons_with_significant_control or state when not to use this tool, so it falls short of full alternative guidance.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds value by detailing what data is returned (name, kind, natures of control, etc.), which goes beyond the annotations and helps the agent anticipate the response. It does not mention pagination behavior, but that is covered by the schema parameters.

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 clear sentences with no fluff. The first sentence states the core action and input; the second lists the returned fields. Each sentence earns its place and provides high-value information in a compact form.

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 moderate complexity (3 params, output schema present, strong annotations), the description is adequately complete. It explains the purpose, the input source, and the return fields. It does not elaborate on pagination or name resolution, but the schema covers those details, so the description does not need to repeat them.

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 fully documents all three parameters. The description adds minimal parameter-related context: it mentions company_number comes from search_companies. It also slightly misleads by saying 'by company_number' while the schema notes the parameter can also accept a company name, but since the schema is explicit, the impact is limited.

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

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

The description starts with a specific verb 'Retrieve' and clearly identifies the resource: 'PSC (beneficial owner) records for a UK company'. It also lists the key input (company_number) and differentiates from sibling tools like get_officers or get_company by focusing on PSC/beneficial owner records.

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

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

It provides clear context for when to use this tool: when you need PSC/beneficial owner records for a UK company. It also hints at a prerequisite by saying 'by company_number (from search_companies)', implying you should first use search_companies to obtain a valid company_number. However, it does not explicitly name alternative tools or 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 already declare readOnlyHint and idempotentHint, so the description merely adds return field details, which is sufficient.

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

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

Two sentences, front-loaded with action and returns, 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 the tool's simplicity (1 optional param, no output schema), the description covers return fields and usage adequately.

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 does not add additional meaning to the include_inactive parameter beyond the schema description.

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

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

The description clearly states 'List the caller's active subscriptions' and enumerates returned fields, distinguishing it from siblings like subscribe and unsubscribe.

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

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

States to use it before adding more subscriptions or to find an id to cancel, providing clear context for when to invoke.

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 (readOnlyHint=false, destructiveHint=false) already signal a non-readonly, non-destructive operation. The description adds valuable context beyond annotations: the claim_token flow ('Filing without an account returns a claim_token; pass it back later...'), rate limits ('Rate-limited to 5 per identifier per day'), and impact ('signal directly affects roadmap'). This enriches the behavioral model without contradicting 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?

Despite being several sentences long, every sentence earns its place: purpose, use cases, exclusions, tips, token flow, rate limits, and cost. It is front-loaded with the core purpose and structured logically, making it dense but not 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 tool has no output schema, but the description explains return behavior (claim_token) and the follow-up workflow. It covers edge cases (different MCP servers), rate limiting, and free usage, making it complete for a feedback 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?

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the claim_token usage ('pass it back later... to read whether it was fixed and what changed') and instructing how to populate message/context ('Describe the issue in terms of Pipeworx tools/packs'). Though it doesn't enumerate each parameter, it provides useful guidance, elevating it to a 4.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb and identifies the resource (Pipeworx team feedback), and it distinguishes itself from sibling research tools by being the only feedback submission 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?

Explicit when-to-use guidance is provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives when-not-to-use and alternatives: 'if the tool came from a different MCP server... file it with that server instead.' This clearly differentiates from siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: data source ('CF analytics-engine'), no PII, caching behavior (5min-1h), and the aggregated nature ('just (pack, tool, count)'). 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?

Four sentences, no wasted words. First sentence states purpose, second lists use cases, third clarifies data origin and privacy, fourth mentions caching. Information is front-loaded and easy to parse.

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

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

Despite no output schema, the description sufficiently explains what is returned (top tools, packs, call volume) and adds caching details. For a simple, read-only tool with no required parameters, this is complete and actionable.

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 the single parameter 'window' with enum and description. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' helping the agent choose based on intent. With 100% schema coverage, this baseline is 3, but the additional context justifies a 5.

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 resource ('top tools, top packs, and total call volume') and the action ('Returns'), making the tool's function immediately obvious. It is easily distinguishable from sibling tools like ask_pipeworx or discover_tools by focusing on trending usage rather than direct queries or general discovery.

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?

Three specific use cases (discovering hot data sources, confirming popular tools, seeing alignment with agent needs) provide clear context for when to use this tool. However, it does not explicitly mention when not to use it or compare it to alternatives like discover_tools, which could further guide agent decision-making.

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 (readOnlyHint, openWorldHint, idempotentHint) already indicate safety and non-destructiveness. The description adds rich behavioral details: it performs scans, checks monotonicity, computes partition sums, applies semantic similarity filters, filters placeholder slugs, and provides fill-check against live depth. 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 thorough and well-structured with clear sections for each mode, but it is somewhat lengthy. However, every sentence adds value, and key details are front-loaded. Minor reduction could improve conciseness without losing 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?

Given the complexity of the tool (optional params, no output schema, but detailed response fields), the description is complete. It enumerates return fields (opportunities array, partition check info, fill check results) and explains edge cases (placeholder filters, low similarity). No gaps.

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

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

Schema coverage is 100%, and the description significantly extends meaning for both parameters. For 'event', it provides slug examples and explains the partition check. For 'topic', it explains cross-event scanning and the semantic anchor constraint (Jaccard similarity ≥0.30). This goes well beyond the bare schema.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (no args, event, topic) with explicit examples, leaving no ambiguity about the tool's purpose and distinguishing it from siblings like 'polymarket_edges' or 'polymarket_fill_risk'.

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

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

The description provides explicit guidance on when to use each mode: call with NO args for trending scan, pass 'event' for single-event analysis with partition checks, or 'topic' for cross-event scanning. It also warns against trading when fill check shows non-realizable edge, directing to 'polymarket_fill_risk' 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so the tool is safe. The description goes far beyond by detailing internal logic (three segments, caching at KV level, diagnostic output), potential data sources (FRED, GDELT), and caveats like the Fed note and 24h-move warning. 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 lengthy but well-organized, with a clear front-loaded purpose statement and structured sections (segments, tradeable-edge knobs, response format). Every sentence carries information; however, it could be more concise by reducing redundant elaboration on model families.

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 (9 parameters, three segments, no output schema), the description covers the response structure (by_segment, diagnostics), caching policy, and behavioral details (e.g., placeholder-slug filter, Fed note). It leaves no major gaps for an AI agent to understand the tool's full behavior.

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 parameter descriptions. The description adds significant connective context, explaining how 'knobs' like min_liquidity and max_spread_pp filter for tradeable edges, and min_partition_leg_kelly applies to per-leg Kelly within structural arbitrage. 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 it 'scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price', specifying the verb (scan/return), resource (Polymarket), and unique scope (disagreement detection). It differentiates from siblings by focusing on edge discovery without pagination, and the detailed segments make its purpose unmistakable.

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

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

The description provides a clear use case ('what should I bet on today') and explains that it avoids paging through hundreds of markets. However, it does not explicitly contrast with sibling tools like 'polymarket_arbitrage' or 'polymarket_edge_tracker', nor does it state when NOT to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it describes the response structure (tracked, expired, snapshot_dates), explains trend computation and decay, mentions that snapshots are written only on cache-miss, and notes history depth bounded by 60-day TTL and daily closures. 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 appropriately detailed for the tool's complexity. It is front-loaded with the core question and then explains response fields and limits. While lengthy, every sentence adds necessary context without redundancy.

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

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

The tool has no output schema, so the description must cover return values. It does so comprehensively, listing fields like tracked, expired, snapshot_dates with detailed meanings. It also addresses edge cases like gaps in data and decay computation, making it complete for an agent to understand and invoke correctly.

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

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

Schema description coverage is 100% for both parameters. The description adds value by providing default values, clamping for 'days', and clarifying that 'window' refers to snapshot family. This enriches the schema information.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' answering 'how long has this edge existed and is it shrinking?' It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical persistence and decay rather than current 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 provides context for usage: it explains when to use this tool (to differentiate fresh vs old edges) and implicitly when not to use it (when only current snapshots are needed, use 'polymarket_edges'). It does not explicitly list alternatives but the domain context is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds critical behavioral context: walking the ladder, returning specific metrics, and warning that partial basket fills convert arb into unhedged directional positions (the dominant loss mode). This 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?

Well-structured with bold section headers (SINGLE-MARKET, BASKET) and a strong opening sentence. Every sentence adds value, but the description is long (around 200 words). For a complex tool with two modes, this is justified; slightly more conciseness could be possible.

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 (two modes, detailed return fields) and no output schema, the description comprehensively covers what the tool returns for both single-market and basket modes. It also addresses parameter behavior, usage context, and risks (forced_directional_risk, thin_legs).

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 enriches meaning: explains `side` defaults for basket mode ('sell if partition sum > 1, buy if < 1'), clarifies `size_usd` as settlement notional for baskets, and defines clamps (10–1,000,000). This adds value beyond schema.

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

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

The description clearly states the tool performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes with explicit parameter requirements. This specificity differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains when not to use it (thin books, partial fills) and describes prerequisites (one of `market` or `event`).

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, non-destructive behavior. The description adds substantial value by detailing the two cases for compatibility_warning, temporal_alignment, skipped cross-type/subtype counters, and the pragmatic note that pre-mapped topics are often not tradeable. 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 fairly long but well-structured with clear sections (overview, modes, response, safety fields). Every sentence adds meaningful detail. Minor redundancy ('pre-mapped ≠ tradeable' is stated twice) but overall efficient.

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

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

Despite lacking an output schema, the description thoroughly explains the response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). Given the tool's complexity, all essential behavioral and output details are covered.

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, every parameter is described. The description enriches understanding: it lists the 10 topic shortcuts, explains that explicit tickers override topic-mapped sides, and describes how the parameters interact. Examples in the schema further aid interpretation.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It specifies two distinct modes (topic shortcuts and explicit tickers), making the purpose precise and easily distinguishable from sibling tools like polymarket_arbitrage.

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 on when to use each mode (topic vs explicit tickers) and warns that pre-mapped topics often yield compatibility warnings. It explains conditions that invalidate spreads (compatibility_warning, temporal_alignment). It does not explicitly state when not to use this tool vs alternatives, but the context is sufficient.

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. Description adds scoping and the behavior of listing keys when argument omitted, which adds value beyond annotations.

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

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

Three sentences: first states core behavior, second gives use cases, third adds scope and pairing. Front-loaded with key action and 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?

For a simple tool with 1 optional param and no output schema, the description covers purpose, usage, scope, and relationships to siblings completely. No gaps.

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

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

Schema coverage is 100% with description for the key parameter. The description adds the critical nuance that omitting key lists all keys, which is essential for correct usage.

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

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

The description clearly states the tool retrieves a value saved via remember, or lists all keys if no key is provided. Specific examples (ticker, address, research notes) and distinction from siblings remember/forget are evident.

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 to look up context the agent stored earlier' and pairs with remember/forget. Provides scoping (anonymous IP, BYO key hash, account ID) and implies when not to use (save/delete operations).

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 useful details beyond annotations: explains the mark_read side effect (flags events read), describes payload fields (source, citation_uri, raw event). 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?

Three sentences, front-loaded with purpose, then key fields, then filtering and usage. Every sentence earns its place; no redundancy or fluff.

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

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

Covers the main behavior, filtering, and mark_read side effect. Lacks explicit mention of limit default (though schema states 50) and pagination, but given annotations and schema richness, it's almost 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?

Adds meaning beyond schema: provides example filter value "sec_8k" for type, explains mark_read effect, clarifies since is ISO timestamp. Schema already covers all parameters, so baseline is 3, but description adds extra value.

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

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

Clearly states the tool pulls fired events from the subscription feed, with specific verb and resource. Distinguishes from sibling tools like list_subscriptions, subscribe, etc. by focusing on retrieving alerts.

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

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

Provides clear context: polling is fine, and mentions an alternative REST endpoint for scripts/dashboards. Does not explicitly exclude scenarios but gives sufficient guidance for typical 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 indicate read-only, idempotent, and non-destructive behavior. The description adds rich detail: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and structured output with citations. 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?

Front-loaded with example queries, each sentence adds value: sources, param details, sibling distinction. No fluff; dense but 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 the tool's complexity (multi-source, fallback, soft-fail) and no output schema, the description covers all essential aspects: input params with examples, output structure, limitations, and sibling differentiation. Exceptionally 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 beyond schema by providing recommended defaults (e.g., "30d" for since) and clarifying that value accepts tickers or CIK. This extra guidance earns a 4.

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

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

The description clearly states it provides a change feed for a company over a recent window, with specific verbs like "what's new" and "latest on". It distinguishes from sibling entity_profile which is for static profiles.

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

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

Explicitly states when to use (for recent change queries) and provides a direct alternative: 'Use entity_profile instead when you want the static profile'. Also gives example query forms.

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 behavioral details beyond annotations, such as key-value pair scoping by identifier, persistence for authenticated users, and 24-hour retention for anonymous sessions. No contradiction with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false).

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

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

The description is concise with four sentences covering purpose, usage, details, and pairing. No fluff, well-organized.

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 two parameters and no output schema, the description thoroughly covers purpose, usage, persistence details, and pairing with siblings. It is complete.

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

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

Schema coverage is 100% with examples in the parameter descriptions. The tool description does not add additional semantics beyond what the schema provides, 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?

The description clearly states the tool's purpose: saving data for reuse across conversations or sessions. It provides concrete examples (resolved ticker, target address, etc.) and distinguishes from siblings by mentioning 'recall' and 'forget'.

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

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

Explicit usage guidance is given: 'Use when you discover something worth carrying forward.' It also pairs with recall and forget, providing context for when to use this tool versus alternatives.

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

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

Annotations already declare read-only, idempotent, open-world behavior. The description adds substantial behavioral detail: internal cascading lookups, graceful degradation of enrichment data, explicit listing of unresolved identifiers, and source labeling for each identifier. It also mentions returning citation links. No contradictions with annotations.

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

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

The description is long but densely packed with useful information. It starts with illustrative queries and then systematically explains supported types, output details, and failure behavior. Every sentence adds value, and the structure is logical, though slightly verbose for a tool with only two parameters.

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 compensates by detailing what is returned for each type, including identifiers, sources, citations, and unresolved fields. It also covers edge cases like enrichment failure and graceful degradation. The tool's complexity (two parameter types, multiple data sources) is fully explained, making it complete for an agent to use effectively.

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

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

Schema coverage is 100% with both parameters described. The description further enriches this by offering concrete examples for 'value' (e.g., 'AAPL', 'ozempic'), clarifying the input formats for each type, and explaining the resolution behavior associated with each 'type' selection. This goes beyond the schema's basic descriptions.

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

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

The description opens with concrete example queries and states the core purpose: resolving a user-spoken name to official identifiers for other tools. It distinguishes itself from siblings by emphasizing 'Use FIRST whenever you have a name but need an ID' and by describing the cross-source identity spine, clearly differentiating from tools that retrieve entity data directly.

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 FIRST whenever you have a name but need an ID' and provides example queries that illustrate the intended use cases. However, it does not explicitly state when not to use this tool or name specific alternative tools, though the 'Use FIRST' phrasing implies priority and the description notes it replaces multiple manual 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?

Annotations declare readOnly, idempotent, non-destructive. Description adds value by detailing that the tool probes each entity with ai_visibility_check, ranks results, and returns score, confidence, signal density. It also notes the first entity is treated as subject. No contradiction with annotations.

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

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

Description is two concise sentences plus an illustrative example. It is front-loaded with the main action. Slightly verbose in the example but overall efficient. Could be slightly more structured but still effective.

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

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

No output schema, but description adequately describes return values (ranked list with score, confidence, signal density). It mentions probing with ai_visibility_check and the role of first entity. Covers essential aspects for tool selection and 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 baseline is 3. Description adds context: 'entities' array first entry is subject, rest competitors; models default to workers-ai; _apiKey needed for anthropic. This enhances understanding 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 clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and returns a ranked list with scores. It differentiates from sibling tools like ai_visibility_check (single entity) and compare_entities (generic) by specifying the exact function: competitive AI-marketing audit.

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 use case: 'competitive AI-marketing audits' and gives example query. It implies when to use (comparing multiple entities' AI recognition) but does not explicitly state when not to use or name alternatives. Sibling tools provide that context, but the description itself lacks exclusions.

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

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

Annotations already indicate safe, idempotent, non-destructive behavior. The description adds critical behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and the sources_failed field lists timeout sources. 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 dense but efficient, front-loading the composite purpose. Minor length for the complexity, but every sentence adds value. Could benefit from slight structuring (e.g., bullet points for return fields), but remains concise overall.

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 comprehensively lists return elements: summary block fields (is_latest, license, etc.), per-advisory detail, links, and recent alternative versions. Also mentions potential partial failures. Fully satisfies completeness given the tool's complexity.

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

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

Schema coverage is 100%, and the description enriches parameter understanding: 'package' notes scoped packages accepted, 'version' clarifies it defaults to latest when omitted. Adds clarity 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 specifies the tool's composite purpose: a single call for evaluating an npm package across deps.dev and bundlephobia. It explicitly states the tool addresses questions about safety, popularity, size, and cost. This stands out from sibling tools, which are unrelated.

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

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

The description provides explicit guidance on when to use this tool: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also clarifies ecosystem limitations (NPM only in v1) and directs to deps.dev:version for other ecosystems, drawing clear boundaries.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds value by specifying return fields and pagination defaults (implicit from schema examples), confirming no destructive 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 two sentences: the first states core functionality and return fields, the second guides subsequent actions. No redundant information; efficient and front-loaded.

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

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

For a search tool with full annotations, output schema, and clear parameters, the description covers everything needed: purpose, return fields, and follow-up actions. No gaps.

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

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

Schema coverage is 100% with all parameters described. The description does not add additional parameter meaning beyond what's in the schema, but it does reinforce the parameter purpose (e.g., 'Company name (full or partial)'). 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 searches UK Companies House by company name and lists the returned fields. It also explicitly connects to sibling tools (get_officers, get_filings) by mentioning using company_number for lookups, distinguishing it from other search/lookup tools.

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

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

The description explains when to use the tool (to find a company by name) and provides examples in the schema. It implies alternatives when company_number is already known: 'Use the company_number to look up officers, filings, and PSCs.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)', which discloses internal behavioral traits 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?

The description is four sentences long, front-loaded with the core function. Each sentence adds distinct value: purpose, use case, pairing with sibling, and technical details. No redundancy or fluff.

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

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

Despite no output schema, the description explains that the tool returns 'top-N passages with character offsets and similarity scores', and details embedding model, window size, character limit, and truncation behavior. This is comprehensive for a tool of this complexity, leaving no major gaps.

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

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

Schema description coverage is 100%, with clear descriptions for all three parameters. The description adds extra details: character limit for 'text', range and default for 'limit', and example queries for 'query'. This adds meaning beyond the schema, justifying a score above baseline 3.

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

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

The description clearly states the tool does 'Semantic search INSIDE a fetched record', specifying the verb (search), resource (record), and scope (inside a fetched record). It distinguishes from siblings like ask_pipeworx_grounded by focusing on searching already-pulled text rather than fetching or grounding.

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt — search_within saves context' and recommends pairing with ask_pipeworx_grounded. It provides clear when-to-use and an alternative, making usage guidance comprehensive.

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 a non-read, non-destructive, idempotent write operation. The description adds value by specifying that the subscription ID is returned, that webhook is auto-disabled after 10 failures, and that SMS has a daily cap. 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 detailed but well-structured, starting with the main purpose, then usage requirements, types, and delivery options. Every sentence adds value, though it could be slightly more concise for a tool with a single primary action.

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 types, parameters, and delivery thoroughly but lacks a full output schema or details on the response structure beyond returning the subscription ID. Given the complexity of nested objects, this is a notable gap.

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

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

Schema coverage is 100%, but the description enriches the schema with concrete examples for each type and delivery option, clarifying constraints like 'sponsor or condition required' for clinical trials and SMS phone verification.

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

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

The description states 'Create a proactive monitoring subscription to a live-data event stream' with a clear verb and resource, and distinguishes it from sibling tools like 'list_subscriptions' and 'unsubscribe'.

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

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

Provides explicit context including account requirements, supported subscription types with examples, and delivery channels. Lacks direct comparison to alternatives like 'recent_alerts' but is specific enough for the tool's purpose.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns category-bucketed example questions with exact tool and argument shapes, and that calling with no arguments gives a full spread. This goes beyond annotations by detailing the output format and invocation options.

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 fairly long but well-structured: it starts with common trigger phrases, explains the output, then provides usage guidance. It front-loads the purpose and is efficient in conveying necessary information. Slightly verbose but justifiable.

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 one optional parameter and no output schema, the description is complete. It covers what the tool does, what it returns (category-bucketed examples with tool shapes), when to use it (onboarding), and how to customize (topic focus). No gaps are evident.

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%, providing a baseline of 3. The description enriches the parameter meaning by listing example values (finance, pharma, betting) and explaining that omitting it gives a cross-category spread. This adds practical guidance beyond the schema's simple enum description.

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

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

The description clearly states it is an onboarding entry point that returns category-bucketed example questions. It uses specific verbs (returns, call) and distinguishes from siblings like ask_pipeworx and entity_profile by noting it is the first tool to use when the agent doesn't know Pipeworx's capabilities.

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

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

Explicitly states when to use ('when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools'). Mentions optional topic parameter for focus. Does not explicitly list when not to use, but the guidance is clear enough.

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

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

The description explains that the row is deactivated (not deleted) and historical events remain available via recent_alerts. This adds context beyond annotations (readOnlyHint: false, destructiveHint: false, idempotentHint: true) without contradiction.

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

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

Two sentences with no redundancy. Every sentence adds value: the first states the action, the second provides ownership and behavioral details.

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

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

The description covers the essential points: action, parameter, ownership, and effect. For a simple tool with one parameter and no output schema, it is complete enough. Could possibly mention idempotency or confirm behavior on repeated calls, but idempotentHint already covers that.

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

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

Schema coverage is 100% with a single parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' The description adds no additional information about the parameter, so it meets the baseline of 3.

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

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

The description clearly states 'Cancel a subscription by id,' specifying the verb (cancel) and resource (subscription). It distinguishes 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?

The description says 'Ownership is enforced — you can only cancel your own subscriptions,' providing a clear condition for use. It does not explicitly mention alternatives but implies that other subscriptions require different tools.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds substantial behavioral context beyond these: the dual-pipeline routing logic, the precise meaning of could_not_verify (including verification_error{stage,detail} and the instruction that it is NOT evidence and must not be shown as one), and the distinction between unsupported vs. could_not_verify. This is exactly the kind of operational nuance an agent needs to interpret results correctly, and it complements rather than contradicts 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 longer than typical but earns its length: it packs trigger phrases, use instructions, pipeline routing, verdict definitions, error semantics, and efficiency benefits into a coherent flow. It is front-loaded with the most critical info (what it is) and organizes details logically. Could be slightly condensed, but every sentence adds value given the tool's complexity.

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

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

Despite lacking an output schema, the description provides a complete picture: all six verdict values, the inclusion of grounded/structured actual value with citation, reasoning output, and the critical error-handling semantics. It also covers the two distinct operational paths and explains when each is used. Given the tool's moderate complexity, this is thorough and self-sufficient for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by explaining the tolerance_pct semantics ('Overrides the tolerance implied by the claim wording — set 1–2 for hallucination detection') and giving concrete examples for the claim parameter. This adds decision-relevant meaning beyond the schema's basic field 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 opens with explicit trigger phrases ('Is it true that…', 'fact check', 'verify the claim that…') and states the core function: natural-language claim verification against authoritative sources. It clearly differentiates from siblings by naming the two verification paths (structured SEC EDGAR for company-financial claims, grounded pipeline for all others) and describing the verdict output.

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 whenever the agent needs to check whether something a user said is factually correct,' which is clear when-to-use guidance. It doesn't explicitly state when not to use or name a specific alternative, but it provides strong contextual cues by distinguishing claim types and noting it replaces 4–6 sequential calls, implying efficiency. A slight miss is lack of exclusionary guidance (e.g., for open-ended research instead of verification).

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