Companies House

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 value by detailing the output format (per-model score, confidence, signals, raw_response + combined view) and cost implications (default free, Anthropic requires BYO key). 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 efficiently structured: main action first, then details, then use cases. Each sentence adds value without redundancy.

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

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

Given no output schema, the description partially compensates by describing the per-model result structure. However, it lacks details on error handling, timeouts, or rate limits for external LLM calls, which would be useful for an agent. Still, for a tool of this complexity, it is reasonably 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%, so baseline is 3. The description provides overall context but does not add significant meaning beyond the existing schema descriptions for each parameter. It reinforces the usage pattern but not deeper semantics.

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

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

The description clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model, specifying default model and optional Anthropic. It does not explicitly differentiate from similar sibling tools like 'scan_competitor_ai_presence', but the specific verb+resource+outcome is clear.

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

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

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains the optional API key for Anthropic. It does not explicitly state when not to use or mention alternatives, but the context provided is sufficient for most scenarios.

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, etc. Description adds valuable context: routes to 3,436 tools across 780 sources, fills arguments, returns structured answer with permanent citation URIs. No contradiction.

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

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

Front-loaded with key instruction. Each sentence serves a purpose (domain list, capability, examples). Slightly long but effective; no wasted space.

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 6 parameters (1 required), 100% schema coverage, no output schema, the description adequately explains input and output behavior. Mentions structured answer with citations, covering the main return format.

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

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

Schema coverage is 100% with 6 parameters all described as aliases for 'question'. Description merely restates 'Your question or request in natural language', adding no extra semantics 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?

Clearly states it routes questions to a large set of verified sources and returns structured answers with citations. Specific domains and examples distinguish it from web search, making 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?

Explicitly says 'PREFER OVER WEB SEARCH' and lists many factual query types. Provides concrete examples and implies when to use (factual questions about entities, events, numbers). Strong guidance.

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

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

The description adds significant behavioral context beyond annotations: it explains the extra LLM call, the structured refusal reasons, and the extraction process. Annotations already mark it as read-only, open-world, idempotent, non-destructive, and the description complements these 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 dense yet concise, front-loading the key purpose and structured return format. Every sentence adds value, with no wasted words. It packs a lot of information into a compact paragraph.

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 completely defines the return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and failure modes. Given the tool's complexity and multiple siblings, the description is thorough and self-contained.

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

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

Schema coverage is 100% with all parameters being aliases for 'question'. The description adds minimal value beyond the schema descriptions, simply restating that aliases are accepted. Since schema does the heavy lifting, a score of 3 is appropriate.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads'. It specifies the behavior (same routing as ask_pipeworx but extracts answer only from tool result) and distinguishes it from the sibling ask_pipeworx by being more rigorous.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with specific high-stakes examples. Also advises preferring ask_pipeworx for casual lookups, providing clear usage 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?

The description is extraordinarily transparent, covering resolver confidence, fan-out behavior, edge cases (low-confidence matches, closed markets, wide spreads), news fallback mechanisms, and blocking routes. It warns agents to inspect match confidence before trusting analysis. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description adds rich behavioral context that aligns perfectly.

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: it front-loads the core purpose and input types, then proceeds to classifiers, fan-out examples, response shapes, and edge cases. While lengthy, each section earns its place, and the organization aids scanning. Minor inefficiencies exist (repetition of 'CLOSED/DEAD MARKETS'), but overall it is clear and informative.

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

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

Given the tool's complexity (multiple fan-out patterns, resolver logic, parent event extraction, news retry, safety checks) and the absence of an output schema, the description is remarkably complete. It covers all major response fields, error states, and blocking conditions, ensuring the agent can correctly interpret and trust 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?

With 100% schema description coverage, the description adds significant value beyond the schema: it explains the market parameter's accepted formats (slug, URL, question text) with examples, details the depth parameter's values, and clarifies include_raw's impact on response size. This goes beyond the baseline 3, providing practical guidance for parameter 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's purpose: to research a Polymarket bet by pulling relevant data. It specifies the input types (slug, URL, question text) and provides explicit examples of use (e.g., 'should I bet on X'). The tool's distinct function is evident even without explicit sibling differentiation.

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 concrete use cases (e.g., 'should I bet on X', 'what does the data say about Y') and explains the depth parameter for controlling scope. However, it does not explicitly state when not to use this tool or compare it to siblings like polymarket_edges, leaving some implicit differentiation.

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?

With no annotations, the description covers what data is returned for each type and mentions URIs. It does not address error handling or rate limits, but provides meaningful behavioral insight.

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

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

The description is two sentences plus a value-added line on efficiency. It is front-loaded with the main purpose and contains no fluff.

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

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

The description explains return data types and URIs but does not detail output format. Given no output schema, it covers key aspects well but could add example or structure notes.

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

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

Although schema descriptions are complete, the description adds domain-specific details (e.g., revenue for companies, adverse-event count for drugs) that explain what each type returns, enriching beyond the schema.

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

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

The description clearly states the tool compares 2-5 entities side by side, with specific metrics for each type ('company' or 'drug'). It differentiates from siblings (e.g., get_company) by offering a bulk comparison across entities.

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

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

The description implies use when comparing up to 5 entities and notes efficiency gains, but lacks explicit when-not-to-use or alternative tool references.

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

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

Discloses key behaviors: decomposition into sub-questions, parallel routing to sources, extraction of grounded answers with evidence, confidence, source, citations, and explicit gaps for unanswerable parts. Also mentions 15-60s execution time and account/plan requirements. 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 well-structured with clear sentences, but slightly verbose. Every sentence adds value, but could be tightened without losing information. Front-loading the core purpose works 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?

For a complex tool with no output schema, the description thoroughly explains what the tool does, how it works, what it returns (findings packet with citations and gaps), and constraints. This leaves little ambiguity for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra context: explains that question can be broad/multi-part and details the meaning of depth enum values (quick=3, standard=5, thorough=8) beyond the schema's generic descriptions. This provides meaningful additional guidance.

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 performs 'grounded multi-source research in ONE call' and distinguishes from sibling tool ask_pipeworx for single lookups. It provides a specific verb-resource combination and concrete examples of use cases.

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 (broad/multi-part questions) and when not to use (single lookups: use ask_pipeworx). Also mentions prerequisites (Pipeworx account, depth:'thorough' requires paid plan) and expected timing (15-60s).

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?

No annotations are provided, so the description must disclose behavioral traits. It describes a search function that returns tool names and descriptions, which implies a read-only operation. However, it does not elaborate on side effects, authorization needs, or other behaviors beyond the basic functionality.

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 consists of two concise sentences with no redundancy. The first sentence states the core function, and the second provides crucial usage guidance. Every word earns its place.

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

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

Given the tool's simplicity (two parameters, no output schema, no annotation), the description adequately covers its purpose and usage. It explains when to use it and what it returns. The return format could be slightly more detailed, but it is sufficient for an AI agent to understand.

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

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

The schema has 100% description coverage, so both parameters are already documented. The description adds no additional meaning beyond what the schema provides; it merely echoes the schema content (e.g., 'default 20, max 50' for limit). 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 'search' and the resource 'Pipeworx tool catalog', and specifies that it returns relevant tools with names and descriptions. It also distinguishes itself by advising to call it first when many tools are available, setting it apart from sibling tools that serve different purposes.

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

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

The description explicitly says 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task,' providing clear context for when to use the tool. It does not explicitly mention when not to use it or name alternatives, but the guidance is direct and helpful.

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

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

Description details behavior: fans out across multiple sources, returns specific fields, and patents endpoint soft-fails due to API sunset. Annotations already indicate readOnlyHint and idempotentHint, but description adds operational context beyond safety. No contradictions.

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

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

Description is front-loaded with examples and clear structure. While dense with information, it is slightly long but each sentence adds value. Efficient for the tool's complexity.

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

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

Given no output schema, description fully explains return values: cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI. Also covers limitations and required input format. Complete for a complex 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?

Input schema has 100% description coverage, but description adds critical guidance: pass ticker or zero-padded CIK, names not supported, use resolve_entity first. Also clarifies type enum currently only supports 'company'. Adds meaning beyond schema.

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

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

Description clearly states purpose: 'full cross-source profile of a US public company in ONE parallel call.' Includes specific examples like 'Tell me about X' and lists data sources. Explicitly distinguishes from chaining single-pack tools, differentiating from siblings like get_filings and get_company.

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: when user asks for a holistic view. Also specifies when not to use: if only a name, use resolve_entity first. Mentions soft-fail for patents. Offers clear usage context and alternatives.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true, indicating it is destructive but idempotent. The description adds context about clearing sensitive data, which is valuable beyond the annotations. 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 concise: two sentences with no unnecessary words. The primary action is stated first, followed by usage guidance and pairing, which is well-structured.

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

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

Given the simple single-parameter tool with full schema coverage and no output schema, the description sufficiently explains when to use it and how it relates to sibling tools, making it 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 a description for the 'key' parameter. The tool description does not add additional parameter information beyond what is in the schema, so it meets the baseline expectation.

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

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

The description clearly states the action ('Delete a previously stored memory by key') and distinguishes this tool from siblings by mentioning 'Pair with remember and recall', which are related but distinct operations.

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 states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also implicitly provides alternatives by pairing with 'remember and recall', guiding the agent on when to use this tool versus those.

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: it fetches the page, extracts title/description/key links, and emits standard markdown. Annotations already indicate read-only, idempotent, and non-destructive, so the description complements without contradiction.

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

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

The description is concise at four sentences, front-loaded with the primary action. Each sentence adds value: purpose, process, output format, use cases. 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?

For a simple tool with no output schema, the description adequately explains inputs and the output text blob. It covers key aspects but lacks details on error handling or edge cases like invalid URLs, which would improve completeness.

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 (url, max_links) with clear defaults and limits. The description adds no additional parameter meaning beyond restating the output format. 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 'generate' and resource 'llms.txt file for any URL', and explains the output format and use cases. It distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on generation rather than analysis.

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

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

The description lists specific use cases (indexing a client's site, drafting for own project, auditing competitor) which help an agent decide when to use it. However, it does not explicitly contrast with sibling tools or provide 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 the tool as read-only and idempotent. The description adds value by listing the specific data fields returned and mentioning links to officers/filings/charges/PSCs, which provides behavioral context beyond the annotations.

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

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

The description is two sentences, front-loads the action, and contains no unnecessary words. Every sentence adds meaningful 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 single required parameter, full schema coverage, and existing output schema, the description provides sufficient detail. It lists key return fields and linking endpoints, making the tool's behavior fully understandable.

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 the schema already describing the parameter as a UK company number. The description adds no new semantic detail about the parameter, meeting the baseline expectation.

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

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

The description clearly states 'Fetch a single UK company profile by company number,' specifying the action and resource. It distinguishes from sibling tools like 'search_companies' (searching) and 'get_filings' (specific subset), making the purpose unique.

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

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

The description implicitly conveys when to use (when you have a company number and need the profile) and is clear about the input. While it does not explicitly state exclusions or alternatives, the context of sibling tools provides differentiation.

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?

No annotations are present, so the description bears full burden. It discloses that it returns specific fields (category, description, etc.) but does not specify behavioral traits like pagination behavior (though parameters exist), rate limits, or read-only nature. Adequate but minimal beyond 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?

Description is concise (one sentence) and front-loaded with key purpose. While efficient, it could be slightly more structured by separating the purpose and returned fields. No redundant 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?

With no output schema, the description should list returned fields, which it does partially (category, description, filing date, transaction ID, links). But parameter count is 4, all described in schema. Missing details like response format or pagination metadata. Adequate but not thorough.

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 parameters are well-documented in the schema. The description adds 'accounts | confirmation-statement | officers | etc.' as category examples, but this overlaps with the schema's 'Optional filter (accounts | confirmation-statement | officers | etc.)'. No new semantic meaning beyond schema.

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

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

Description clearly states it provides filing history for UK companies, specifies types (annual returns, accounts, changes, charges, mortgages), and lists returned fields (category, description, date, transaction ID, document links). This verb+resource combination distinguishes it from siblings like 'get_company' or 'get_officers'.

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

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

No explicit when-to-use or when-not-to-use guidance is provided. While the description implies it is for retrieving filing history, it does not compare to alternatives or specify prerequisites (e.g., need a company number). Usage context is assumed but not clarified.

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?

With no annotations, the description carries the burden. It lists returned fields but does not disclose pagination behavior (start_index, items_per_page) or result ordering, which are important for a listing 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 a single sentence, front-loaded with the action, and every word is relevant. No unnecessary text.

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 covers the return fields well. However, it omits pagination details, which are relevant for a list tool with multiple pages. Still close to 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 parameter descriptions. The description adds no extra meaning to parameters beyond what the schema provides, 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 'List directors and secretaries for a UK company' with a specific verb and resource, and distinguishes itself from sibling tools like get_company and get_filings by focusing on officers.

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

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

Usage is implied by the purpose; no explicit guidance on when to use or alternatives is provided. The tool is straightforward, but the description lacks when-not-to-use or comparisons.

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 are empty, so the description must fully disclose behavior. It mentions returned fields but omits that this is a read-only operation, pagination behavior (start_index, items_per_page), or any side effects. The schema implies pagination, but the description does not confirm safety or rate limits.

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

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

The description is a single sentence that conveys the core purpose efficiently. It includes key details like output fields, but could be slightly more front-loaded with the resource name.

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

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

With no output schema, the description partially covers return fields but omits potential fields like date of birth or ceased dates. Pagination parameters are not explained in context. Adequate but not comprehensive for a 3-parameter tool.

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

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

Schema coverage is 100% (all 3 parameters described). The description adds no additional meaning beyond the schema, e.g., does not clarify that the company_number is a string of 8 characters or provide hints for start_index and items_per_page 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 returns beneficial-ownership records (PSCs) for a UK company, specifying fields returned. It differentiates from siblings like get_company and get_officers by focusing on persons with significant control.

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 no guidance on when to use this tool versus alternatives like get_officers or get_company. It does not explain prerequisites or context such as needing a valid UK company number.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds the return format (fields) but does not disclose any additional behaviors like pagination or ordering. This is adequate but not exceptional.

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 succinctly states purpose and output fields, second provides usage guidance. No wasted words, well-structured.

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

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

For a simple list tool with one optional parameter, the description covers the essential: what it returns and when to use it. Minor gaps like potential pagination or default limits prevent a perfect score.

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

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

Schema coverage is 100% with a clear description of the include_inactive parameter. The description reiterates the parameter's effect but adds no extra semantic meaning, so baseline 3 applies.

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

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

The description clearly states 'list the caller's active subscriptions' and enumerates the returned fields, making the purpose unambiguous and distinguishing it from sibling tools like subscribe/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?

It provides concrete use cases: 'review what you're monitoring before adding more' and 'find an id to cancel'. While it doesn't explicitly exclude alternatives, the guidance is clear and action-oriented.

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 are minimal (readOnlyHint false, destructiveHint false). Description adds key behaviors: rate-limited to 5 per identifier per day, free, doesn't count against quota. 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?

Single paragraph of 5 sentences, well-organized: purpose, when to use, how to write, operational details. 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?

Covers all aspects: purpose, usage, input semantics, constraints (rate limit, free). No output schema needed for feedback tool. Complete for its 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%, so baseline 3. Description adds extra semantic guidance: message should be specific, 1-2 sentences, max 2000 chars; context is optional; type enum explained. 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?

Clearly states the tool sends feedback to Pipeworx team about bugs, features, data gaps, or praise. Distinguishes from sibling tools, which are data retrieval or action tools, not feedback.

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 defines when to use (wrong data, missing tool, praise) and how to structure the message (reference tools/packs, avoid user prompt). Also mentions rate limits and that it's free.

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: source ('CF analytics-engine'), privacy ('no PII'), output structure ('pack, tool, count'), and caching behavior ('5min-1h depending on window'). Annotations already declare readOnly/ idempotent/ openWorld, and description aligns perfectly with 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?

Concise at ~100 words, front-loaded with a clear opening sentence. Uses bullet points for readability. Could slightly tighten but no unnecessary words.

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

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

For a simple read-only tool with 1 optional param and no output schema, the description fully covers purpose, usage, behavioral traits, and caching. No gaps 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 covers 100% of parameters with description for the single parameter. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps agents choose appropriately beyond the schema's enum.

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

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

Description clearly states the tool returns 'top tools, top packs, and total call volume over a recent window', with a specific verb (returns) and resource (trending usage). It distinguishes from sibling tools like discover_tools by focusing on real-time call volume rather than discovery or search.

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

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

Explicitly lists three use cases (discovering hot data, confirming canonical choice, seeing alignment) and explains window tradeoffs. Lacks explicit when-not-to-use or alternatives, but 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 indicate read-only, idempotent, open-world. Description adds substantial behavioral context: cost of partition checks, similarity thresholds, placeholder filtering, fill check logic, and the fact that opportunities may not be realizable if book depth is insufficient.

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, but is lengthy. While it contains necessary detail, some redundancy could be trimmed without losing clarity.

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

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

Covers return values (opportunities[] and partition_check details), failure modes (fill check, low similarity), and provides enough context for an agent to decide when and how to invoke the tool 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?

Both parameters are described in detail with examples and mode-specific behavior, adding significant value beyond the schema descriptions. The description explains how each parameter triggers different analysis paths.

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 via monotonicity violations and partition-sum checks, specifying two modes (event, topic) with distinct use cases.

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 requires one of event or topic, recommends which mode for which scenario, mentions sibling tool polymarket_fill_risk for custom sizing, and explains the impact of missing arguments.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds caching (1h at KV level), model family details, response structure, diagnostics, and limitations (Fed bets). No contradiction, adds substantial 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?

The description is detailed and front-loaded with purpose, then models, then response structure, then knobs. However, it is dense and long; some sentences could be tightened without losing information. Still well-structured 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?

Given 9 parameters, 3 model families, and no output schema, the description is remarkably complete. It explains response segments (by_segment), diagnostics (_diagnostics), tradeable-edge knobs, and even model formulas and limitations. Nothing essential is missing.

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

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

Schema coverage is 100% with descriptions for all 9 parameters. The description adds context for min_partition_leg_kelly, explaining why min_kelly doesn't filter partition arbs. It also clarifies slippage_pp defaults and usage. This adds meaning beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage by focusing on edge opportunities and defining three model families.

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 'Built for what should I bet on today' and explains when to use it. Tradeable-edge knobs (min_liquidity, max_spread_pp) and category_filter guide usage. It notes Fed candidates are excluded from ranking. No explicit when-not-to-use, but clear context.

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

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

The description adds significant behavioral context beyond annotations: snapshot TTL, decay computation from daily closes, gaps meaning nobody scanned, and limits on history depth. Annotations already mark it as read-only, idempotent, and non-destructive; description reinforces and details behavior.

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

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

The description is dense but well-structured: starts with the core question, then details output fields, then limits. Every sentence adds value, though it could be slightly more concise.

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

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

Despite no output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and key computed fields (trend, decay_pp_per_day, lifespan_days). It also covers historical limits and data gaps, making it complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds value by providing defaults (days default 14, window default 1wk) and clarifying the lookback clamp (2-30) and window options. This goes beyond the schema descriptions.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes from sibling polymarket_edges by focusing on persistence over time rather than just 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 implies usage via the question 'how long has this edge existed and is it shrinking?', contrasting fresh vs old edges. It doesn't explicitly state when not to use it or alternatives, but the context is clear and helpful.

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, indicating a safe, non-destructive read operation. The description adds behavioral details: walks the order book ladder, returns fill details, verdicts, and warns about unavoidable directional risk in thin baskets. No contradictions.

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

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

The description is front-loaded with the core purpose, then details each mode. It is somewhat verbose but every sentence adds value. Could be slightly more concise by merging mode descriptions, but still well-structured.

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

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

Despite no output schema, the description enumerates all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) for both modes. Parameters are fully explained with defaults and edge cases. The tool's complexity (two modes, risk warnings) is fully addressed.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema: default values, interpretation of size_usd for buys vs sells, basket mode behavior (auto side detection). It explains how parameters interact with each other and the two modes.

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

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

The description starts with a clear verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It explicitly distinguishes single-market and basket modes, differentiating 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?

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains consequences of not using it (partial fills convert arb to directional position), providing clear context.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds detailed behavioral context: two operating modes, response structure, safety fields (compatibility_warning, temporal_alignment, counters for dropped comparisons), and explains limitations extensively.

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

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

The description is dense with useful information but slightly long. It is well-structured: starts with high-level purpose, then modes, response fields, and safety details. Every sentence adds value, but minor trimming could improve conciseness.

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 thoroughly explains the response structure (leg prices, spreads, compatibility_warning, temporal_alignment, counters). It covers all aspects an agent needs to handle the tool correctly 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 has 100% coverage with descriptions for all three parameters. The description adds value by explaining the interplay between parameters (topic vs explicit override), listing the 10 pre-mapped topic values, and providing example tickers for explicit mode.

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 distinguishes from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on cross-venue comparison.

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 describes two modes (topic shortcuts vs explicit tickers), warns that most pre-mapped topics currently return compatibility warnings, and explains when spreads are meaningless (temporal misalignment, incompatible bet shapes). Clear when to use and when not.

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, making the safety profile clear. The description adds behavioral context beyond annotations: scoping to user identifier (anonymous IP, BYO key hash, account ID), the ability to list keys when no argument is provided, and the relationship with companion tools. 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 extremely concise, covering functionality, use cases, scope, and companion tools in just a few sentences. Every sentence adds value with no redundancy. It is front-loaded with the core operation and efficiently expands on important details.

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

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

Given no output schema, the description explains what the tool returns (a value or list of keys). It also addresses scope (user identifier) and companion tools. However, it does not specify the data type of stored values or any formatting details for keys. For a simple key-value retrieval, this is nearly complete, though slightly lacking in return format specification.

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 'key' with 100% description coverage, so baseline is 3. The description reiterates that omitting the key lists all keys, which is already in the schema description. It does not add new semantic details like expected key format, value types, or case sensitivity. The schema adequately documents the parameter.

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 dual functionality: retrieving a specific saved value or listing all keys. It uses strong verbs ('Retrieve', 'list') and specifies the resource ('value previously saved via remember'). It also distinguishes itself from siblings by naming 'remember' and 'forget' as companion 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 explicitly tells when to use this tool: 'to look up context the agent stored earlier... without re-deriving it from scratch.' It also mentions pairing with 'remember' and 'forget' for save/delete operations. However, it does not explicitly contrast with other data retrieval tools among siblings (e.g., 'search_companies'), but given the nature of memory storage, that is implied.

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, ensuring the agent knows it's a safe, repeatable read operation. The description adds valuable behavioral context: setting mark_read to true affects future calls by marking events as read, and mentions polling is safe. 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 a single paragraph of 4 sentences, starting with the main purpose and then covering details. It is concise without being overly brief, and front-loads the key action. Each sentence adds value, though the mention of the GET endpoint could be considered slightly tangential. Overall well-structured.

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

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

Given the lack of an output schema, the description adequately explains the return format (source, citation_uri, raw payload). It covers all parameters with examples, mentions behavior of mark_read, and even provides an alternative access method. No significant gaps remain for an agent to understand the tool's behavior and input/output.

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

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

All 5 parameters are documented in the input schema with descriptions (100% coverage). The tool description adds further meaning beyond the schema: it illustrates filter examples (e.g., type 'sec_8k'), clarifies that 'since' expects an ISO timestamp, and explains the side effect of mark_read (so next call shows only newer ones). This enriches the agent's understanding.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', indicating the tool retrieves recent alerts. It provides specific details about the returned fields (source, citation_uri, raw event payload). However, it does not explicitly differentiate from sibling tools like 'recent_changes' or 'list_subscriptions', missing a chance to clarify its unique role.

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

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

The description mentions that 'Polls work fine' and provides an alternative GET endpoint for scripts/dashboards, offering some usage context. However, it lacks explicit guidance on when to use this tool versus other similar tools (e.g., for filtering vs. subscription management), and does not state conditions where the tool should not be used.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and no destructiveness. Description adds specifics: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO with sunset caveat, and fallback mechanism. No contradictions.

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

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

Description is moderately long but well-front-loaded with usage examples. Every sentence adds unique value. Slightly verbose but not wasteful. Could be more concise, 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 mentions return structure (grouped changes, count, URIs). Covers fallback behavior and source specifics. All required parameters are well-described. Complete for a complex fan-out tool.

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

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

Schema coverage is 100%, but description adds significant meaning: explains `since` accepts ISO or relative shorthand with examples, suggests typical values, explains `value` as ticker or CIK, and re-emphasizes `type` as only 'company'.

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 is a change feed for a company over time, fanning out to multiple sources. It distinguishes from sibling tool 'entity_profile' which provides static profiles. Specific verb+resource+scope.

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 (dynamic changes over time) and when-not-to (static profile via entity_profile). Provides example queries and typical monitoring suggestion ('30d' or '1m').

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?

Disclosures beyond annotations: key-value scoping by identifier, persistence differences (authenticated vs anonymous), and pairing. No contradiction with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true).

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 usage and details. Every sentence adds value with no redundancy.

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

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

Covers purpose, usage, scope, persistence, and sibling pairing. No output schema needed; description is sufficient for a simple write tool.

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

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

Schema covers both parameters fully with descriptions. Description adds practical examples (e.g., 'subject_property', 'target_ticker') and clarifies value type ('any text'), enhancing 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 states a specific verb ('Save') and resource ('data the agent will need to reuse later'), clearly distinguishing it from siblings like '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?

Explicitly says when to use ('when you discover something worth carrying forward...') and pairs with recall and forget, providing clear context for choosing this tool over 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 indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that each call cascades through several lookup endpoints internally, how auto-disambiguation works for companies, and specifies the return fields including citation URIs. This goes well 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 examples and bullet points. It front-loads the purpose with natural language queries. While slightly lengthy, every sentence adds value, making it appropriately detailed without being overly verbose.

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

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

Given the lack of output schema, the description thoroughly explains return values for both entity types, including citation URIs. It covers input examples and auto-disambiguation. It does not explicitly address error cases (e.g., ambiguous name), which is a minor gap, but overall it is comprehensive.

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

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

Schema coverage is 100%, but the description adds meaningful examples for each parameter (e.g., 'ticker (AAPL), CIK (0000320193), or name' for company value). It also explains auto-disambiguation and what each type returns, enhancing understanding beyond the schema.

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

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

The description clearly states that the tool resolves user-spoken names to canonical identifiers, with specific examples like 'ticker for...' and 'CIK for...'. It distinguishes itself from sibling tools by positioning as the first step when you have a name but need an ID, and it mentions replacing 2-3 manual 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 'Use FIRST whenever you have a name but need an ID', providing clear context for when to use. It details supported types (company, drug) and what they return. However, it does not explicitly mention when not to use or provide alternatives among the many sibling tools.

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

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

Annotations indicate readOnly/openWorld/idempotent. Description adds internal process details (probes with ai_visibility_check, ranks, returns score/confidence/density). 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: main action, process, and example use case. Every sentence earns its place, front-loaded with 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?

No output schema, but description explains return type (ranked list with score/confidence/signal density). Covers model options and context parameter. Lacks error handling details but sufficient for a non-destructive 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 adds value by noting first entity is treated as subject and clarifying model omission defaults to workers-ai.

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

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

The description clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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 a clear use case ('competitive AI-marketing audits') but does not explicitly exclude alternatives. However, sibling tool names provide contextual differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds critical behavioral context: composite fan-out to two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timed-out sources. 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 and front-loaded with purpose and usage. Every sentence adds value, though it could be slightly more concise. It is well-structured for its length.

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

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

Despite no output schema, the description fully explains the return: summary block, per-advisory detail, links, and recent alternative versions. Also covers partial failures. Complete for this low-complexity tool.

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

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

Schema coverage is 100% with both parameters described. The description adds value by noting that scoped packages are accepted and that version defaults to latest when omitted.

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 a composite check for adding an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from siblings by specifying NPM only in v1 and contrasting with other ecosystems via deps.dev:version 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 provides usage scenarios: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also mentions NPM only v1 and alternative approaches for other ecosystems.

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

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

No annotations are provided, but the description is straightforward for a read-only search tool. It does not disclose any potential behavioral traits such as rate limits, authentication requirements, or data freshness, which would be useful for an agent.

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 two sentences: the first states the purpose and output, the second provides actionable guidance. No superfluous words.

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

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

Given no output schema, the description adequately lists return fields and suggests next steps. It covers the necessary information for a simple search tool, though it could mention default pagination.

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 overall context but does not elaborate on parameter usage beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool searches UK Companies House by company name, specifying the returned fields (company number, name, status, etc.). It distinguishes from sibling tools like get_company which look up by company number.

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

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

The description provides guidance on using the result (company_number) for further lookups, indicating how to proceed after a search. However, it does not explicitly state when to use this tool versus alternatives like get_company or when not to use it.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds concrete details: embeddings (BGE-base-en), window size (500-char), cap (200K chars with truncation flag), output includes offsets and scores.

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

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

Single dense paragraph, no fluff. Could benefit from bullet points or section headers, but efficient and front-loaded with key verb and resource.

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, description explains return format (top-N passages with offsets and scores) and constraints (cap, truncation). All relevant user-facing behavior is 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?

Schema coverage is 100%, baseline 3. Description adds query examples, clarifies limit range (1-20, default 5), and notes text max (~200K chars), adding value beyond schema.

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

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

Description starts with 'Semantic search INSIDE a fetched record', clearly specifying verb and resource. It distinguishes from sibling tools like ask_pipeworx_grounded, and uses capitalization for emphasis.

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

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

Explicitly tells when to use ('record too big to cram into the prompt') and mentions pairing with ask_pipeworx_grounded. Lacks explicit when-not-to-use, but context is clear.

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

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

The description says 'Returns the new subscription id,' implying each call creates a distinct subscription, contradicting the idempotentHint=true annotation which suggests identical requests yield the same result. This is a serious inconsistency. The description does add other behavioral details (SMS cap, phone verification) but fails to disclose idempotency 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 long but well-structured with clear sections for types and delivery channels. Each sentence adds specific, non-redundant information. It could be slightly more concise by removing minor details like phone number format, 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?

For a creation tool with no output schema, the description provides complete context: return value ('new subscription id'), account requirements, type options with detailed params, delivery channels with constraints, and verification steps. Nothing critical is missing.

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

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

Schema coverage is 100%, and the description adds extensive meaning beyond the schema: per-type param examples (e.g., sec_8k: items codes), delivery channel constraints (SMS cap, webhook signing), and account requirements. This fully compensates for any schema brevity.

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: 'Create a proactive monitoring subscription to a live-data event stream.' It distinguishes from siblings like list_subscriptions and unsubscribe by focusing on creation. The verb 'Create' and resource 'subscription' are specific and unambiguous.

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

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

The description provides explicit usage context: requires a Pipeworx OAuth account (anonymous/BYO cannot persist). It explains supported types and delivery channels with examples. However, it does not explicitly state when not to use this tool versus alternatives (e.g., for querying alerts use recent_alerts), though the sibling list implies separation of concerns.

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, non-destructive behavior. The description adds valuable context about the return format (category-bucketed example questions) and source (live catalog). 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 front-loaded with common user queries and is appropriately detailed for an onboarding tool. Every sentence adds value, though it could be slightly more structured to improve scannability.

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

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

Despite no output schema, the description fully explains the return value: category-bucketed example questions with exact tool+argument shapes. This is complete for the tool's onboarding purpose, and the param details are sufficient.

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 one optional parameter. The description adds meaning by listing possible values (finance, pharma, etc.) and explaining that omitting it gives a cross-category spread, going beyond the schema's 'Optional focus area' description.

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

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

The description clearly states the tool's purpose as the onboarding entry point, answering 'What can I ask Pipeworx?' and providing category-bucketed example questions with tool+argument shapes. It distinguishes itself from sibling tools like discover_tools by explicitly stating 'Use this FIRST when you do not yet know what Pipeworx can do for you.'

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

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

The description gives clear guidance: 'Call with no arguments for the full spread, or pass topic to focus.' It also advises using this tool first for onboarding or learning meta-tools. While it doesn't explicitly list when not to use it, the context is sufficient for an entry-point 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?

Adds beyond annotations: ownership enforcement, deactivation not deletion, historical events stay via recent_alerts. 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?

Two concise sentences, front-loaded with purpose, then details. No wasted words.

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

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

Complete for a simple tool: explains effect, ownership, relation to recent_alerts. No missing info given annotations and single parameter.

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

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

Schema coverage 100% with id described as uuid returned by subscribe. Description adds 'by id' but no additional syntax 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?

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

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

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

Explicitly mentions ownership enforcement (only cancel own subscriptions) and deactivation rather than deletion. Lacks explicit alternatives but provides clear context.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by detailing return values (verdict, structured form, actual value with citation, percent delta) and noting the efficiency gain (replaces 4-6 calls). It does not disclose rate limits or auth requirements, but the domain limitation is stated.

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

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

The description is front-loaded with trigger phrases, followed by purpose, domain, returns, and efficiency note. While it is a paragraph, every sentence adds value. Could be slightly more concise but is well-structured.

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

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

Given the tool has one well-documented parameter and annotations covering safety, the description is mostly complete. It explains output and domain scope. However, it lacks mention of error cases (e.g., unsupported company, invalid claim format), which would be helpful.

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

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

Schema coverage is 100% with a description for the 'claim' parameter. The description adds meaning beyond the schema by providing example claim formats and confirming the supported domain (company-financial claims), helping the agent format valid inputs.

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 common query phrases and clearly states 'natural-language claim verification against authoritative sources.' It specifies the domain (company-financial claims) and distinguishes itself by noting it replaces 4-6 sequential calls, differentiating it from sibling tools like resolve_entity or search_companies.

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

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

The description gives clear usage context: 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides example phrasing and domain constraints (company-financial claims via SEC EDGAR + XBRL). However, it does not explicitly state when not to use it or name alternative tools for out-of-scope claims.

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