Etherscan

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: default model (Workers AI, free), optional Anthropic probe with BYO key, and that Anthropic calls are billed directly. It also discloses the return 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?

Three sentences, no wasted words. First sentence states purpose, second explains models, third describes return format and lists use cases. 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?

No output schema, but the description fully covers return values ('per-model {score, confidence, signals, raw_response} + combined view') and mentions scoring range 0-100. For a tool with 4 parameters and no output schema, this is complete and sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: it explains the default model for 'models', that '_apiKey' is only needed for Anthropic, and that 'context' helps disambiguate. This elevates the score to 4.

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

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

The description clearly states the tool's purpose: probing LLMs about an entity and returning a visibility score. It specifies the verb 'probe', the resource 'LLMs', and the output format. This distinctively separates it from sibling tools like 'scan_competitor_ai_presence' by focusing on per-entity analysis.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide an API key for Anthropic. While it doesn't compare directly to sibling tools, the context is clear enough for an agent to decide when to invoke.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: it routes questions to one of 3,745 tools, returns structured answers with pipeworx:// citation URIs. This goes beyond annotations by explaining the routing mechanism and output format, with no contradictions.

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

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

The description is front-loaded with the key preference instruction. It is comprehensive but slightly verbose, listing many domains and examples. Every sentence adds value, but could be streamlined slightly without losing clarity. Still, it is well-structured and 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?

Given the tool's complexity (routing to thousands of tools), the description covers purpose, usage, and output format (structured answer with citations). No output schema exists, but the description compensates by describing the return format. Minor gaps: no mention of error handling or what happens if no tool matches, but overall complete for typical use.

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

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

Schema coverage is 100% with one required parameter 'question' and multiple aliases. The description does not add semantic detail about the parameter beyond what the schema already provides. Baseline of 3 is appropriate since schema already handles parameter documentation.

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: answering factual questions with authoritative structured data. It specifies domains (SEC filings, FDA drugs, etc.) and provides examples like 'current US unemployment rate'. It also explicitly distinguishes itself from web search, which is a sibling tool in context.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' and 'Use whenever the user asks...'. It lists trigger phrases like 'what is', 'look up', 'find', etc., and gives concrete examples. It advises routing to this tool for factual queries even if web search could answer, making usage boundaries 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 discloses significant behavioral traits beyond annotations: the extra LLM call cost, refusal mechanism with specific reasons, and the return format. Annotations already declare safe read-only behavior, but the description adds rich context about how the tool handles data extraction and refusal.

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

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

The description is a single paragraph with multiple sentences, each adding value: purpose, mechanism, return format, use cases, and comparison. It is front-loaded and efficient, though slightly verbose. It earns its place without excess.

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 routing across many sources and extracting answers, the description provides complete context: return format details, refusal reasons, usage guidance, and comparison with sibling. No output schema exists, so the description compensates fully.

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

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

Schema coverage is 100% (all parameters described). The description adds no new semantic information beyond listing aliases for the question parameter, which is already documented in the schema. Baseline 3 is appropriate as the schema carries the full burden.

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

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

The description clearly states the tool's purpose as a 'Hallucination-resistant answer mode for high-stakes reads' and distinguishes it from the sibling ask_pipeworx by noting the grounded extraction and extra LLM call. It specifies the verb (answer) and resource (tool results), making it easy to understand.

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

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

The description explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'). It provides clear context and exclusions, guiding the agent effectively.

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 extensively details behavioral traits beyond annotations: fan-out to source-specific data packs, response shapes per category, safety short-circuits for low-confidence or closed markets, fallback mechanisms for news, and resolution-rule risk. The annotations (readOnlyHint, etc.) are consistent and the description enriches them with concrete examples.

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 long but efficiently front-loads the core purpose and key constraints. It uses bullet-like formatting for classifiers and examples, making it scannable. Some redundancy exists (e.g., repeating 'low-confidence' and 'closed mark' concepts), but overall it earns 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?

The description is exceptionally complete for a complex tool with 3 parameters and no output schema. It covers market resolution, evidence fan-out, response fields, safety guards, resolution rules, and fallbacks. All aspects an agent needs to invoke and interpret results are addressed.

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

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

With 100% schema description coverage, the description adds significant meaning: it explains the market parameter with examples, depth effect, and include_raw impact. This goes beyond the JSON schema's brief descriptions, enabling proper parameter understanding.

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

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

The description clearly states the tool's purpose: researching a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and outputs (evidence packet, market-vs-model comparison). It distinguishes from siblings like polyamrket_edges and validate_claim by focusing on raw data retrieval and analysis for any bet.

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 to use this tool for questions like 'should I bet on X' and gives example categories. It also describes when results may be unreliable (low-confidence matches, closed markets, wide spreads) and advises inspecting certain fields. However, it does not explicitly state when NOT to use it or list alternatives, slightly reducing clarity.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral detail: it pulls latest 10-K data from SEC EDGAR/XBRL for companies (with correct handling of off-calendar fiscal years), FAERS data for drugs, sorts results by primary metric, and returns citation URIs. This goes well 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 a single paragraph with clear structure: example queries, usage guidance, type-specific data sources, sorting behavior, and replacement value. Every sentence adds meaningful information without redundancy.

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

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

Despite no output schema, the description explains that results are sorted by primary metric and include citation URIs. It covers both entity types with specific data sources. With only 2 parameters, both required, and detailed schema coverage, the description is fully complete for correct agent invocation.

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

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

Input schema has 100% coverage with descriptions for type (enum) and values (array with limits and examples). The description adds meaning by specifying tickers/CIKs for company and drug names, plus examples like 'AAPL','MSFT' and 'ozempic','mounjaro'. It also explains what data each type returns, enhancing 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 performs side-by-side comparisons of 2-5 companies or drugs using a single call, with example queries like 'compare X and Y' and 'head to head'. It distinguishes from siblings like entity_profile by explicitly stating it replaces sequential single-pack lookups.

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

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

The description instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing explicit guidance on when to use. It does not mention when not to use, but the context is clear for comparison tasks.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint, so description adds value with behavioral details: 'never invented', 'explicit gaps[]', 'pre-verified', time expectation (15-60s), account and plan requirements. Missing specifics like rate limits, but still informative.

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 quite dense with valuable information but could be more concise. It front-loads the main benefit but includes many clauses that could be streamlined.

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

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

Despite no output schema, the description thoroughly details the return structure (findings packet with evidence, confidence, source, citation, gaps). It covers input, behavior, prerequisites, timing, and constraints, making it highly complete for an agent.

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

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

Schema coverage is 100%, but description adds meaning: explains depth values (quick=3, standard=5, thorough=8) and that questions can be broad/multi-part. This goes beyond the raw schema definitions.

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: 'Grounded multi-source research in ONE call.' It explains decomposition and parallel routing, and explicitly distinguishes from sibling ask_pipeworx by stating when to use each.

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

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

The description provides explicit when-to-use guidance: 'Use for broad or multi-part questions' and contrasts with 'use ask_pipeworx for single lookups.' It also mentions prerequisites like a Pipeworx account and paid plan for 'thorough' depth.

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

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

Annotations already indicate safe read operation; description adds return format (top-N with schemas) and direct-callability, enhancing transparency 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?

Very concise, two sentences with clear purpose and key behavioral info, no fluff.

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

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

Provides all necessary context: purpose, usage, return format, examples, and behavioral hints. 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%; description adds usage examples but no new semantic info 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 uses specific verb 'find' and resource 'tools', enumerates many domains, and explicitly distinguishes from sibling tools by advising to call first.

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

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

Provides explicit usage context ('use when you need to browse') and advises to call first when many tools are available, but does not directly name alternative 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 note readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds crucial behavioral context: the tool fans out across multiple sources, mentions that the patents API 'soft-fails until reactivated' (important for reliability), and describes fallback behavior (GDELT→GNews). It also clarifies that only type 'company' is supported, with more entity types coming. 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 information-dense but well-structured: starts with example queries, then states the recommendation, then lists sources and return values. Every sentence serves a purpose. Could be slightly more concise by grouping some details, but overall it's tightly written for a complex 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?

With no output schema, the description fully explains the return format: cik, company_name, recent_filings (with count limit and URI format), fundamentals (specific fields sorted), patents (with sunset note), news (via fallback), and LEI. It also describes the parallel fan-out behavior and the soft-fail mechanism. Given the tool's complexity, this is remarkably 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?

Input schema has 2 parameters with 100% schema description coverage. The description reinforces the schema by explaining that value can be a ticker or zero-padded CIK, and reiterates that names are not supported. It adds practical examples ('AAPL', '0000320193') and aligns with the sibling tool resolve_entity. While the schema already provides the basics, the description's examples and context add meaningful 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 concrete user queries ('Tell me about X', 'research Acme', etc.) and defines the tool as providing a 'full cross-source profile of a US public company in ONE parallel call'. It explicitly lists all data sources and returned fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI), making the purpose unmistakable.

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

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

The description clearly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. It also specifies what input to provide ('Pass ticker "AAPL" or zero-padded CIK') and explicitly warns that names are not supported, directing users to resolve_entity for names. This gives thorough guidance on when and how to use the tool.

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

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

Annotations already include destructiveHint=true, so description's 'Delete' aligns but adds little new behavioral info beyond noting it clears sensitive data. Bar is lowered by annotations; description does not conflict.

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, zero waste. 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 one-parameter tool with good annotations, the description fully covers purpose, usage, and behavior. No gaps given the tool's simplicity.

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

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

Schema coverage is 100% with description 'Memory key to delete'. Description adds no new meaning beyond 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 explicitly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes from siblings like 'remember' and 'recall' by implying the opposite 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?

Provides clear guidance: 'Use when context is stale, the task is done, or you want to clear sensitive data.' Also mentions pairing with alternatives 'remember' and 'recall'.

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 mark readOnly, idempotent, non-destructive. Description adds valuable behavioral details: fetches the page, extracts title/description/key links, emits standard markdown format, and outputs a single text blob ready for site-root placement. No contradictions.

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

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

Three sentences: purpose, process, use cases. No wasted words, front-loaded with key verb and output. Every sentence earns its place.

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

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

For a 2-param tool with no output schema and sufficient annotations, the description fully covers what the tool does, how it works, what it produces, and when to use it. No missing information.

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

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

Schema covers both parameters fully (100% coverage). Description adds only a URL example; max_links default/max are already in schema. Baseline 3 is appropriate as description provides minimal extra meaning.

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 generates a production-ready llms.txt file for any URL, explicitly naming the output format and listing concrete use cases (client indexing, personal project, competitor audit). This specific verb-resource pairing distinguishes it from all sibling tools.

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

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

Description explicitly lists three use cases (getting client's site indexed, drafting for own project, auditing competitor crawl). While it doesn't state when not to use, the context is clear and sufficient given no directly competing sibling tool.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds that the default chain is Ethereum mainnet and lists supported chains, but does not disclose additional behavioral details (e.g., error handling, rate limits). This aligns with annotations and adds minor context.

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

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

Two sentences, no redundancy. Front-loaded with core purpose, followed by essential usage details. Every sentence earns its place.

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

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

Given the tool's simplicity (2 parameters, 1 required), existing annotations, and presence of an output schema, the description covers all necessary context. No gaps identified.

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

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

Schema coverage is 100%, baseline is 3. The description adds value by enumerating supported chain slugs and clarifying that chain can be a numeric ID, which goes beyond the schema's simple description. This aids correct parameter usage.

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

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

The description clearly states the tool retrieves native-token balance for an address on supported EVM chains, distinguishing it from siblings like get_token_balance. It specifies the resource (balance), action (get), and scope (native token, EVM chains).

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

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

Provides clear guidance on chain specification (slug or ID) and default chain. However, lacks explicit direction on when to use this tool versus alternatives (e.g., get_token_balance for ERC20 tokens), which 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, idempotentHint, and non-destructive nature. The description adds the important condition that it works only for verified contracts, providing behavioral context beyond the annotations.

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

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

A single, concise sentence that efficiently conveys the tool's purpose without unnecessary detail.

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, combined with annotations and the presence of an output schema (implied), provides sufficient completeness for a simple retrieval tool. The condition about verification is clearly stated.

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

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

Schema description coverage is 100%, with both 'chain' and 'address' described adequately. The description does not add further semantic meaning to the parameters beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states it retrieves the verified contract ABI as JSON. It uses a specific verb ('get') and resource ('contract ABI'), and distinguishes from sibling tools like get_contract_source (source code) and get_balance (balance).

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 hints at usage ('if the contract is verified on Etherscan'), indicating a prerequisite. It does not explicitly state when not to use or list alternatives, but the context from siblings makes the intent 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, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by specifying the exact data returned (compiler version, optimization, license) 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 a single sentence that covers all key aspects with zero wasted words. It is front-loaded with the core purpose.

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

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

With an output schema present, the description need not explain return values. It adequately covers the tool's purpose and outputs for a simple retrieval operation.

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 does not add parameter-level details beyond what the schema provides, but it contextualizes the output. Baseline of 3 is appropriate.

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

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

The description clearly states the tool retrieves verified contract source code along with compiler version, optimization settings, and license. It effectively distinguishes from siblings like get_contract_abi which gets ABI.

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

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

The description implies usage for retrieving source code but does not explicitly state when to use or when to avoid, nor does it mention alternatives among 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 already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so the safety profile is clear. The description adds only a standard read declaration, not enhancing beyond annotations. No contradictions.

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

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

A single, clear sentence with no wasted words. It front-loads the core purpose. Could be slightly more descriptive but is 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 an output schema exists, the description need not explain return values. For a simple query tool, it provides the essential context (token type, address/contract parameters). Complete enough 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?

Schema description coverage is 100%, so parameters are fully documented in the schema. The description adds no extra parameter details (e.g., default chain, address format). Baseline 3 is appropriate.

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

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

The description 'ERC-20 token balance for an address against a specific token contract' uses a specific verb ('get') and clearly identifies the resource (token balance) and scope (address + contract). It effectively distinguishes from sibling tools like 'get_balance' (likely native coin) and 'get_contract_abi'.

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 explicitly state when to use this tool versus alternatives, nor does it mention limitations (e.g., only ERC-20, not native coin). Context is implied but not spelled out.

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, and idempotentHint=true, which cover safety and idempotence. The description adds return field details and the include_inactive parameter behavior, but does not disclose additional behavioral traits beyond what annotations provide.

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

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

Two sentences with no redundancy. The purpose and return fields are front-loaded, followed by usage guidance. 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 low-complexity tool with one optional parameter, no output schema, and strong annotations, the description fully covers its behavior (what it returns) and usage (when to use it). No gaps.

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

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

Schema description coverage is 100% for the single optional parameter include_inactive. The description does not add meaning beyond the schema's description of that parameter, so baseline 3 is appropriate. Return field details are not parameter semantics.

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

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

The description explicitly states the verb 'list', the resource 'subscriptions', and the scope 'caller's active'. It also enumerates return fields (id, type, params, etc.), making the purpose highly specific and distinguishable from sibling tools like subscribe and unsubscribe.

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

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

The description provides clear context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It explains when to use the tool, though it doesn't explicitly mention when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe, non-destructive reads. The description adds concrete behavioral details about the transaction types returned and the address requirement, but could mention pagination behavior.

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

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

Two sentences: first states primary purpose, second elaborates on the key parameter. No unnecessary words, front-loaded 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 8 parameters, 1 required, and presence of output schema, the description covers the essential functionality well. It fully explains the type parameter but could briefly mention pagination defaults (offset, page) or sort order.

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 still adds meaning by explaining how the `type` parameter transforms the result (regular EOA txs, contract-internal, ERC-20, etc.). This is a clear addition beyond the enum list 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 starts with a clear verb+resource ('List transactions for an address') and immediately distinguishes types via the `type` parameter. Sibling tools like get_balance and get_token_balance handle different concerns, so this tool's scope is well-differentiated.

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

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

The description explains that `type` controls which list (normal, internal, erc20, erc721, erc1155), providing direct guidance on when to use each variation. However, it does not explicitly mention when not to use this tool (e.g., for a single token balance) or compare with 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?

Discloses rate limit (5 per identifier per day), that feedback is free and doesn't count against quota, and that team reads digests daily affecting roadmap. All beyond annotations.

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

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

Description is a dense paragraph covering all essentials, but could be slightly more structured (e.g., bullet points). Front-loads purpose and usage well.

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

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

Given no output schema, description fully covers what happens after sending (team reviews), plus rate limits and content guidelines. Very comprehensive for a feedback tool.

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

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

Schema coverage is 100%, but description adds value by explaining how to write the message (be specific, 1-2 sentences, 2000 chars max) and provides context on type meanings not fully covered in schema.

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

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

Clearly states the tool sends feedback to the Pipeworx team, specifying categories (bug, feature, data_gap, praise) and their meanings. Distinguishes from sibling tools which are primarily query tools.

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

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

Explicitly says when to use for bugs, feature requests, data gaps, or praise. Also provides negative guidance: don't paste end-user prompts, describe in terms of Pipeworx tools/packs.

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, non-destructive. Description adds valuable behavioral context: aggregated from CF analytics-engine, no PII, caching 5min-1h. 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, front-loaded with core function, then bullet-like use cases. No wasted words.

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

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

Complete for a simple tool with one optional param and no output schema. Describes why to use, how it works, and caching. Minor gap: exact return structure not specified, but acceptable.

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

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

Schema coverage is 100% and description adds meaning beyond schema by explaining window behavior (shorter = hot, longer = steady-state) and default.

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 returns top tools, top packs, and total call volume over a window, using specific verbs and resource. It distinguishes from siblings like discover_tools by focusing on trending/current usage.

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

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

Three explicit use cases are listed, plus window selection guidance. It doesn't explicitly mention when not to use, but the context is clear. Could be improved by noting alternatives among siblings.

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

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

Annotations already indicate read-only, idempotent, open-world. Description adds detailed behavioral context: walks child markets, checks ordering, partition checks, similarity threshold (≥0.30 Jaccard), placeholder filtering, fill check against CLOB depth. 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 lengthy but well-structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds value, though slight verbosity prevents a 5. Front-loaded with requirement and purpose.

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

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

Covers all necessary context: how to use each parameter, failure conditions (no args fails, placeholder fraction >20%), return structure (opportunities, partition_check), and fill check integration. No output schema needed; description sufficiently explains outputs.

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

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

Schema coverage is 100% with descriptions. Description greatly expands meaning: explains event mode vs topic mode, gives examples of valid inputs ('fed-decision-may-2026'), and describes what each mode does internally (e.g., 'searches related events across the platform').

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 verb 'Find arbitrage opportunities' and resource 'Polymarket via monotonicity violations + partition-sum checks'. Distinguishes two modes (event and topic) with specific behaviors, setting it apart from sibling tools like polymarket_edges.

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

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

Explicitly requires one of 'event' or 'topic', recommends event for specific markets and topic for cross-event scanning. Provides guidance on when not to trade (realizable_edge_pp ≤ 0) and 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?

Annotations already mark the tool as readOnly, openWorld, idempotent, non-destructive. The description adds extensive behavioral context: internal model families, response structure (by_segment with diagnostics), caching at KV level, and edge components like the 24h-move warning. It does not contradict annotations and significantly enriches the agent's understanding of what happens during and after invocation.

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 necessary given the tool's complexity. It is well-structured: general purpose first, then model families, response structure, knobs, additional fields. Every sentence serves a purpose, though some technical details (e.g., filter skips diagnostics) could be slightly abbreviated. Still efficient for the content density.

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

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

With no output schema and 9 parameters, the description fully compensates by detailing the by_segment response, diagnostics, caching, and edge metrics. It explains what happens when a segment is empty (diagnostics show filter_skips) and includes realistic usage knobs. The description is self-sufficient for an agent to understand inputs, behavior, and outputs.

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 9 parameters have schema descriptions (100% coverage), so the description's job is to add value beyond those. It explains parameter interactions (e.g., why min_kelly doesn't filter partition arbs, how min_partition_leg_kelly compensates) and provides usage advice (e.g., slippage_pp defaults, max_spread_pp recommendation of 2). This goes beyond the schema's basic type/description.

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

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

The description opens with a clear verb-resource pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It distinguishes itself from many sibling tools (e.g., polymarket_arbitrage, polymarket_edge_tracker) by specifying its niche—discovering edge opportunities without manual paging—and by detailing the three model families under by_segment.

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 is explicit about the tool's purpose ('what should I bet on today'), explains when to use knobs like min_liquidity and max_spread_pp, and notes that Fed bets are excluded from ranking. It does not explicitly compare to alternatives, but the detailed segments and knob guidance provide strong usage context.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds critical behavioral details: decay from daily closes (not intraday), snapshot gaps, and explains response structure. 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-organized with Args, RESPONSE, LIMITS sections. Slightly verbose with parentheticals, but front-loaded purpose. Good balance of detail.

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

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

No output schema, but description fully specifies response fields (tracked, expired, snapshot_dates) with their contents. Addresses limitations (60-day TTL, snapshot gaps). Complete for a telemetry 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 has 100% coverage with descriptions. Description adds value by specifying defaults, clamp range for days, and explicit window options (24hr/1wk/1mo), exceeding 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?

Clearly states it provides edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and trend. Differentiates from sibling tools like polymarket_edges.

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

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

Gives context on when to use (for time-series edge analysis) and describes args with defaults. Lacks explicit when-not-to-use or alternatives, but implies it's for historical analysis, not current edges.

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 goes beyond by detailing behavioral traits: it walks the order book ladder, returns verdicts ('clean|degraded|cannot_fill'), warns about thin legs and forced directional risk, and explains the dominant loss mode. This adds significant 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 single-market and basket modes, and uses bold headings and bullet-point-like enumerations. It is slightly lengthy but every sentence earns its place by providing necessary details. It is front-loaded with the purpose and critical warnings, making it efficient 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 the tool's complexity (two modes, many return fields), the absence of an output schema, and rich annotations, the description is remarkably complete. It covers all necessary contexts: return values, edge cases (thin books, partial fills), risk factors (unhedged directional position), and practical usage thresholds. No gaps are apparent.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds deeper meaning: for 'market' and 'event', it explains the two modes; for 'side', it clarifies default behavior in basket mode; for 'size_usd', it interprets the value as 'max spend on buys, target proceeds on sells' or 'settlement notional' for basket. 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 explicitly states the tool's purpose as a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and clearly distinguishes between single-market and basket modes. It uses specific verbs ('walks the ladder', 'returns') and resource references ('market slug', 'event slug'), making it easy to differentiate from siblings like polymarket_arbitrage and polymarket_edges.

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

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

The description 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 the risks of not using it (partial basket fills converting an arb into an unhedged directional position), offering clear context and exclusions.

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

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

The description adds significant behavioral context beyond annotations: it explains two modes, response structure (leg prices, top_spreads_pp), and safety fields (compatibility_warning, temporal_alignment, skipped counters) with conditions for warnings. Annotations already indicate read-only, idempotent, non-destructive, and description does not contradict.

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-organized and front-loaded with purpose and modes, but it is quite lengthy. Every sentence contributes, but some could be tightened 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 lacking an output schema, the description thoroughly explains the return structure: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters. It covers all relevant aspects for an agent to correctly invoke and interpret results.

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

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

Schema coverage is 100%, so parameters are documented. The description adds value by listing all topic shortcuts and explaining that explicit parameters override the topic-mapped side. This enriches 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes: topic shortcuts and explicit ticker/slug, and positions it uniquely among sibling tools like compare_entities.

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

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

The description explicitly tells when to use the tool (to find spread) and provides guidance on interpreting compatibility warnings. It notes that most pre-mapped topics return warnings, implying when to avoid relying on spreads. However, it does not explicitly compare with sibling tools, though the tool is sufficiently distinct.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds useful behavioral details: scoped to identifier, omit key to list all keys, pairing with other tools. No contradictions.

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

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

Three focused sentences. Front-loaded with core function. Every sentence adds value. 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?

Completely describes the tool's behavior for its simplicity: retrieval, listing, scoping, and relationship to siblings. No missing information 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?

Schema coverage is 100% for one parameter. Description adds meaning: 'omit to list all keys', which clarifies the parameter's behavior beyond the schema description.

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

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

Description clearly states 'Retrieve a value previously saved via remember, or list all saved keys'. It gives specific action (retrieve/list) and resource (saved keys), and differentiates from siblings '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?

Explicitly states when to use: 'look up context the agent stored earlier'. Provides alternatives: 'Pair with remember to save, forget to delete'. Also notes scoping by identifier.

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 true, and destructiveHint false. The description adds significant value by detailing return fields (source, citation_uri, payload), the mark_read side effect, and polling suitability, all beyond what annotations provide.

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

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

The description is a single, well-structured paragraph of ~80 words. It front-loads the purpose, then efficiently covers return format, filtering, mark_read, polling, and alternative access without redundancy.

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

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

Given no output schema, the description adequately explains return fields. Combined with 100% schema coverage for parameters, it covers all essential aspects: purpose, filtering, side-effects, polling, and alternative endpoint, making it complete.

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

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

With 100% schema coverage, the description still enriches parameters by giving an example type ('sec_8k'), explaining mark_read behavior, and specifying ISO timestamp format for 'since', adding meaning beyond the schema.

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

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

The description clearly states the tool 'pulls fired events from your subscription feed', specifying the verb (Pull) and resource (fired events). It distinguishes itself from siblings like 'list_subscriptions' by focusing on alert 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 usage context, noting that polling works fine and offering an alternative HTTP endpoint for scripts. However, it does not explicitly state when to avoid this tool or compare it to other 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 openWorldHint. The description adds significant behavioral context: it fans out to SEC, GDELT/GNews, and USPTO; explains fallback logic; mentions soft-fail for USPTO API sunset; and describes return structure (changes[] grouped by source, total_changes, citation URIs). This goes well beyond annotations.

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

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

The description is detailed but every sentence adds value: example queries, source listing, fallback, parameter format, return structure, alternative tool. It is front-loaded with examples. While not ultra-concise, it earns its length without redundancy.

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

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

Given the tool's complexity (multiple data sources, fallback logic, parameter options) and lack of output schema, the description covers all essential aspects: supported entities, parameter formats, return structure, source behavior, and alternative tool. An agent can confidently invoke this tool based solely on the description.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds additional meaning: for 'since', it explains ISO vs relative shorthand and gives examples ('7d', '30d', '3m', '1y'); for 'value', it specifies ticker or CIK format; for 'type', it notes only 'company' supported. This adds practical usage guidance beyond the schema.

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

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

The description opens with multiple example queries ('What's new with X', 'latest on Y') and explicitly states it provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes from sibling tool entity_profile by directing users to that tool for static profiles. This gives a specific verb+resource and differentiates from alternatives.

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

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

The description provides clear context for when to use this tool via example queries and explicitly mentions the alternative entity_profile. It explains the fallback behavior (GDELT→GNews) and soft-fail for USPTO. However, it does not explicitly state when not to use the tool (e.g., if real-time data is needed), but the context is largely 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?

Description discloses persistence behavior beyond annotations: authenticated users get persistent memory, anonymous sessions retain 24h. Also notes scoping by identifier. No contradictions with annotations.

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

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

Four sentences, front-loaded with purpose and usage, then technical 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?

Given no output schema and simple tool, description covers purpose, usage, persistence, and scoping. Complete for 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?

Schema coverage is 100% with clear descriptions. The description repeats schema info without adding new semantic meaning beyond examples. Baseline score of 3 applies.

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

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

The description clearly states the tool saves data for later reuse, using specific verb 'save' and resource 'key-value memory'. It distinguishes from siblings like recall and forget by explaining the lifecycle.

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

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

Provides explicit guidance on when to use (discover something worth carrying forward) and pairs with recall/forget. Does not explicitly state when not to use, but context is strong.

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, destructiveHint. The description adds value by revealing internal cascading through multiple endpoints and auto-disambiguation for companies, which is beyond the annotation data.

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?

A single, focused paragraph front-loads the purpose and provides examples. Every sentence earns its place with no redundancy. Highly concise without sacrificing 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 lacking an output schema, the description details return values per entity type (ticker, CIK, RxCUI, etc.) and mentions internal behavior. It is complete for the tool's complexity and covers both supported types thoroughly.

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

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

Schema coverage is 100%, baseline 3. The description enriches by providing concrete input examples for both parameters, explaining what each entity type returns, and mentioning citation URIs, adding significant meaning beyond the schema.

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

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

The description clearly states it resolves user-spoken names to canonical identifiers, with concrete examples (ticker, CIK, RxCUI) and lists supported entity types. It differentiates by emphasizing it's the first step when needing an ID, which distinguishes it from siblings like entity_profile or compare_entities that likely use resolved IDs.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID' and notes it replaces 2-3 manual lookups. Provides clear context for when to use but does not explicitly exclude alternatives or specify when not to use.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds details on internal probe mechanism, ranking, and return fields (score, confidence, signal density), going beyond annotations.

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

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

The description is concise, with four sentences that are front-loaded with the main action. It efficiently conveys purpose, process, and output without unnecessary words.

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

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

The description covers input, process, and output clearly. It specifies what is returned (ranked list with metrics) even without an output schema. Minor gap: does not mention required parameter validation or error cases.

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

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

Schema coverage is 100% with descriptions for all four parameters. The description enriches meaning by noting that the first entity in 'entities' is treated as the subject, and explaining model options and API key usage.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks results. It distinguishes itself from similar tools like ai_visibility_check by focusing on multi-entity comparison.

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

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

The description explicitly states it is useful for competitive AI-marketing audits, giving a concrete example question. It implies when to use and that it probes multiple entities, but doesn't explicitly state when not to use it.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds crucial behavioral details: fans out across services, partial failures degrade gracefully, bundlephobia first measurement timing, and lists return fields. 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?

Single paragraph is informative but moderately long. Still front-loaded with purpose and all sentences add value. Could be slightly more concise but very clear.

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

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

Given no output schema, description covers return summary fields, per-advisory details, links, alternative versions, and partial failure handling. Ecosystem limitation stated. Lacks interpretation guidance but overall complete.

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

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

Schema coverage is 100% so baseline is 3. Description adds context: scoped packages accepted, version defaults to latest, and explains how parameters are used in the composite check.

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

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

The description clearly states it is a composite check for evaluating whether to add an npm package, covering safety, popularity, and size. It distinguishes from siblings by being specific to npm and combining deps.dev and bundlephobia.

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

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

Explicitly says 'Use whenever an agent asks is X safe / popular / small' and provides alternatives for other ecosystems (PyPI, Maven, etc.), guiding when not to use this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint (false). The description adds significant behavioral details: embedding model (BGE-base-en), window size (500-char overlapping windows), character cap (200K chars with truncation flagged), and output structure (passages with character offsets and similarity scores). 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 at about four sentences, with the key purpose and use case upfront. Every sentence adds necessary context: purpose, when to use, output features, technical details, and pairing suggestion. No redundant or wasted words.

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

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

Given that there is no output schema, the description fully explains what the agent can expect: top-N passages with character offsets and similarity scores. It covers input constraints (max 200K chars, truncation flagged), pairing with a sibling tool, and technical details (model, windowing). This is complete for a tool of moderate complexity.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by providing concrete examples of what 'text' should be (e.g., SEC 10-K body, article) and giving example queries for 'query'. It also clarifies the default and range for 'limit' (1-20, default 5). This goes beyond the schema's dry 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 semantic search inside a fetched record, using a specific verb ('search inside') and resource ('record'). It distinguishes from sibling tools like ask_pipeworx_grounded by explaining that this tool searches within a single record, while the sibling grounds over passages.

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 advises using this tool when a record is too large for a prompt, saving context. It mentions pairing with ask_pipeworx_grounded for grounding, providing clear context on when to use this tool versus an alternative. However, it does not explicitly state when not to use it, leaving a small gap.

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

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

Adds significant behavioral details beyond annotations: required account type, SMS cap, webhook auto-disable after 10 failures, webhook secret returned only once. Does not explicitly address idempotency, but the idempotentHint annotation covers that.

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

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

Well-structured with important information front-loaded. Slightly long but every sentence adds value. Could benefit from bullet points for readability.

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

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

Covers prerequisites, types, delivery options with limitations, and return value. Lacks explicit mention of idempotency behavior, but overall complete for a creation tool with no output schema.

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

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

Schema already has 100% coverage with descriptions. The description adds value with concrete examples for each subscription type and additional delivery option details (e.g., webhook signing, bulk import for params).

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 creates a subscription to a live-data event stream and returns the subscription id. Differentiates from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

Provides prerequisites (Pipeworx OAuth account) and lists supported types with examples. Lacks explicit guidance on when not to use or alternative tools, but context is sufficient for an agent to decide.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds value by specifying it returns category-bucketed example questions and helps learn meta-tool usage, going 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 lists and examples, but it is somewhat lengthy and could be trimmed without losing essential information.

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

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

Given the low complexity (one optional parameter, no output schema), the description is very complete. It explains the return format, when to use, and includes extra context about meta-tools.

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 covers the single parameter with a description. The description adds semantics by providing concrete examples ('finance', 'pharma', 'betting') and explaining the effect of omitting the parameter (full spread).

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

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

The description clearly states it provides example questions categorized by topic and teaches how to call meta-tools. It uses multiple synonyms ('getting started', 'what data do you have?') and distinguishes itself from siblings like 'discover_tools'.

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

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

The description explicitly advises to use this tool first when unsure what Pipeworx can do, and explains when to call with no arguments vs a specific topic. It does not explicitly mention alternatives, but the guidance is strong.

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

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

Discloses key behavioral trait beyond annotations: 'row is deactivated (not deleted) so historical events stay available via recent_alerts'. This adds value over readOnlyHint and destructiveHint 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, front-loaded with core action, no unnecessary words. Every sentence provides essential information.

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

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

Given the simple tool with 100% schema coverage and annotations, description fully explains purpose, ownership constraint, and effect on data (deactivation vs deletion). No gaps.

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

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

Schema coverage is 100% with description 'Subscription id (uuid) returned by subscribe.' Description doesn't add additional meaning beyond the schema, so baseline score applies.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. It distinguishes from siblings like subscribe, list_subscriptions, recent_alerts by mentioning ownership enforcement and effect on historical events.

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

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

Provides clear context: ownership enforced, only own subscriptions. Implicitly says when to use, but doesn't explicitly state when not to use or offer alternatives for non-own subscriptions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: it uses specific data sources (SEC EDGAR+XBRL), returns a verdict with structured output (including pipeworx:// citation and percent delta), and explains it replaces multiple sequential calls. 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 front-loaded with purpose and trigger phrases, then provides domain, data source, return format, and efficiency benefits. Every sentence adds value without redundancy. It is appropriately sized for the tool's complexity.

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

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

For a single-parameter tool with no output schema, the description fully explains the return value (verdict types, structured form, citation, delta) and the tool's scope. Annotations cover safety. No missing information.

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

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

Only one parameter (claim) with 100% schema description coverage. The schema already includes examples and format. The tool description reinforces this with similar examples. Since the schema covers the meaning fully, the description adds marginal value, resulting in a baseline 3.

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

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

The description uses explicit trigger phrases ('Is it true that...', 'fact check') and clearly states it verifies natural-language claims against authoritative sources. It specifies the domain (company-financial claims via SEC EDGAR+XBRL) and distinguishes from siblings by noting it replaces 4-6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of supported claims. However, it does not explicitly state when NOT to use it or mention alternatives beyond the sibling list, so it's slightly incomplete.

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