Opencellid

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

Beyond annotations (readOnlyHint, etc.), the description adds behavioral context: exact return structure (per-model {score, confidence, signals, raw_response} + combined view), default model cost (free), and BYO key model (Anthropic). No contradiction with annotations.

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

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

Three sentences, each earning its place: first sentence states action and output, second explains options and cost, third lists use cases. No redundant words, fully front-loaded.

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

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

Given the tool's complexity (multiple models, scoring, optional parameters, no output schema), the description is complete: it covers purpose, parameters, return format, and ideal use cases. 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 descriptions cover all 4 parameters (100% coverage). The description adds value by explaining the default model behavior for 'models', the purpose of '_apiKey' (pass-through to Anthropic), and the disambiguation help of 'context'. This goes beyond the schema descriptions.

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

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

The description uses specific verbs ('Probe', 'score') and identifies the resource ('LLMs', 'visibility') and the output ('0-100 score per model'). It clearly distinguishes from sibling tools like scan_competitor_ai_presence by focusing on multi-model visibility scoring.

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 usage context: AI-marketing audits, pre-launch brand checks, competitive monitoring. It explains when to provide _apiKey (for Anthropic) and that the default model is free. It lacks explicit 'when NOT to use' guidance, but the use cases are sufficient.

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

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

Annotations already provide the safety profile (readOnly, idempotent, non-destructive). The description adds valuable behavioral context: routing to thousands of tools, filling arguments, returning stable citation URIs, working on every tier, and being a 'one fast call' default. It does not cover failure/fallback behavior, but given strong annotations, this is a solid disclosure.

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

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

The description is long but front-loaded with the core directive ('PREFER OVER WEB SEARCH') and packed with useful examples, trigger phrases, and sibling alternatives. Every sentence earns its place; it could benefit from light formatting (bullets) but remains appropriately sized for a broad meta-tool.

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 exists, but the description states the return format (structured answer with stable citation URIs) and comprehensively covers triggers, examples, alternatives, and limitations. It lacks explicit failure-mode or citation-format details, but is complete enough for an agent to confidently select and invoke the tool.

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

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

The schema has 100% coverage of all 6 parameters (all aliases for the single 'question' field) with clear descriptions and examples. The description adds no additional parameter syntax or constraint information beyond the schema, so the 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 routes questions to one of 5,529 tools across 1,455 verified sources and returns structured answers with pipeworx:// citation URIs. It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and positions itself as the 'default entry point', making its purpose unmistakable.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual/structured data, 'START HERE for most questions', and specific trigger phrases like 'what is', 'look up', 'find'. It names alternatives with precise conditions: ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad/multi-part questions, plus a news exception.

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 discloses that candidate routing improvements are enabled live only when under test, and that no candidate is active as of 2026-07-26, so it currently behaves identically to ask_pipeworx. It also states 'Falls back to nothing — this IS a full working router', clarifying that it is not a fallback stub. This adds behavioral nuance beyond the annotations (readOnly, idempotent, openWorld).

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

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

The description is three sentences and each earns its place: identity, current state, usage guidance, and no-fallback clarification. It is moderately detailed but not bloated; could be tightened by removing the date example, but it's still 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?

The tool is a beta router with a simple question-input interface. The description adequately covers its experimental nature, current parity with the stable version, and usage. While no output schema exists, it references 'same response shape' as ask_pipeworx, though it doesn't enumerate the return format. Overall sufficient for an informed 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?

All six parameters are aliases for 'question' and are fully documented in the schema (100% coverage), so the description adds no parameter-specific details. The phrase 'same arguments' alludes to ask_pipeworx but is not explanatory. Baseline of 3 applies due to high schema coverage.

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 identifies the tool as a beta version of ask_pipeworx with identical router capabilities, clearly establishing it as an experimental variant. It references the same toolset and response shape, and the title 'Ask Pipeworx Beta' reinforces the ask-type verb. However, it assumes familiarity with ask_pipeworx for full understanding, so it's clear but not fully self-contained.

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 instructs to use the tool exactly like ask_pipeworx when wanting the newest routing, and notes that it currently matches ask_pipeworx. It differentiates from the stable router by stating results are compared against it to decide merges, providing clear when-to-use 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?

Beyond the annotations (readOnly, idempotent, openWorld), the description discloses detailed behaviors: the exact return shape ({answer, evidence, confidence, source, fetched_at, refusal_reason}), the explicit refusal reasons list, and the rule that answers use 'ONLY what the tool result contains.' It also notes the one-extra-LLM-call cost, which is not captured in annotations.

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

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

The description is dense but every sentence contributes: purpose, routing, extraction behavior, return format, refusal reasons, usage guidance, and cost comparison. It is front-loaded with the core purpose and uses structured lists for refusal reasons, making it easy to scan.

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 fully explains return values, refusal handling, domain applicability, and relationship to siblings. It leaves no ambiguities for an agent deciding whether or how to invoke the tool.

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

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

Schema coverage is 100% (all aliases are documented), so the description adds no additional parameter meaning. The baseline of 3 applies because the schema already fully explains that 'question' accepts natural language and aliases, with no need for elaboration.

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

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

The description opens with a specific verb and resource: 'Hallucination-resistant answer mode for high-stakes reads.' It explicitly differentiates from sibling ask_pipeworx by stating 'Same routing as ask_pipeworx' but adding grounded extraction, making its unique role unmistakable.

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

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

Provides explicit when-to-use context: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' It also mentions the extra LLM call cost as a tradeoff, offering clear decision guidance.

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

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

The annotations already indicate read-only, open-world, and idempotent behavior. The description adds extensive behavioral details: resolver contract with confidence levels, fan-out logic, response shapes, safety short-circuits for low confidence or closed markets, and resolution-rule risk. No contradictions; the description enriches the annotation 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 structured with clear sections (classifiers, fan-out examples, response shapes, etc.) and is front-loaded with the core purpose and use cases. However, it is quite lengthy and could be more concise by trimming redundant explanations (e.g., repeated mentions of low-confidence paths).

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

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

Given the absence of an output schema, the description thoroughly covers all return value shapes (market, analysis, evidence, resolver contract, parent event, news fields, safety indicators, cancellation rules). It addresses edge cases like low confidence, closed markets, wide spreads, and resolution rules, making it fully actionable for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description provides additional context beyond the schema: explains that 'market' accepts slug, URL, or question text; 'depth' describes the trade-off between quick and thorough; 'include_raw' explains when to use true vs false and the impact on response size. This adds significant value.

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

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

The description starts with a clear statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It identifies the specific verb 'Research', the resource 'Polymarket bet', and distinguishes itself from sibling tools like polymarket_edges by targeting bet-specific research with use-case examples.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides concrete examples but does not explicitly name alternatives or state when not to use it, leaving a minor gap in differentiation from siblings like polymarket_arbitrage or deep_research.

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 that results are capped by OpenCellID, a behavioral trait not covered by 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?

Two sentences that front-load the purpose and format, then add a critical limitation. No unnecessary words—every sentence adds value.

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

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

Given the presence of an output schema, the description sufficiently explains the tool's operation and limitations. Could mention pagination or response structure, but not required.

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 schema already describes all parameters. The description reiterates the bbox format and adds context on caps, but does not significantly enhance parameter 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 verb 'List' and resource 'cell towers' with a bounding box. It distinguishes from sibling tools like 'get_cell' which retrieves a single cell, and other unrelated tools.

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

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

Provides guidance on narrowing the bounding box due to server-side caps, but does not explicitly state when to use versus alternatives like 'get_cell'. The context about caps is helpful for effective use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: it explains that for 'company' it pulls latest 10-K revenue/net income/cash/debt with correct off-calendar fiscal year handling, and for 'drug' it pulls FAERS adverse-event counts, FDA approvals, active trials. It also states results are sorted by primary metric and returns paired data with citation URIs. No contradictions with annotations.

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

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

The description is a single, front-loaded paragraph with example queries that immediately convey the tool's function. Every sentence adds value: usage guideline, entity-specific data details, output format, and efficiency claim. No redundant or filler content.

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

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

Given the tool's complexity (multiple entity types, multiple data sources, comparison logic), the description is remarkably complete. It covers input requirements, data sources, special cases (off-calendar fiscal years), output format (paired data + citation URIs), and efficiency gains. 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?

Schema coverage is 100%, but the description enriches parameter meaning: for 'type', it specifies what data each enum value retrieves (SEC EDGAR/XBRL vs FAERS/FDA/clinicaltrials). For 'values', it explains expected formats (tickers/CIKs for companies, drug names for drugs) and the 2-5 limit, providing practical guidance beyond the schema's 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 starts with multiple query examples ('Compare X and Y', 'X vs Y', etc.), clearly stating the tool's purpose: side-by-side comparison of 2-5 companies or drugs. It distinguishes itself from sequential single-pack lookups, making the verb 'compare' and resource 'entities' unambiguous.

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

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

Explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear when-to-use directive. Also details entity types ('company' vs 'drug') and what data each pulls, helping the agent decide when to invoke this tool vs alternatives like entity_profile.

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/destructive), it discloses the account and paid-tier requirement, non-open-web nature, parallel decomposition to 5,529 tools, findings packet composition, gaps that are never invented, contradictions scan, semantic excerpting, latency expectations, and second-hop iteration. No contradiction with annotations.

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

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

The description is long but every section adds usable context: account prerequisite, alternatives, output packet, depth behavior, latency, and edge cases. It is front-loaded with the critical sign-in warning. Slightly verbose but wholly functional and well-organized.

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

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

For a complex tool with no output schema, the description fully documents the return format (evidence, confidence, source, fetched_at, stable citation, gaps[], contradictions[], hop field), failure modes (empty gaps for non-catalog topics), prerequisites, latency, and depth semantics. The burden is fully carried.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds practical meaning: depth levels' behavioral consequences (gap recovery, contradictions, paid tier) and question scope ('Broad/multi-part is fine — decomposition is the point'). It does repeat some schema wording but enriches with real-world implications.

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

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

The description states a specific verb+resource scope: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explicitly contrasts with open-web search. It also differentiates from sibling ask_pipeworx by noting the one-call parallel decomposition across 5,529 tools.

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

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

Provides explicit when-to-use: 'Best for broad/multi-part questions over structured data' and gives concrete alternatives: ask_pipeworx for single lookups or breaking/colloquial current-news, and use ask_pipeworx if not signed in. Depth variants are also explained with discernible trade-offs.

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 that it returns top-N most relevant tools with names, descriptions, and full input schemas with curated examples, ready to call directly. This enriches behavioral context without contradicting annotations.

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

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

The description is relatively concise given the amount of useful information. It front-loads the main purpose and domain list, then explains output and usage hint. A few sentences could be tightened, but overall efficient.

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

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

For a discovery tool with multiple parameters and no output schema, the description fully explains the output (top-N tools with schemas, ready to call) and usage context. No gaps given 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%, so baseline is 3. The description mentions aliases for 'query' but doesn't add significant meaning beyond the schema. The parameter descriptions in the schema are already adequate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists many specific domains and explicitly distinguishes it from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).'

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 guidance: 'Use when you need to browse, search, look up, or discover what tools exist for: [list]' and instructs to call this first to see options, implying not for single answers. This helps differentiate from sibling tools.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds extensive behavioral detail: what sources it fans across (EDGAR, XBRL, USPTO, news, GLEIF), specific return fields (cik, company_name, recent_filings with URIs, fundamentals, patents with sunset note, news with fallback, LEI), and failure modes (soft-fails on patent API). No contradiction with annotations.

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

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

Description is fairly long but well-structured: front-loaded with examples, then usage guidance, then detailed return format. A few details (e.g., patent sunset) could be more concise, but overall efficient for the complexity of the tool.

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 comprehensively details what the tool returns for each source, including ordering, URIs, and fallback behavior. For a complex multi-source profile tool, this provides complete context for an agent to understand the output without needing further documentation.

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

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

Schema coverage is 100% with both parameters described. The description repeats the same parameter guidance (ticker/CIK, names not supported) without adding new semantics beyond the schema. Baseline of 3 is appropriate as schema already carries the load.

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

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

Description clearly states the tool provides a full cross-source profile of a US public company, with numerous example queries ('Tell me about X', 'research Acme', etc.). It distinguishes itself from chaining single-pack lookups, making the purpose highly specific and actionable.

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 'ALWAYS PREFER over chaining... when the user asks for a holistic view.' Also specifies that names are not supported and advises using 'resolve_entity' first if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already provide destructiveHint and idempotentHint. The description adds context about clearing sensitive data and that the tool is used for deletion, which aligns with annotations. 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?

Two sentences, no wasted words. First sentence clearly states purpose, second provides usage context. Front-loaded 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 parameter and no output schema, the description fully covers purpose, usage, and related tools. No gaps.

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

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

Schema coverage is 100% and the parameter 'key' is described as 'Memory key to delete' in the schema. The description does not add extra semantics beyond what is already 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 states 'Delete a previously stored memory by key' which clearly identifies the verb and resource. It also mentions pairing with 'remember' and 'recall', distinguishing it from siblings.

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

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

Explicitly specifies when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. This helps the agent decide when to invoke this tool over alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. Description adds concrete steps: fetches the page, extracts title/description/key links, and emits standard markdown format. No contradictions.

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

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

Description is three sentences, front-loaded with core action, followed by use cases. Every sentence is informative and there is no superfluous content.

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

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

Despite lacking an output schema, description fully explains output format (text blob for site-root/llms.txt). Process is summarized, use cases are covered, and annotations ensure safety understanding.

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

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

Schema coverage is 100% so baseline is 3. Description adds examples (e.g., 'https://example.com') and default/max values for max_links, providing added value beyond schema.

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

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

Description clearly states the action (generate a production-ready llms.txt file) and the resource (any URL). It specifies the exact output format and distinguishes from sibling tools which are all research or utility tools, none generating llms.txt.

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

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

Explicitly lists three common use cases (indexing a client's site, drafting for own project, auditing a competitor). While it does not state when not to use, the specificity makes its application clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the tool returns lat/lon, range, samples, and radio type, which is helpful but does not disclose potential errors, rate limits, or data freshness. For a read-only tool with robust annotations, this is adequate but not rich.

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 long: the first states the core action, the second defines acronyms and lists return fields. It is concise, front-loaded, and contains no superfluous 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?

The tool has an output schema, so detailed return value documentation is not required. However, the description lists return fields but does not explain terms like 'samples' or 'range' in context. For a simple geolocation tool, it covers the basics but could be more informative.

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

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

Input schema has 100% description coverage, with each parameter clearly described (e.g., 'Mobile Country Code (e.g., 310 = US)'). The tool description defines acronyms (MCC, MNC, LAC) and mentions return fields, adding marginal value. Baseline for high schema coverage is 3, and the description does not significantly exceed that.

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

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

The description clearly states the tool's purpose as geolocating a cell tower by mobile network identifiers. It lists the required identifiers (MCC, MNC, LAC, cell_id) and the return fields, distinguishing it from sibling tools like 'cells_in_area' (which finds cells by geographic area).

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 does not provide explicit guidance on when to use this tool versus alternatives. While the sibling 'cells_in_area' suggests a related but different functionality, there is no direct comparison or advice on choosing between them. Usage context is implied but not stated.

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, destructiveHint=false, etc. Description adds value by detailing return fields (id, type, params, created_at, last_fired_at, fire_count) and specifying 'active' subscriptions, providing behavioral context beyond annotations.

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

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

Two sentences with no wasted words. First sentence states purpose and return fields; second provides usage guidance. Highly efficient.

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

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

With full schema coverage, annotations covering safety traits, no output schema but return fields listed, and clear sibling tool context, the description is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% for the single parameter (include_inactive) with a clear description. The tool description adds minimal extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states 'List the caller's active subscriptions' with specific verb and resource. Mentions returned fields (id, type, params, etc.), and 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?

Explicitly tells when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' This provides clear guidance on usage context and differentiates from subscribe/unsubscribe.

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

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

With all annotation hints false, the description carries the full burden of behavioral disclosure. It transparently covers rate-limiting (5 per identifier per day), cost (free, doesn't count against quota), the claim_token flow for anonymous filing, and the consequence of misreporting (delays). No annotation 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 front-loads purpose in the first sentence, followed by usage guidance, exclusions, and mechanics. It is somewhat long (7 sentences) but every sentence contributes useful context, so it is appropriately sized rather than wasteful.

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

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

Despite lacking an output schema and safety annotations, the description covers all essential context: return behavior (claim_token), scope, rate limits, cost, and follow-up mechanism. It is fully adequate for a 4-parameter tool with no required parameters.

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

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

Schema coverage is 100%, with each parameter already documented. The description adds no new parameter semantics beyond the schema; it merely reiterates claim_token usage that the schema already explains. 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 uses a specific verb+resource ('Tell the Pipeworx team something is broken, missing, or needs to exist') that immediately establishes the tool's purpose. It also distinguishes from sibling tools by explicitly limiting scope to this Pipeworx connection and listing concrete use cases (bug, feature, data_gap, praise).

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 criteria ('Use when a tool returns wrong/stale data...') and a clear exclusion ('if the tool came from a different MCP server... file it with that server instead'). It also offers a disambiguation rule for uncertain agents ('Pipeworx tool names are the ones this connection lists'), making usage guidance exceptionally clear.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds self-aggregating signal, no PII, caching details. No contradictions.

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

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

Concise, well-structured: purpose first, then uses, then technical details. 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?

No output schema but describes return values (top tools, packs, volume). Includes caching and privacy details. Complete for its purpose.

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

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

Schema covers window param with description. Description adds semantic context: shorter windows for hot, longer for steady-state. Adds value beyond schema.

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

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

Clearly states it returns top tools, packs, call volume over a window. Differentiates from siblings by focusing on aggregated usage trends.

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

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

Explicitly lists three use cases: discovering hot data sources, confirming canonical tool, aligning use case. Lacks explicit when-not or alternatives, but context is helpful.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds substantial behavioral context: how it searches (top ~200 markets, walks child markets), the semantic anchor threshold, partition filter logic, response structure, and fill check details. No contradiction with annotations; description enriches them.

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

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

The description is lengthy but well-structured with clear sections for each mode, semantic anchor, partition filter, response, and fill check. It is front-loaded with the main purpose. While it could be slightly more concise, every sentence adds value and there is 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 the complexity of the tool (multiple modes, fill check, no output schema), the description is remarkably complete. It explains the criteria for valid arbitrage signals, the fill check logic to avoid non-tradeable opportunities, and the response structure. It also references a sibling tool for custom sizing, covering all necessary context.

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

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

Schema coverage is 100% with both parameters described. The description adds meaning beyond the schema by providing examples of event slugs (like 'fed-decision-may-2026'), topic seeds (like 'Fed rate decision'), and URL acceptance. It also clarifies that passing no args triggers a different mode. However, schema already captures the essential types and 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 on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes: trending scan with no args, event mode for a specific slug, and topic mode for cross-event scanning. The verb 'find' and resource 'arbitrage opportunities' are specific, and the description distinguishes the tool from siblings.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event (recommended for a specific market), and topic for cross-event scanning. It explains the semantic anchor (Jaccard >= 0.30), partition filter (placeholder slugs), and fill check to avoid non-realizable trades. It also references polymarket_fill_risk for custom sizing.

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

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

The description provides extensive behavioral details beyond the annotations: it explains the three model families, edge calculation with slippage, Kelly sizing caps, Fed bet exclusion, caching behavior ('Cached 1h at the KV level keyed on all knobs'), and diagnostic output. This exceeds what the annotations (readOnlyHint, idempotentHint) 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 well-structured despite its length. It starts with a clear one-sentence purpose, then breaks down into logical sections: model families, opportunity fields, tradeable knobs, response structure, and caching. Front-loading is effective. Every sentence adds value given the tool's complexity.

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

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

The description is exceptionally complete. Given the lack of an output schema, it thoroughly explains the response structure (by_segment, fed_candidates, _diagnostics) and each field within opportunities (edge_pp_net, kelly_fraction, market metadata, 24h-move warning). It also describes how empty segments are handled via diagnostics, making the tool self-explanatory.

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

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

Although the schema already covers all parameters (100% coverage), the description adds significant meaning: it explains the rationale for default values (e.g., slippage_pp: 'Polymarket has zero trading fees... but bid/ask + thin depth typically eats 20-50bp per trade'), clarifies the purpose of tradeable-edge knobs, and provides usage guidance for parameters like min_liquidity and max_spread_pp. This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' The verb 'scan/return' and the resource 'Polymarket markets' are explicitly mentioned, and the phrase 'what should I bet on today' distinguishes it from siblings like polymarket_arbitrage or polymarket_fill_risk.

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

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

The description gives clear usage context: 'Built for 'what should I bet on today' — agents discover opportunities without paging hundreds of markets.' It implies the tool is for initial opportunity discovery, but it does not explicitly state when not to use it or compare it to sibling tools. However, the context is sufficient for an agent to understand its primary use case.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds valuable behavioral details: response structure (tracked[], expired[], snapshot_dates[]), decay computation on |edge_pp_net|, and sign convention (negative = SELL YES). 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 a clear front-loaded purpose and sections for response details and limits. It is somewhat verbose but every sentence adds value. Minor point: could be slightly more concise, but structure compensates.

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

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

Despite no output schema, the description fully explains response fields (tracked[], expired[], snapshot_dates[]) and their content. It also notes limitations (60-day TTL, start date, decay from daily closes). For a moderately complex tool, this is comprehensive.

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

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

Input schema coverage is 100% with descriptions for both parameters (days, window). The description adds context: default values, clamping (2-30), window options, and explanation of snapshot triggers. This enhances understanding beyond the schema alone.

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: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like polymarket_edges by focusing on time-series tracking and decay, answering 'how long has this edge existed and is it shrinking?'

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 context on when to use the tool (analyzing edge persistence) and explains trade significance. It does not explicitly list alternatives or when not to use, but the context is clear. The LIMITS section provides constraints on history depth and decay computation.

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 non-destructive. The description adds substantial behavioral detail: it walks the order book ladder, returns verdicts (clean/degraded/cannot_fill), and for basket mode reveals forced_directional_risk and the danger of partial fills. This is valuable context beyond the annotations.

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

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

The description is well-structured with clear sections for REQUIRES, SINGLE-MARKET, and BASKET modes. It is lengthy (~300 words) but every sentence adds value. Minor conciseness could be achieved by further splitting, but overall it balances detail with clarity.

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

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

Given the tool has no output schema and handles two complex modes, the description is remarkably complete. It lists all return fields (top_of_book, vwap_fill_price, slippage_pp, etc.) and explains risks (thin legs, forced directional risk). It covers edge cases like partial basket fills and maximum safe notional.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances understanding by explaining how size_usd is interpreted differently (spend vs target proceeds, settlement notional) and how side defaults are determined in basket mode. This adds meaning but the schema already provides 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 performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and specifies two modes (single-market and basket). It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by explicitly recommending its use before acting on their signals.

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

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

The description provides explicit guidance on when to use this tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It also explains why alternative tools or actions may fail due to thin books and partial basket fills converting arb into directional positions.

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, open-world. Description adds context on price differences, response fields (compatibility_warning, temporal_alignment, skipped counters), and the rarity of real spreads. No contradictions.

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

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

Well-structured and front-loaded, but somewhat verbose. Could be slightly more concise while preserving all key information.

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

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

Given complexity and no output schema, description thoroughly covers modes, parameters, response structure, safety fields, and edge cases. Completely adequate.

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%; description adds examples, enumerates topic values, explains explicit tickers override topic mapping. Adds meaning beyond schema.

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

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

Clearly states the tool's purpose: compute cross-venue spread between Kalshi and Polymarket for the same question. Distinguishes from sibling Polymarket tools by focusing on spreads across two venues.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers) and warns when spreads are not meaningful (compatibility_warning, temporal_alignment false). States that most pre-mapped topics return warnings, guiding appropriate use.

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

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

Behavioral traits like read-only, idempotent, and non-destructive are already provided by annotations. The description adds useful context about scoping ('scoped to your identifier') and the tool's relationship with 'remember' and 'forget'.

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 (three sentences) and front-loaded with the main action. Every sentence adds value with no redundancy or filler.

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

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

For a tool with one optional parameter, no output schema, and comprehensive annotations, the description covers retrieval, listing, scoping, and pairing with sibling tools, making it complete for an agent to use 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?

The schema already describes the single parameter, but the description adds crucial semantic information: omitting the key lists all keys. This goes beyond the schema's documentation of the parameter.

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

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

The description clearly states the tool's purpose: retrieving a value by key or listing all keys if omitted. It uses specific verbs ('retrieve', 'list') and distinguishes itself from sibling tools like 'remember' and 'forget'.

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

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

The description provides clear context on when to use the tool (to look up stored context) and mentions complementary tools (remember, forget), though it does not explicitly state when not to use it.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds key behaviors: marking events as read (mark_read), returning specific fields (source, citation_uri, payload), and confirming polling suitability. No contradiction with annotations.

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

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

The description is concise (two main sentences plus a note about an alternative endpoint). It is front-loaded with the core purpose and each sentence provides necessary detail without repetition.

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

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

Given the tool's simplicity (no required parameters, no nested objects, no output schema), the description covers what is returned, filtering options, state-changing parameter behavior, and an alternative method. It is complete for an agent to understand and use the tool.

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

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

Schema coverage is 100%, providing baseline 3. The description adds meaning by explaining the effect of mark_read, giving an example filter (sec_8k), and clarifying that since expects an ISO timestamp. This adds value beyond the schema.

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

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

The description clearly states it pulls fired events from the subscription feed and returns recent alerts. It distinguishes itself from sibling tools like list_subscriptions (which lists subscriptions) and subscribe/unsubscribe (which manage subscriptions) by focusing on event retrieval.

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

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

The description provides guidance on when to use this tool (e.g., polling works fine) and mentions an alternative endpoint for scripts/dashboards. However, it does not explicitly state when not to use this tool or contrast with alternatives like search tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds detailed behavioral traits: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and return format (structured changes[] grouped by source). No contradiction with annotations.

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

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

Description is somewhat long but every sentence adds value. It is front-loaded with example queries, then details fan-out behavior and return format. Well structured but could be slightly more concise without losing information.

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

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

Given no output schema, the description adequately explains the return: 'Returns structured changes[] grouped by source + total_changes count + pipeworx:// citation URIs.' Covers all aspects of a complex multi-source tool with fallback behavior.

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

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

Schema coverage is 100% so baseline is 3. Description adds meaning beyond schema: explains `since` accepts ISO date or relative shorthand with examples, suggests typical monitoring value, and clarifies `value` can be ticker or CIK. Adds 'only company supported' for `type`.

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

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

Description clearly states the tool provides a 'change feed for a company' with examples like 'What's new with X'. It specifies the verb 'change feed' and the resource 'company', and distinguishes from the sibling entity_profile tool by explaining that entity_profile is for static profiles.

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

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

Explicitly says when to use this tool (change feed) and when not to (use entity_profile for static profile). Provides guidance on `since` parameter: 'Use "30d" or "1m" for typical monitoring.'

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 context beyond annotations: memory is scoped by identifier, authenticated users get persistent memory, anonymous sessions retain for 24 hours. Annotations already indicate idempotency and non-destructiveness. 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 and front-loaded with the primary purpose. Every sentence adds value, from usage context to storage 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 set operation, the description covers purpose, when to use, scoping, and persistence. No output schema is needed; the return is implied. Missing minor details like overwrite behavior, but still fairly complete.

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

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

Schema coverage is 100%, and the description adds context by explaining that key-value pairs store findings with examples (subject_property, target_ticker). This enhances 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: 'Save data the agent will need to reuse later.' It provides specific examples (resolved ticker, target address) and distinguishes from siblings 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?

The description explicitly says when to use: 'when you discover something worth carrying forward.' It mentions pairing with recall and forget, but does not explicitly state when not to use it or list alternatives beyond siblings.

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

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

The description significantly extends beyond the annotations by detailing source-labelled identifiers, the explicit inclusion of unresolved identifiers under 'unresolved', graceful degradation when external sources are unavailable, and the fact that each call cascades through multiple internal endpoints. These are important behavioral traits the agent would not know from annotations alone.

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

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

The description is long but every sentence earns its place. It is front-loaded with user-phrase examples, followed by a terse purpose statement, then structured details on supported types, unresolved behavior, and degradation. The use of bold labels and bullet-like structure makes it easy to scan despite its length.

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

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

Given there is no output schema, the description carries the full burden of explaining what the tool returns. It does so thoroughly: identifier sources, unresolved handling, graceful degradation, and the fact that the tool replaces 2-3 manual lookups. The description is complete enough for an agent to invoke the tool correctly and interpret results in context.

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

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

Though the schema covers both parameters 100%, its descriptions are minimal (e.g., 'Entity type: company or drug'). The description adds substantial meaning by explaining what each type resolves to (company: CIK, ticker, LEI, FIGI; drug: RxCUI, ingredient, brand) and by providing examples for the value parameter. This elevates the parameter semantics well beyond the schema.

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

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

The description is exceptionally clear: it opens with concrete user phrasings, then states the core purpose as 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It distinguishes itself from downstream tools by positioning this as the preparatory lookup step, and it immediately differentiates the two supported types (company, drug) with specific identifier outputs.

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 instruction 'Use FIRST whenever you have a name but need an ID' gives explicit when-to-use guidance. It also implies when not to use it (when you already have an ID), though it does not explicitly name alternative tools or state concrete exclusions. This is strong but not at the highest level because it lacks explicit when-not or sibling comparisons.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already convey safety. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns score, confidence, signal density per entity. This supplements the 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 that front-load the core purpose and then detail functionality and use case. It is fairly concise, though the second sentence is a bit long. No filler or repetition.

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

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

Given no output schema, the description covers return values (ranked list with score, confidence, signal density). It also describes internal behavior (calling ai_visibility_check). It lacks details on error handling or limits, but the annotations cover safety. Overall complete for a benchmarking 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?

With 100% schema coverage, the description adds significant meaning: it explains the entities array's semantics (first is subject), that models default to workers-ai, that _apiKey is only needed for anthropic, and that context disambiguates common names. This goes well 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check and ranking results. It distinguishes from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison) by specifying its competitive audit 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?

The description explicitly recommends use for competitive AI-marketing audits and notes that the first entity is treated as the subject. While it does not directly advise against using alternative tools, the sibling list includes ai_visibility_check for single entities, and the context implies this is for multi-entity comparisons.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds important behavioral context: partial failures, bundlephobia latency (5-30s), and graceful degradation with sources_failed. 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 well-structured and front-loaded. It is a bit long (two paragraphs) but every sentence adds value. Could be slightly more concise, but overall efficient.

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

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

Given no output schema, the description fully explains return values: summary block (fields listed), per-advisory detail, links, and alternative versions. Also covers error handling (sources_failed). Complete for the tool's complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds useful context: default version (latest) and acceptance of scoped packages (e.g., '@types/node'). Slightly 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's purpose: a composite check for npm packages using deps.dev and bundlephobia. It uses specific verbs and resources ('is X safe / popular / small') and distinguishes itself from sibling tools like deps.dev:version.

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

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

Explicit when-to-use guidance: 'Use whenever an agent asks...'. Also clearly scopes to NPM ecosystem and mentions fallback for other ecosystems (PyPI, Maven, etc.) via deps.dev:version.

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

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

Goes beyond annotations by detailing: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation and flagging, and that passages include offsets for verification. 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?

Single well-structured paragraph front-loading purpose, then usage, then technical details. Every sentence adds value, though minor redundancy exists (e.g., character offsets mentioned twice).

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 explains return values (top-N passages with offsets and scores), embedding model, windowing, and constraints. No gaps in essential behavior.

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

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

Schema has 100% coverage, so baseline is 3. Description adds value by explaining usage context (e.g., 'pass the text you already pulled') and mentioning truncation behavior, which enhances understanding beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' with a specific verb ('search') and resource ('fetched record'). It distinguishes from siblings by highlighting the context-saving benefit and pairing with ask_pipeworx_grounded.

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

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

Explicitly tells when to use: 'Use when the record is too big to cram into the prompt.' Provides alternatives and complementary tools (ask_pipeworx_grounded) for grounding over passages.

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

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

The description adds behavioral context beyond annotations, requiring OAuth, listing type-specific parameters, and describing delivery channel constraints (verification, rate limits, auto-disable). Annotations indicate idempotentHint=true but description does not clarify behavior on duplicate creation, which is a minor gap.

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

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

The description is front-loaded with purpose and structured with clear sections. It is slightly dense but each sentence adds value; could be marginally more concise but is still efficient.

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

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

Given the tool has 3 parameters, nested objects, and no output schema, the description covers purpose, parameters, delivery options, and constraints comprehensively. Return value is mentioned only as 'Returns the new subscription id' which is adequate but could be more detailed.

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, and the tool description adds value with examples and constraints for each parameter, especially for 'params' and 'delivery' which include type-specific formats and validation rules.

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 'Create a proactive monitoring subscription to a live-data event stream' and specifies that it returns the new subscription ID. It distinguishes from sibling tools like 'unsubscribe' and 'list_subscriptions' by defining the creation action.

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: requires a Pipeworx OAuth account, lists supported types with examples, and details delivery channels with constraints. It does not explicitly state when not to use this tool versus alternatives, but within the subscription tools group, the usage is clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. Description adds that it returns category-bucketed example questions with exact tool+argument shapes, drawn from a live catalog. This provides rich behavioral context 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?

Front-loaded with common user queries, followed by clear explanation. Slightly verbose with multiple synonyms, but each sentence adds value. Could trim redundancy without losing clarity.

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

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

Despite no output schema, the description explains return format (category-bucketed examples with tool+argument). Single optional parameter is fully documented. Additionally lists meta-tools, providing complete context for an onboarding 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?

Only one optional parameter 'topic' with full schema coverage. Description adds example values and usage context, but the schema already provides adequate description. 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 uses specific verb+resource ('suggest questions') and lists multiple natural language triggers. It clearly distinguishes this as the onboarding entry point, contrasting with siblings like discover_tools or ask_pipeworx.

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 instructs to use this tool FIRST when unsure of Pipeworx capabilities. Also explains optional topic parameter to focus the output. No exclusion guidance needed for an onboarding tool.

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

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

Beyond annotations, the description explains that the row is deactivated (not deleted) and historical events remain available, adding behavioral context that annotations do not cover.

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

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

Two sentences, front-loaded with action, no superfluous words. Every sentence adds value.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose, ownership, side effects, and references related tool (recent_alerts). Complete.

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

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

Schema description coverage is 100%, and the description simply restates 'by id'. No additional semantics beyond schema, meeting 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 uses a specific verb ('Cancel') and resource ('subscription by id'), clearly distinguishing it from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding proper usage. Does not mention alternatives but context is clear.

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

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

The description adds critical behavioral context beyond the annotations: it explains the distinction between could_not_verify (the check did not happen, not evidence either way) and unsupported (no coverage), and discloses that returns include a verdict, the actual value with citation, and reasoning. It also notes the tolerance_pct override for hallucination detection. These details meaningfully supplement the readOnly/openWorld/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 appropriately sized for the tool's complexity. It opens with concrete user query examples, then defines the action, explains the two routing paths, summarizes the output, highlights the crucial could_not_verify caveat, and closes with the efficiency benefit. Every sentence adds information; there is no fluff or redundancy.

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

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

For a tool with two pipeline paths and nuanced verdict meanings, the description covers all essential details: the claim types (financial vs. other), the return structure (verdict, value, citation, reasoning), the special handling of could_not_verify and unsupported, and the tolerance override. It is complete enough for an agent to invoke correctly without an output schema, and it explains the optional parameter's impact.

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

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

Schema coverage is 100% (both parameters described), so baseline is 3. The description elevates this by explaining tolerance_pct's purpose beyond the schema: it 'overrides the tolerance implied by the claim wording' and recommends setting 1–2% for hallucination detection. The claim parameter already has illustrative examples in the schema, so the description's additional examples are marginal but the tolerance_pct enrichment is valuable.

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 defines the tool as 'natural-language claim verification against authoritative sources' and lists recognizable query patterns like 'fact check' and 'is it true that'. It distinguishes itself by describing two routing paths (SEC EDGAR for company-financial claims vs. grounded pipeline for all others), making it clear this is a specialized claim-verification tool, not a general Q&A tool.

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

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

It explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct,' which gives clear guidance. It also explains the routing logic and notes that the tool 'replaces 4–6 sequential calls,' implying it should be preferred over composing other tools. However, it does not name specific sibling tools to exclude, so it lacks an explicit 'when-not-to-use' statement.

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