Open Corporates

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the tool's safety profile is clear. The description adds value by explaining the cost implications (free default vs. paid Anthropic) and that results include per-model details plus a combined view, which goes beyond annotations.

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

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

The description is concise: two main sentences plus a usage sentence, front-loaded with the core action. Every sentence contributes value, no fluff, and the structure is clear.

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

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

Despite lacking an output schema, the description outlines the return format (per-model fields + combined view). It covers all parameters and their roles. While it doesn't mention limits on models or pagination, the tool is simple enough that this information is not critical for correct invocation.

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

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

Schema coverage is 100% with good descriptions for each parameter. The description enhances this by clarifying the default model, the need for _apiKey only for Anthropic, and the purpose of the context parameter for disambiguation, adding meaningful guidance beyond the schema.

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

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

The description clearly states the tool's function: probing LLMs for brand visibility and scoring it (0-100). The verb 'probe' and resource 'LLMs for visibility' are specific, and the tool is well-distinguished from siblings like 'deep_research' or 'ask_pipeworx' which focus on different queries.

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

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

The description provides context for use (AI-marketing audits, pre-launch checks, competitive monitoring) and mentions the default model and optional BYO key for Anthropic. However, it does not explicitly state when not to use this tool versus alternatives, which would strengthen 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 read-only, open-world, idempotent, and non-destructive behavior. The description adds context about routing to 5,462 tools, filling arguments, returning pipeworx:// citations, and being fast. This enriches the behavioral model beyond annotations, though it doesn't discuss failure modes or data freshness.

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

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

The description is lengthy but well-structured: it opens with a strong recommendation, lists supported domains, explains the mechanism, provides usage triggers, examples, and alternative tool guidance. Every sentence serves a purpose, though it could be trimmed without losing core value.

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

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

Given the tool's complexity and the absence of an output schema, the description adequately communicates that results are structured with citation URIs. It also covers practical aspects like tier availability and call speed. Lacking only detailed return format specifics, but the description provides enough for an agent to understand the tool's role.

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

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

Schema coverage is 100% for the question parameter and its aliases. The description complements the schema by providing concrete example questions and noting that the tool 'fills arguments,' implying the input is a natural language query that the tool interprets. This adds operational meaning beyond the schema's terse descriptions.

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

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

The description clearly states the tool's purpose: it routes factual questions to appropriate data sources and returns structured answers with citations. It explicitly distinguishes itself from web search and sibling tools by framing it as the default entry point and listing specific data domains (SEC filings, FDA data, etc.).

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

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

The description provides explicit guidance on when to use this tool: for any factual question about real-world entities, even if web search could answer it. It also names alternatives and when to 'step up' to ask_pipeworx_grounded or deep_research, plus clarifies that breaking news is already covered.

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

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

The description discloses key behavioral traits beyond the annotations: it is an experimental version with live candidate routing that may change behavior, and it is fully functional ('this IS a full working router'). The note about the last candidate being retired on 2026-07-26 provides specific context about its current equivalence to the stable tool. This adds significant value beyond the readOnly/idempotent hints.

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

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

The description is structured and front-loaded with the key identification ('Beta version of ask_pipeworx'). It is somewhat wordy, with redundancy between 'identical universal router' and 'this currently matches ask_pipeworx exactly', but every sentence contributes to understanding the tool's purpose and usage. It earns a solid 4.

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

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

Given the tool's moderate complexity (one main question parameter, no output schema, rich annotations), the description fully covers the context: what the tool is, its relationship to ask_pipeworx, when to use it, and its experimental nature. The phrase 'same response shape' references the stable tool to clarify returns, making the description complete for an agent.

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

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

The schema already provides 100% description coverage for all 6 parameters (all aliases for 'question'). The tool description itself adds no parameter-specific information beyond stating it has 'same arguments' as ask_pipeworx, which is not needed since the schema fully documents the parameters. Baseline of 3 is appropriate.

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

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

The description immediately identifies the tool as a beta version of ask_pipeworx, a universal router with the same tools and arguments. It explicitly states the tool's function with a specific verb and resource, and distinguishes it from the stable sibling by highlighting the experimental routing improvements. The phrase 'identical universal router... with candidate routing improvements enabled live' clearly conveys purpose and 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?

The description provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It clarifies the current state (matches ask_pipeworx exactly) and explains how results are used (compared against stable router). This tells users when to choose this beta over the stable variant, satisfying the 'when to use vs alternatives' criterion.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses key behavioral traits: it extracts answers 'using ONLY what the tool result contains,' returns an explicit refusal with specific reasons like 'not_in_source' and 'data_truncated,' and incurs an additional LLM call. This adds meaningful context that annotations do not convey.

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 front-loaded with the most critical concept ('Hallucination-resistant answer mode'), then systematically covers routing, extraction, return shape, refusal reasons, use cases, and cost tradeoff. Every sentence contributes necessary information with no filler.

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

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

With no output schema, the description fully explains return values: {answer, evidence, confidence, source, fetched_at, refusal_reason} and all refusal reason strings. It also covers the tool's routing behavior, the grounding constraint, when to use it, and its relation to the sibling tool, making the context complete for correct invocation.

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

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

Schema coverage is 100% and the only real parameter is 'question' with five aliases, each described as an alias. The description does not add detail beyond the schema (e.g., question format or constraints), but none is needed since the parameter is self-explanatory. 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 opens with 'Hallucination-resistant answer mode for high-stakes reads' and clearly states the action: it picks the right tool, fetches data, and extracts the answer using only the tool result. It explicitly differentiates from the sibling ask_pipeworx by noting it is the same routing but with grounded extraction, and it names ask_pipeworx as the alternative for casual 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 gives explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also provides a when-not-to-use with a cost tradeoff: 'Costs one extra LLM call vs ask_pipeworx — prefer ask_pipeworx for casual lookups.'

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description fully discloses behavioral traits: resolver confidence levels, short-circuit conditions for low-confidence/closed markets, tradeability warnings for wide spreads, and cancellation rule parsing. No contradictions with annotations observed.

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

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

The description is structured with clear section labels but is overly long (700+ words). It contains many examples that, while informative, contribute to verbosity. A more concise version retaining core details would be more effective.

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

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

For a tool with three parameters, no output schema, and rich annotations, the description is exceptionally complete. It covers input formats, response shapes, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety mechanisms. No significant gaps are present.

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

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

The input schema covers all three parameters with descriptions, achieving 100% coverage. The tool description adds value by clarifying the market parameter's input forms (slug, URL, question text) and providing examples for depth and include_raw. While not essential, these additions enhance 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 the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research with data pull), and differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on bet-specific research. The 'Use for' line further clarifies appropriate queries.

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 examples such as 'should I bet on X' and 'what does the data say about Y,' and includes detailed fan-out examples for different bet types. However, it does not explicitly state when not to use this tool or exclude alternatives, leaving some ambiguity relative to siblings like validate_claim.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral details: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, specific financial metrics, sorting by primary metric, and citation URIs. No contradictions.

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

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

The description is a single paragraph with front-loaded example queries. It is concise given the amount of information, but the structure could be slightly improved with bullet points or clearer separation. Every sentence adds value.

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

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

With 2 parameters, high schema coverage, and annotations, the description covers input formats, data sources, sorting behavior, and output characteristics (paired data, citations). No output schema exists, but the description adequately replaces it.

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

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

Schema coverage is 100%, baseline 3. Description adds meaning: explains what each type pulls (company vs drug data), and for the values array, specifies format (tickers/CIKs for company, names for drug). This goes beyond the schema's basic descriptions.

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

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

The description uses specific verbs and resources: 'side-by-side comparison of 2–5 companies or drugs'. It lists example queries and explicitly distinguishes from siblings by stating 'ALWAYS PREFER over sequential single-pack lookups'.

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

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

The description clearly states when to use this tool (comparison queries like 'compare X and Y') and what to prefer it over (sequential lookups). However, it does not explicitly list when not to use it.

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

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

The description far exceeds the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by disclosing account/depth requirements, gap handling ('never invented'), second-hop iteration, contradiction scanning, semantic excerpting, resolvable citation URIs, and latency expectations. No annotation contradiction exists.

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

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

The description is long but dense with actionable detail for a complex tool. It front-loads the account prerequisite and follows with purpose, usage boundaries, and return semantics. Slight redundancy (e.g., repeated mention of gaps and citations) prevents a 5, but every sentence contributes 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?

Without an output schema, the description fully explains the return value structure: findings packet with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop, and citation_uri. It also covers timing, account requirements, source coverage, and alternatives, making it complete for a tool of this complexity.

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

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

Schema coverage is 100% and both parameters are already well-described. The description adds value by explaining the practical meaning of depth values (quick=3, standard=5, thorough=8) including the extra hop and contradictions behavior, and notes that 'thorough' requires a paid plan—information not in the schema.

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

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

The description uses a specific verb ('researches') and resource ('Pipeworx's 1419 STRUCTURED data sources'), clearly distinguishing it from siblings. It explicitly states it decomposes questions into facets and routes to 5,462 tools in parallel, and even contrasts with ask_pipeworx for single lookups and current-news topics.

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

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

Provides explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). Also notes account/depth prerequisites and alternatives across tiers.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context: returns schemas with examples and that results are ready to call directly. It does not contradict 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?

Extremely concise: 3 sentences plus a list of domains. Each sentence adds value: purpose, examples, return format and usage advice. No wasted words.

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

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

For a meta-tool with simple parameters and no output schema, the description fully covers what it does, what it returns, and when to use it. No gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add significant parameter-level detail beyond the schema, though the schema's examples and the description's domain list provide context for the query 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 'Find tools by describing the data or task' and lists many domains, making the purpose specific and well-defined. It distinguishes itself from sibling tools by being a meta-tool for discovery.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear when-to-use guidance and implies when not to use (if tool is already known).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds useful context about USPTO sunset and soft-failure, and explains data 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 well-structured with purpose, guidelines, and data breakdown. It is somewhat verbose but front-loads critical info. A slight trim 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?

Given complexity (multiple data sources, 2 params, no output schema), the description covers return fields, limitations, fallback behavior, and prerequisites. 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%, so baseline 3. The description adds value by explaining that type is only 'company' for now, value must be ticker or zero-padded CIK (not name), and provides examples.

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

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

The description clearly states the tool's purpose: 'full cross-source profile of a US public company in ONE parallel call.' It lists data sources and return fields, and distinguishes from siblings like resolve_entity.

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

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

Explicit guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also warns that names are not supported and directs to use resolve_entity first.

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. The description adds context about clearing sensitive data and deleting by key, but does not contradict annotations. Gives slight added value.

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

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

Two concise sentences. First sentence states action and resource, second provides usage guidance. No wasted words.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, usage, and behavioral implications sufficiently.

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 only parameter 'key' is described in the schema as 'Memory key to delete'. The description repeats this without adding new semantics, so baseline 3.

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

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

The description clearly states 'Delete a previously stored memory by key' with a specific verb and resource. It distinguishes from sibling tools by naming 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with 'remember' and 'recall', providing clear 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?

Description details behavior (fetches page, extracts title/description/key links, emits markdown format) beyond annotations (readOnly, idempotent). No contradictions. Adds value by explaining the output.

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, front-loaded with purpose, followed by method and use cases. No redundant sentences. 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 no output schema, description adequately describes output as a single text blob. For a simple generation tool with read-only, idempotent annotations, it covers key aspects. Minor lack of error/edge case info, but acceptable.

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 covers both parameters with descriptions (100% coverage). Description does not add new information about parameters beyond reinforcing the URL purpose. Baseline 3 as schema does the heavy lifting.

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

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

Description clearly states 'Generate a production-ready llms.txt file for any URL', specifying the verb and resource. It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on llms.txt generation.

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

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

Explicitly lists use cases: getting client's site indexed, drafting own llms.txt, auditing competitors. While no exclusions or alternatives are given, the guidance 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 cover readOnlyHint, idempotentHint, and destructiveHint. The description adds useful context about authentication requirements and the types of data returned, but does not disclose rate limits or other potential behavioral nuances. With annotations providing the safety profile, the description's additional context earns a 3.

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

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

The description is two sentences plus an example, conveying all necessary information without redundancy. It is front-loaded with the primary action and clearly 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 presence of an output schema, the description appropriately lists returned data types (registration details, officers, filings, industry codes) without duplicating schema content. This is sufficient for the tool's moderate 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 the parameter descriptions are already complete. The description provides an example call with specific values and lists jurisdiction examples, but this adds limited new semantic meaning beyond the schema baseline of 3.

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

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

The description uses a specific verb ('Get') and resource ('company'), clearly identifying that it retrieves full details for a specific company by jurisdiction and number. It distinguishes from search tools like search_companies by focusing on a single entity lookup.

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

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

The description explicitly states the requirement for an OpenCorporates API token and warns that keyless calls return 401, providing clear context for when this tool should be used. It does not, however, explicitly mention when not to use it or name alternatives, but the prerequisite is well-covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds return fields and default behavior (active only, with optional include_inactive). No contradictions.

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

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

Two sentences, front-loaded with the main purpose, and no extraneous 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 list tool with 1 optional parameter and no output schema, the description fully covers return fields and use case, matching the 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 is 3. The description does not add details about the 'include_inactive' parameter beyond what the schema provides, but the usage context indirectly clarifies its purpose.

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 return fields. It distinguishes from sibling tools like 'subscribe' and 'unsubscribe' by focusing on listing.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' While it doesn't state when not to use, the 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?

All annotations are false (readOnlyHint=false, etc.), so the description carries the burden of behavioral disclosure. It adds valuable details like 'Rate-limited to 5 per identifier per day' and 'Free; doesn't count against your tool-call quota,' and explains the feedback loop ('team reads digests daily'). It doesn't mention potential side effects (e.g., permanence of the message), but covers the most important operational behaviors.

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

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

The description is longer than average, but every sentence packs meaning: it covers the tool's purpose, triggers, scope limits, content guidance, rate limit, and quota behavior. It opens with the core action and then layers usage rules. A few sentences could be tightened (e.g., 'Not sure? Pipeworx tool names are the ones this connection lists.'), but overall it's efficient for the complexity it handles.

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

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

For a feedback tool with an enum, nested context object, and no output schema, the description fully covers the decision space: what types of feedback are accepted, which tools/packs are in scope, how to phrase content, and operational constraints (rate limit, quota). There is no missing critical context for an agent to select and invoke this tool correctly.

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

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

Input schema coverage is 100%, so the baseline is 3. The description adds above-baseline value by expanding on the `type` enum with real-world interpretations (bug = wrong/stale data, feature = new tool) and by instructing the agent on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This contextualizes the parameters beyond the raw 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 opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete trigger conditions (bug, feature/data_gap, praise), making it unmistakably distinct from sibling tools like ask_pipeworx or discover_tools. The scope restriction to Pipeworx tools further clarifies exactly what this tool is for.

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

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

The description provides explicit when-to-use guidance ('Use when a tool returns wrong/stale data', 'when a tool you wish existed isn't in the catalog', 'when something worked surprisingly well'). It also gives a clear exclusion: do NOT use for tools from other MCP servers, and directs the agent to 'file it with that server instead.' This is textbook usage-rule clarity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: caching behavior (5min-1h), source derivation (CF analytics-engine, no PII), and self-aggregating signal, which goes beyond annotations.

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

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

The description is concise at five sentences, uses bullet points for use cases, and every sentence adds value. No redundancy or wasted words.

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

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

For a tool with one optional parameter and no output schema, the description covers return values (top tools, packs, volume), caching, and purpose. It is complete for an agent to understand usage and expectations.

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 defines the 'window' parameter with enum and description. The description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand,' providing additional decision-making guidance 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 returns top tools, top packs, and total call volume over a window. It distinguishes itself from sibling tools by focusing on aggregated agent activity, which is unique among the listed siblings.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical tool, and seeing alignment. While it doesn't explicitly state when not to use, the use cases are clear and practical.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true. Description adds beyond: explains fill check (theoretical vs realizable edge, do not trade if edge ≤0), semantic anchor (Jaccard similarity), and partition filter. 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?

Well-structured with sections but slightly verbose. Every sentence adds value; front-loaded with main purpose. Minor redundancy (e.g., 'partition_check' explained twice), but still highly 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 fully covers response fields (opportunities[], partition_check{}, fill check results). Includes edge cases (placeholders, similarity filter) and references sibling tool for custom sizing.

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%, but description greatly enriches: explains event slug examples, topic seed questions, full URL acceptance, and mode behavior. Adds context beyond schema parameter 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 finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes modes (no args, event, topic) and contrasts with siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly recommends when to call with no args, event, or topic. Explains trade-offs (cross-event catches missed patterns) and references polymarket_fill_risk for custom sizing, providing clear usage guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the description need not reiterate safety. It goes far beyond, detailing caching behavior (1h KV-level), edge computation methodology, response structure, diagnostic output, and warnings about edge already priced in. This is exemplary transparency.

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

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

The description is lengthy but well-structured: high-level purpose first, then model family details, response fields, diagnostics, and caching. Every sentence earns its place for a complex tool, though it could be slightly trimmed without losing substance.

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

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

With no output schema, the description fully compensates by detailing the response structure: by_segment segments, fed_candidates/fed_note, and _diagnostics. It also explains edge calculations, filter knobs, and tradeable-edge knobs, making the tool's behavior entirely predictable to an agent.

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

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

Schema coverage is 100%, but the description adds significant context beyond schema descriptions. For example, it explains the rationale behind slippage_pp (Polymarket zero fees but bid/ask costs) and why min_partition_leg_kelly exists when min_kelly does not apply. This adds meaning for effective agent use.

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 ('Scan') and resource ('Polymarket markets'), stating it returns opportunities where data disagrees with market price. It explicitly frames the tool for the use case 'what should I bet on today', distinguishing it from siblings like polymarket_arbitrage which focus on different mechanisms.

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

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

The description provides clear context for when to use the tool ('discover opportunities without paging hundreds of markets') and describes three model families and their conditions. It does not explicitly state when not to use it or compare with alternatives, but the intent is well-communicated.

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

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

Annotations (readOnlyHint, idempotentHint) are reinforced by description. Adds critical behavioral details: 60-day snapshot TTL, decay from daily closes not intraday, gaps mean no scan, history bounded by snapshot enablement. Response structure thoroughly explained.

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

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

Description is efficient but detailed. Front-loads the key question and then lists args and response. Every sentence is informative, though slightly verbose. Could be tightened without loss.

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 fully explains response fields (tracked, expired, snapshot_dates) and constraints (TTL, decay limitations). Covers all needed context 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% with descriptions, so baseline is 3. Description adds default values, clamp ranges, and clarifies 'window' as snapshot family. This extra context justifies a 4.

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

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

Description clearly states verb 'track' and resource 'edge persistence and decay' from snapshots. Directly answers the core question 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like 'polymarket_edges' by focusing on temporal 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?

Implied usage for analyzing edge history and decay trends. Does not explicitly state when not to use or list alternatives, but context makes it clear this is the tool for temporal edge analysis. Slight gap in explicit 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 indicate read-only, idempotent, non-destructive behavior. The description adds rich details on return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and warns about partial fills converting arb to directional positions, going 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?

Description is dense but front-loaded with purpose, then structured into single-market and basket sections. Every sentence adds value; could be slightly more concise but not wasteful.

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

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

Given complexity of two modes, four parameters, and no output schema, the description covers return fields for both modes, edge cases (thin legs), and risks (partial fills). It is fully adequate for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant context: explains size_usd meaning per mode (spend/proceeds vs settlement notional), side defaults and behaviors, and parameter conditions, justifying a score above baseline.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It specifies two modes (single-market and basket), uses specific verbs and resources, and is well-differentiated 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?

Explicitly says 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Provides rationale about uncapturable overround and partial-fill risks, giving clear when-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 readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds substantial behavioral context: explains internal logic for compatibility_warning (two distinct failure modes), temporal alignment details, skipped_cross_type/subtype counters, and the fact that pre-mapped shortcuts may not yield tradeable spreads. 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 approximately 300 words and quite verbose. While it uses ALL CAPS headings for structure, key information (two failure modes, temporal alignment, pre-mapped caveat) is buried in a dense wall of text. A more structured, front-loaded format would improve usability.

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 (no output schema, three parameters, intricate internal matching logic), the description covers essential behavioral context: two modes, compatibility_warning cases, temporal alignment, and skipped comparison counters. Lacks exact response format but includes a 'RESPONSE:' section that partially addresses this. Mostly complete for effective use.

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

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

Schema coverage is 100% with each parameter well-described in the schema. The description adds value by listing all 10 topic values and explaining override behavior for kalshi_event_ticker/polymarket_event_slug, but this is modest additional context beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool computes cross-venue spreads between Kalshi and Polymarket for the same resolving question, explains two modes (topic shortcuts vs explicit tickers), and distinguishes it from siblings like polymarket_arbitrage by focusing specifically 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?

Provides explicit guidance on when to use each mode, explains the two compatibility_warning cases with concrete interpretations, warns about temporal alignment prerequisites, and explicitly cautions that most pre-mapped topics are not tradeable today. This prevents misuse and sets realistic expectations.

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

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

Annotations already indicate readOnly and idempotent behavior. The description adds useful context about scoping (anonymous IP, key hash, account ID) beyond annotations. No contradictions.

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

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

Three sentences, front-loaded with main action, no redundant words. Well-structured and 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 simple tool with one optional parameter and no output schema, the description covers purpose, usage scope, and relationships with siblings completely. No gaps.

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

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

Schema coverage is 100% and already describes the 'key' parameter including the 'omit to list all keys' behavior. The description adds minimal new information about the parameter beyond usage context.

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

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

The description clearly states the tool retrieves a saved value or lists all keys, with specific verbs 'retrieve' and 'list'. It also differentiates from siblings 'remember' and 'forget' by mentioning them.

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

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

The description explains when to use the tool ('look up context stored earlier') and mentions pairing with other tools, but does not explicitly state when not to use it. Context about scoping to identifier is provided.

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

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

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds the nuance that mark_read:true modifies state (flags events read), which is non-destructive but not purely read-only. This adds value beyond annotations.

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

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

Three sentences, each packed with distinct value: purpose, return format, filtering, state-modifying behavior, and alternative access. 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 5 parameters, return format, behavioral nuance (mark_read), and even an alternative access method. No output schema, but description sufficiently explains what is returned.

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 behavioral semantics (e.g., mark_read 'flag returned events read so the next call only shows newer ones') and practical usage tips beyond the schema's descriptions.

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

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

The description uses a specific verb ('Pull') and resource ('fired events from your subscription feed'), clearly distinguishing this read tool 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?

Explains how to filter by type and since, mentions polling works fine, and provides an alternative access method (GET registry.pipeworx.io/alerts.json). 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 rich behavioral context beyond annotations: fan-out to multiple sources, fallback logic, USPTO soft-fail due to API sunset, return format (grouped changes, count, citation URIs). This fully informs the agent of the tool's behavior and limitations.

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 dense paragraph but remains front-loaded with examples and key capabilities. Every sentence adds value. A minor improvement would be to break into sections, but it is still efficient and clear.

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

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

Given the tool's complexity (multiple data sources, fallback, parameter nuances) and no output schema, the description is remarkably complete. It covers return format, source behavior, parameter syntax, and even notes an API sunset. It also links to a sibling for an alternative use case.

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

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

Schema coverage is 100%, so the description builds on that. It clarifies 'since' with examples and typical usage, explains that 'value' accepts ticker or CIK, and notes that only 'company' is supported for 'type'. This adds meaningful detail without redundancy.

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

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

The description starts with concrete query examples and clearly states it returns a change feed for a company over a window. It lists specific sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes the sibling tool entity_profile, so the purpose is both specific and differentiated.

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

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

The description provides an explicit alternative ('Use entity_profile instead when you want the static profile') and explains fallback behavior (GDELT→GNews). It also suggests typical window values ('30d' or '1m'). While not exhaustive about when-not-to-use, it offers clear 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?

Adds context beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradiction with annotations (idempotentHint=true, destructiveHint=false).

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

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

Three concise sentences: purpose first, then usage, then behavioral 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?

For a simple write tool with no output schema, description covers purpose, when to use, and retention behavior. Could mention if overwrite or append, but not essential.

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 reinforces key-value nature but adds no new parameter semantics beyond the schema's examples.

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 'Save data the agent will need to reuse later' with concrete examples, and explicitly distinguishes from sibling tools '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?

Provides explicit guidance on when to use: 'when you discover something worth carrying forward' with examples, and pairs with recall/forget for retrieval/deletion.

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

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

Beyond the read-only and idempotent annotations, the description discloses that each call cascades through several lookup endpoints internally, replaces 2-3 manual lookups, and returns specific citation URIs. It also mentions auto-disambiguation for company inputs, giving rich behavioral context that surpasses what annotations provide.

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

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

The description is well-structured and front-loaded with natural-language triggers. Despite being lengthy, every sentence adds value: it clarifies the tool's niche, describes supported types, return fields, and citation URIs, and notes the cascading internal lookups. No filler or redundancy.

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

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

For a tool with only two parameters and no output schema, the description thoroughly covers the return value structure (ticker, CIK, company_name, RxCUI, etc.), input flexibility, and disambiguation behavior. It also mentions the citation URIs, making the tool's contextual behavior complete for an agent to select and use it confidently.

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

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

The input schema already covers both parameters with detailed descriptions (100% coverage), so the baseline is 3. The tool description adds extra semantics by explaining the accepted input formats for each entity type, noting auto-disambiguation, and clarifying example values like 'ozempic' and 'metformin'.

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: resolving a user-spoken name to a canonical/official identifier required by other tools. It gives specific examples like 'What's the ticker for…' and 'find the CIK for…', and distinguishes the tool from siblings by emphasizing it is the first stop when you have a name but need an ID.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID', providing strong usage guidance. It also lists supported types and what each returns, but it does not explicitly state when not to use the tool or name alternative tools for other scenarios, so it lacks explicit exclusionary guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description is not required to restate safety. The description adds value by explaining the probing mechanism, ranking, and return fields (score, confidence, signal density) beyond annotation hints.

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

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

The description consists of three concise sentences that front-load the purpose, provide a use case, and mention output. 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?

Even without an output schema, the description mentions return fields and the probing mechanism. It explains ordering and results adequately for a composite tool, and the schema covers parameter details.

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 that the first entity is treated as the 'subject' for narrative and rest as competitors, providing extra semantic value beyond the schema descriptions.

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

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

The description explicitly states it compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, ranks by score, and surfaces the most/least recognized. This clearly distinguishes it from the sibling tool ai_visibility_check which checks a single entity.

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

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

The description provides a concrete use case (competitive AI-marketing audits) and an example question, implying when to use this tool. It also implies that for a single entity, ai_visibility_check should be used instead.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description goes beyond by explaining partial failure behavior: 'bundlephobia's first measurement on a new version can take 5-30s; sources_failed will list it if it times out, the rest still returns'. This adds valuable behavioral context.

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 with all essential information front-loaded. While it is longer than minimal, every sentence adds value. Could be broken into bullet points for readability, but it is well-structured and efficiently conveys the tool's behavior.

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

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

Given no output schema, the description fully details return values: summary block with fields, per-advisory detail, links, and alternative versions. It also covers edge cases like partial failures and timing. This is complete for a scanning tool.

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

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

Schema coverage is 100%, but the description adds nuance: scoped packages accepted, default version is latest. It explains the role of each parameter in context, e.g., 'Defaults to the latest published version when omitted'. This exceeds solely relying on 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 starts with a clear verb phrase: 'Composite 'should I add this npm package to my project' check in ONE call' and specifies the resource (npm package) and the sources consulted (deps.dev, bundlephobia). It distinguishes from sibling tools by focusing on npm packages, which is unique among the listed siblings.

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

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

Explicit usage guidance: 'Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also specifies limitations: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', providing clear when-to-use and alternative approaches.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond that by disclosing the need for an API key, the error behavior for keyless calls (401), and the scope of results (name, jurisdiction, status, etc.). 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 concise (3 sentences plus an example) and front-loads the core purpose. Every sentence adds value: purpose, return fields, requirement/alternative, and example. 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?

Given the tool's complexity (3 parameters, 140+ jurisdictions), and full annotation and schema coverage, the description provides all necessary context: prerequisites, error conditions, return fields, and an example. With an output schema existing, further detail on return values is unnecessary.

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

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

The input schema has 100% description coverage for all three parameters. The description adds value by explaining why _apiKey is required (public API is closed), providing an example of usage, and clarifying the country parameter as ISO 2-letter code. This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Search global company registries by name across 140+ jurisdictions.' It specifies the verb (search), resource (company registries), and scope (global). It also distinguishes itself from the sibling 'gleif search_lei' by noting it requires an API key.

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 guides when to use the tool (when you have an OpenCorporates API token) and when not to (for keyless global lookup, use 'gleif search_lei'). It also mentions the required authentication and the consequence of missing the API key (401 error).

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. The description adds critical behavioral info: authentication requirement (API key) and return fields. No contradiction; complements annotations well.

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

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

The description is two sentences plus an example, front-loaded with purpose, no redundant words. Every sentence adds value.

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

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

Given annotations, output schema existence, and schema coverage, the description is complete: it covers purpose, required input, return fields, and authentication. Output schema handles return format details.

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 both parameters. The description adds a concrete usage example showing how to pass _apiKey, which is helpful but not essential 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 states 'Search company officers and directors by name' with clear verb and resource, and lists return fields. It distinguishes from siblings like 'search_companies' and 'search_within' 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?

The description explicitly warns about the required API key and gives a usage example. It does not explicitly mention when to use over alternatives, but the distinct purpose and sibling differentiation are 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?

Discloses technical details beyond annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and output structure (passages with offsets and scores). 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?

Concise at ~100 words with front-loaded purpose; every sentence adds value (examples, usage, pairing, technical specs). 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?

Given no output schema, description sufficiently explains outputs (passages, offsets, similarity scores) and constraints (truncation flag). Covers usage, input semantics, and technical details, making the tool 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 already covers parameters well (100% coverage), but description adds meaning: 'text' is a fetched record (e.g., SEC filing), query can be natural language with examples, and limit range. Adds context about offsets for verification, which is not in schema.

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

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

The description clearly states it performs semantic search inside a fetched record, with specific examples (SEC 10-K, article) and distinguishes from sibling ask_pipeworx_grounded by explaining the pairing use case.

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 advises 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded, providing clear context for when this tool is appropriate.

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

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

Beyond annotations, the description discloses account restrictions, SMS daily cap (10/day), webhook auto-disable after 10 failures, and one-time signing secret for webhooks. It also explains that email and SMS are optional additions to the persistent feed. 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 comprehensive and well-structured, starting with the main action, then requirements, supported types, and delivery channels. However, it is somewhat lengthy; a few sentences could be tightened without losing clarity, but overall it's efficient for the 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 the 3 parameters (type, params, delivery) with nested objects and no output schema, the description covers the subscription lifecycle (creation, delivery, limitations), required account type, and response (returns subscription ID). It is complete enough for an AI agent to use correctly, with no missing critical information.

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

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

The input schema already has 100% coverage with descriptions, but the description adds richer examples and context, such as type-specific parameters (e.g., items for sec_8k, topic for polymarket_edge) and delivery details like webhook signing and auto-disable. It enhances understanding beyond the schema's brief descriptions.

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

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

The description starts with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream' and adds 'Returns the new subscription id.' It clearly distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation with persistent monitoring.

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 prerequisites ('Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions)'), which guides when to use. It implicitly contrasts with the always-on feed and mentions alternative delivery channels. However, it does not explicitly state when not to use this tool or compare with siblings like recent_alerts for ad-hoc checks.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. The description adds behavioral context: the output is 'category-bucketed example questions' drawn from a 'live catalog of thousands of tools', and each example includes 'exact tool + argument shape'. This goes beyond annotations.

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

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

The description is front-loaded with common queries, then states purpose, output, and usage. Every sentence adds distinct value; no wasted words. It is moderately long but appropriately detailed.

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 only one optional parameter and no output schema, the description thoroughly covers what the tool does, when to use it, the output format, and parameter usage. It compensates for lack of output schema by describing the output structure.

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 description adds usage guidance: 'Call with no arguments for the full spread, or pass topic (e.g. finance, pharma) to focus.' This adds value beyond the schema description.

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

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

The description clearly states the tool is an 'onboarding entry point' that returns 'category-bucketed example questions' with tool+argument shapes. It differentiates from siblings like ask_pipeworx (which answers questions) and discover_tools (which lists tools) by targeting first-time users.

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 this FIRST when you do not yet know what Pipeworx can do' and explains calling with no arguments for a full spread or with a topic to focus. It does not explicitly discuss when not to use it, but the 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?

Provides rich behavioral details beyond annotations: ownership enforcement, deactivation (not deletion), and impact on historical data. Annotations already show it's mutating, non-destructive, and idempotent, but description adds essential context.

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

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

Two sentences, front-loaded with core action and constraints. No redundant information; every sentence adds value.

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

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

Given single parameter, no output schema, and annotations covering mutation/idempotence, the description fully addresses ownership, deletion behavior, and historical data persistence. Complete for this tool's complexity.

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

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

Schema coverage is 100% and parameter description already states 'Subscription id (uuid) returned by subscribe.' Description doesn't add extra semantics beyond reinforcing that the id identifies the subscription.

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

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

Clearly states 'Cancel a subscription by id' with a specific verb and resource. Distinguishes itself from sibling 'subscribe' by being the inverse operation.

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

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

Explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior. Implicitly guides usage via mention of 'historical events stay available via recent_alerts.' No explicit alternatives but context is sufficient.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses the two-path mechanism: structured SEC EDGAR + XBRL for financial claims, and a grounded pipeline for others. It details the return structure (verdict, actual value with citation, reasoning) and notes it replaces multiple sequential steps. 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 well-structured with front-loaded purpose and examples. Each sentence adds essential information, but the third sentence is quite long and could be slightly trimmed without losing meaning. Overall efficient for the complexity.

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

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

Despite no output schema, the description comprehensively covers return values (verdict, actual value, citation, reasoning). It also explains the internal routing logic. With only two parameters (both well-documented) and clear behavioral details, the tool is fully specified for an agent to invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the 'claim' parameter with concrete examples and describes 'tolerance_pct' usage (overriding default, hallucination detection). This goes beyond the schema's brief descriptions.

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

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

The description starts with example phrasings ('Is it true that…', 'fact check', etc.) and clearly states it's for natural-language claim verification against authoritative sources. It distinguishes between company-financial claims (SEC EDGAR + XBRL) and other claims (grounded pipeline), providing a specific verb+resource combination. The tool's purpose is unambiguous and well-differentiated from sibling tools.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides context on when to use but does not explicitly list exclusions or alternative tools. However, it contrasts with the need for multiple sequential calls, implying consolidation. Sibling tools like 'ask_pipeworx_grounded' exist, but no direct comparison is made.

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