Elife

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds significant behavioral detail: default model (Workers AI Llama-3.3-70b), optional Anthropic probing with BYO key, and the return structure (per-model {score, confidence, signals, raw_response} + combined view). This provides transparency about how the tool operates and what the output contains, beyond what annotations offer.

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 (about 4 lines) and front-loaded with the main action and purpose. Each sentence adds necessary information: what it does, default model, optional Anthropic, return format, and use cases. No redundant or filler language.

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

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

Given the tool has 4 parameters (100% schema coverage), no output schema, and no nested objects, the description covers all essential aspects: purpose, behavior, parameter semantics (via schema and added context), return structure, and use cases. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100% (all parameters have descriptions). The description adds extra semantics: it explains that 'models' can include 'workers-ai' (default) and 'anthropic' (requires _apiKey), and it clarifies the 'context' parameter 'Helps disambiguate common names.' This adds value beyond the schema, though the schema itself is already well-described, so a slight increase from baseline 3 to 4 is warranted.

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: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses a specific verb ('probe') and resource ('LLMs'), and distinguishes from siblings by emphasizing visibility scoring and default model. The description also lists use cases like 'AI-marketing audits, pre-launch brand checks, competitive monitoring', which further clarifies its unique role.

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

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

The description provides explicit usage contexts: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It also explains when to use the free default model vs. requiring an API key for Anthropic. However, it does not explicitly state when NOT to use this tool or mention alternatives among siblings (e.g., 'scan_competitor_ai_presence'), so it's clear but not fully exhaustive.

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 and idempotent. Description adds that the tool routes to many tools and returns citations with 'pipeworx://' URIs. No contradiction; additional context is valuable.

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

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

Description is front-loaded with key instruction ('PREFER OVER WEB SEARCH') and is well-organized with examples. Slightly long at 5 sentences but efficient overall.

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

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

Covers routing, sources, citation format, and examples. No output schema, but description hints at return format with citations. Adequately complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add parameter-specific info beyond what schema provides (just mentions 'natural language'). No extra value.

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

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

Description clearly states the tool routes questions to 3,599 tools across 839 verified sources, covering many domains (SEC, FDA, FRED, etc.). It distinguishes from web search and from sibling tools like ask_pipeworx_grounded.

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

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

Explicitly says to prefer over web search and provides example queries (e.g., 'current US unemployment rate') and trigger phrases ('what is', 'look up'). Does not mention when not to use or alternatives like ask_pipeworx_grounded, but context is clear.

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

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

Beyond annotations (readOnly, idempotent, etc.), the description details the extraction mechanism, explicit refusal reasons, return object fields, and the extra LLM call cost. 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 dense and front-loaded with core purpose, but slightly lengthy (5 sentences). Every sentence adds value, yet minor trimming could improve conciseness.

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

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

Despite no output schema, the description fully documents return structure, refusal reasons, and cost implications. For a query tool with one effective parameter, coverage is complete.

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

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

Schema coverage is 100%. Description adds meaning by listing all aliases (q, text, input, query, prompt) and describes the parameter as 'Your question in natural language', enhancing schema info.

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 'hallucination-resistant answer mode for high-stakes reads' with specific verb 'ask', resource 'Pipeworx', and distinguishes from sibling 'ask_pipeworx' by noting it extracts answers only from tool results and is for high-stakes scenarios.

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

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

Explicitly states when to use: 'when an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples like financial verdicts, and when not: 'prefer ask_pipeworx for casual lookups', including cost trade-off.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds extensive behavioral context: fan-out logic, classifers, response shapes, resolver contract with confidence scores, parent event extraction, news fallback handling, safety checks for low-confidence and closed markets, and wide-spread warnings. 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 quite long (multiple paragraphs) but front-loaded with the main purpose. While verbose, the level of detail is necessary for such a complex tool. It loses points for not being more concise, but it is well-structured with clear sections and examples.

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

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

Given the tool's complexity (3 params, no output schema), the description is extremely complete. It covers the full workflow, response structure, edge cases (low confidence, closed markets, news fallback), and behavioral notes. No gaps remain for an AI agent to size a bet.

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 value beyond schema: explains depth defaults ('quick = 2-3 sources, thorough = full fan-out'), include_raw behavior and size implications, and provides examples. This extra context justifies a 4.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and output (evidence packet + comparison). This verb+resource combination distinguishes it from sibling tools like polymarket_edges by focusing on comprehensive research rather than just edge detection.

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 for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' Also provides conditions for when it short-circuits (low confidence, closed markets) and explains how to handle fuzzy matches. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: data sources (SEC EDGAR, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. 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?

While information-dense, the description is relatively long and includes many example query phrases which could be more succinct. It is front-loaded with common patterns but could be trimmed without losing essential guidance.

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 adequately covers expected returns (paired data + citation URIs) and behavioral details for both entity types. For a tool with only 2 parameters, this is fully 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 provides basic descriptions (100% coverage). The description enriches both parameters: explains that type 'company' pulls financial data with fiscal year handling, type 'drug' pulls AE/counts, and values are tickers/CIKs or drug names. This adds significant meaning beyond enum/array 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 it performs side-by-side comparison of 2-5 companies or drugs in a single parallel call, with specific verbs like 'compare' and resource 'entities'. It distinguishes from sibling single-entity tools by emphasizing 'one parallel call' vs sequential 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?

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', providing a clear directive for when to use this tool. It also implies alternatives (e.g., entity_profile for single entities) and gives example query patterns.

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 and idempotent. Description adds transparency about output format (returns top-N results with names, descriptions, schemas, examples, ready to call) and that no side effects occur.

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

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

Description is moderately sized, front-loaded with purpose and usage. Lists categories but each sentence adds value. Could be slightly more concise but remains efficient.

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

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

Given no output schema, description fully explains what is returned and how to use results. It covers when to use this tool among many siblings. Could mention limit behavior but adequate.

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

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

Schema has 100% coverage with descriptions for all 6 parameters. Description reinforces natural language usage and provides examples, adding value beyond schema.

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

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

Description clearly states the tool finds tools by describing data/task, lists categories, and distinguishes from siblings by being a meta-tool for discovery. It says 'Call this FIRST when you have many tools available,' which differentiates it from data 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?

Explicitly says when to use (browse, search, discover tools) and includes guidance to call first when many tools are available. Does not explicitly state when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds significant behavioral context: it makes one parallel call, fans out across multiple sources, returns specific fields, and notes that patents soft-fail until May 2025. 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 example queries, which is good. However, it is somewhat long and includes detailed output lists that could be streamlined. Still, every sentence adds value and the structure is logical.

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, no output schema), the description adequately covers all critical aspects: what is returned, constraints on input (ticker/CIK, not names), fallback behavior (patents soft-fail), and guidance to use sibling tools when needed. This is complete for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema: clarifies that type is currently only 'company', explains that value can be ticker or zero-padded CIK (not names), and reiterates the name constraint. This extra context justifies a 4.

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

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

The description uses specific verbs ('profile', 'brief me on', 'give me the rundown') and clearly states the resource: a full cross-source profile of a US public company. It lists concrete data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF) and outputs, distinguishing it from siblings like resolve_entity (for name resolution) and 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?

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also tells when not to use: if only a name is available, use resolve_entity first. Provides context on potential soft-failure of patents.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description is not required to repeat those. However, it adds useful context about when deletion is appropriate (stale context, task done, sensitive data), which enhances transparency 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 three concise sentences with no superfluous information. It front-loads the core purpose, then provides context and pairing instructions, making it efficient and easy to parse.

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

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

For a simple tool with one required parameter, no output schema, and clear annotations, the description covers all necessary aspects: purpose, usage conditions, and relationships to sibling tools. No gaps remain.

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

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

The input schema covers 100% of parameters with a description for key ('Memory key to delete'). The tool description does not add further details about key format or constraints, so it meets the baseline but does not surpass it.

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 deletes a memory by key. It specifies the verb 'delete' and the resource 'previously stored memory', making the action unambiguous. Additionally, it mentions related tools (remember, recall) to distinguish its purpose from siblings.

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

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

The description provides explicit conditions for use: when context is stale, task is done, or to clear sensitive data. It also advises pairing with remember and recall, offering clear guidance on when to use this tool versus alternatives.

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

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

Annotations already indicate safe, read-only, idempotent, non-destructive behavior. The description adds specific behavioral details: fetches the page, extracts title/description/key links, and emits standard llms.txt markdown. 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 (4 sentences), front-loaded with the main purpose, then process, output, and use cases. Every sentence adds value without redundancy.

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

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

The description covers purpose, process, output, and use cases well. However, it omits potential limitations (e.g., rate limits, redirect handling, error scenarios). For a moderate-complexity tool with no output schema, this is adequate but not exhaustive.

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 parameters well-described in the schema. The description adds no additional semantic value beyond the schema; it only implicitly references the URL.

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 generates a production-ready llms.txt file for any URL, detailing the process (fetches page, extracts title/description/links) and output format. It mentions specific use cases (client indexing, own project, competitor auditing), distinguishing it from sibling tools like ai_visibility_check.

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

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

The description lists explicit use cases (getting a client's site indexed, drafting for own project, auditing competitors) but does not mention when not to use or provide explicit alternatives. However, the context is clear and the tool's purpose is well-defined.

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 'Keyless' beyond annotations that declare readOnlyHint, openWorldHint, etc. Also details returned fields, providing useful context for how the tool behaves.

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 pack all needed info: action with example and return fields. No filler, front-loaded, efficient.

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

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

For a simple read-only retrieval with strong annotations, the description covers what it does, what it returns, and auth requirements. 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?

Only parameter 'id' is fully described in the input schema. The tool description does not add extra meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

Clearly states the tool retrieves full metadata and abstract for a single eLife article by ID. Lists specific return fields, distinguishing it from search or list 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?

Indicates 'Keyless' for no auth, implying it's a simple retrieval. Does not explicitly list when not to use or alternatives, but context with siblings like search_articles makes it 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 minimal behavioral context beyond these annotations (e.g., return fields). Given rich annotations, a score of 3 is appropriate.

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

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

The description is concise: two sentences ( purpose and journal context plus return fields) with no filler. It is front-loaded with the main action.

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

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

No output schema exists, but the description explicitly lists returned fields (id, title, type, DOI, publication date, authors) and notes keyless access. This provides complete context for a simple list tool.

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

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

Schema coverage is 100% with a single parameter (limit) described as 'Max results (default 15, max 100).' The description does not add further semantic meaning beyond the schema, so baseline 3 applies.

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

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

The description clearly states the tool lists the most recently published eLife articles, newest first, and enumerates the returned fields (id, title, type, DOI, publication date, authors). This specificity distinguishes it from siblings like get_article or search_articles.

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 the tool's purpose (fetches latest articles) and notes 'Keyless' (no auth required), providing clear context. It does not explicitly state when not to use or name alternatives, but the use case is straightforward.

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=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds that it returns specific fields but does not disclose additional behavioral traits like pagination or rate limits. Without annotations, this would be a gap, but with annotations, it's adequate.

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 purpose and return fields, second gives usage guidance. No wasted words, front-loaded with the core action.

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

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

For a simple read-only tool with one optional parameter and annotations covering safety, the description covers the essentials: what it does, what it returns, and when to use. It doesn't describe pagination or limits, but that is a minor gap.

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

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

Schema coverage is 100% (the only parameter include_inactive has a description in the schema). The tool description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'the caller's active subscriptions', and lists the return fields (id, type, etc.). It distinguishes from siblings like subscribe and unsubscribe by its focus on listing and providing ids for cancellation.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear when-to-use context and links to related actions. It doesn't explicitly state when not to use, but the positive 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?

Annotations indicate a write operation (readOnlyHint=false) and no destruction (destructiveHint=false). The description adds key behavioral traits: rate limit (5 per identifier per day), no quota cost, and that the team reads digests daily. This provides practical context beyond annotations.

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

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

The description is a single paragraph of three sentences, each serving a purpose: stating the tool's function, providing usage guidance, and noting rate limits. It is front-loaded with the core purpose. Could be slightly more structured but remains efficient.

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

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

For a simple feedback tool with full schema coverage and no output schema, the description covers all necessary aspects: purpose, usage scenarios, formatting guidelines, rate limits, and quota impact. It leaves no obvious gaps for agent decision-making.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant new meaning beyond the schema's parameter descriptions, though it reinforces the enum values and message field in context of usage. No extra syntax or format details are provided.

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

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

The description starts with a specific verb-resource pair ('Tell the Pipeworx team') and clearly states the tool's purpose: reporting bugs, feature requests, data gaps, or praise. It effectively distinguishes itself from sibling tools, none of which serve a feedback function.

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 lists when to use the tool (bug, feature/data_gap, praise) and provides directives on what to include (describe in terms of Pipeworx tools/packs) and what to avoid (don't paste end-user's prompt). It lacks explicit 'when not to use' statements, but the clarity is high.

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

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

Annotations already indicate read-only, idempotent, and non-destructive. The description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). No contradictions.

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

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

Two well-structured paragraphs: first states what it returns, second lists use cases and technical details. No wasted words; every sentence provides 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 low complexity (one optional param, no output schema), the description covers all needed aspects: return values, use cases, caching, data source. Complete for its context.

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

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

Schema coverage is 100% with one parameter. Description adds semantic guidance: 'shorter windows surface what's hot right now; longer windows show steady-state demand', supplementing the schema's enum. Adds 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 clearly states the verb 'returns' and the resource: 'top tools, top packs, and total call volume'. It distinguishes from sibling tools like 'ask_pipeworx' and 'discover_tools' by focusing on trending signals.

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

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

Explicitly lists three use cases for when to use the tool: discovering hot data sources, confirming canonical tools, and aligning use cases. Lacks explicit exclusions or alternatives, but context from siblings is evident.

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 goes well beyond annotations (readOnlyHint, etc.) by detailing: required parameter constraints, walking child markets, monotonicity checks, partition sum computation, Jaccard similarity for cross-event, placeholder filtering, and response structure. No contradiction with annotations; adds rich behavioral context.

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

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

The description is detailed and well-structured with section headings (e.g., 'SEMANTIC ANCHOR', 'PARTITION FILTER'), but it is somewhat verbose. Some sentences could be condensed without losing critical information. The use of ALL CAPS for key phrases aids scanning but may feel heavy.

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 covers the response structure (opportunities[], partition_check details) and all key behavioral aspects (modes, checks, filters). For a complex tool with two modes and multiple algorithmic steps, the description provides sufficient context for correct invocation.

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

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

Schema coverage is 100%, but the description adds significant meaning: it explains the difference between `event` and `topic` modes, provides example slugs, and describes how each parameter affects behavior (e.g., cross-event scanning with similarity checks). This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes between two modes (single-event and cross-event) with specific examples, making the verb and resource clear. While sibling tools like polymarket_edges are not explicitly differentiated, the purpose is unambiguous.

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

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

The description explicitly states that one of `event` or `topic` is required and recommends `event` for specific markets and `topic` for cross-event scanning. It explains why cross-event mode is valuable ('catches ... patterns that single-event misses'). However, it does not provide explicit 'when not to use' guidance or compare with specific sibling tools, leaving room for improvement.

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 exceeds annotations (readOnly, idempotent, openWorld) by detailing the three model families, edge calculation, Kelly caps, caching behavior, diagnostics for empty segments, and tradeable-edge knobs. It provides rich behavioral context beyond what annotations alone convey.

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

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

The description is well-organized with clear sections and headers, but it is lengthy and contains extensive algorithmic details that might overwhelm an agent. It could be more concise while retaining essential information, earning a middling score.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably thorough. It covers the output structure (by_segment, fed_candidates, diagnostics), explains why segments might be empty, and details caching and knobs. No gaps remain.

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

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

With 100% schema coverage, the baseline is 3, but the description adds significant value beyond the schema: e.g., explaining that min_partition_leg_kelly applies per-leg while min_kelly does not filter partitions, and detailing the effect of each knob. This additional guidance raises the score.

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

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

The description clearly states the tool scans Polymarket markets for opportunities where Pipeworx data diverges from market price, using a specific verb-resource combination. It is tailored for the 'what should I bet on today' use case, making its purpose unambiguous. Although it does not explicitly differentiate from sibling tool polymarket_arbitrage, the specificity is sufficient.

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 built for agents seeking betting opportunities and includes clear usage context (e.g., avoids paging hundreds of markets, Fed bets excluded from ranking). However, it does not explicitly state when not to use this tool or name alternatives, which would have made it a 5.

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 behavior. The description adds extensive behavioral details: compatibility warnings for shape mismatches, temporal alignment checks, skipped cross-type/subtype counters, and the fact that most pre-mapped topics may not be tradeable. No contradictions with annotations.

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

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

The description is detailed and well-organized with sections for modes, response, and safety fields. While it is lengthy, every sentence is informative and contributes to understanding the tool's behavior. It is front-loaded with the main purpose.

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

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

Given the tool's complexity and lack of output schema, the description fully explains the response structure (leg-by-leg prices, matched spreads, compatibility warnings, temporal alignment) and all input modes. It covers edge cases and failure conditions comprehensively.

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 three parameters. The description adds value by explaining the two operational modes (topic vs explicit tickers), the override logic, and the list of pre-mapped shortcuts, which goes beyond the schema's provided enum description.

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

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

The description clearly states the tool's purpose: computing cross-venue spreads between Kalshi and Polymarket for the same resolving question. It distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on a specific venue pair and provides two modes (topic shortcuts and explicit tickers), making the scope unambiguous.

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

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

The description explains when the tool is useful (comparing same outcome across venues) and warns that real spreads are rare; it provides clear conditions for when spreads are invalid (non-equivalent bet shapes, mismatched timeframes). However, it does not explicitly contrast with alternative tools like 'polymarket_arbitrage' for intra-venue comparisons.

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

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

Annotations already indicate it is read-only, idempotent, and non-destructive. The description adds behavioral context: scoping to an identifier, the ability to list all keys by omitting the key argument, and the pairing with remember/forget. 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?

The description is compact (4 sentences) and well-structured: main function, use cases, scoping, and sibling pairing. No unnecessary words.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scoping, and relationships with sibling tools, leaving no evident 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 a clear parameter description. The description only reiterates the omission behavior, adding marginal value beyond the schema.

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

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

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when the key argument is omitted. It distinguishes from sibling tools 'remember' and 'forget' and provides concrete examples like 'user's target ticker, an address, prior research notes'.

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

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

The description explicitly says when to use the tool: to look up stored context without re-deriving it. It also scopes usage to the agent's identifier and pairs with 'remember' and 'forget', but does not explicitly state when not to use it.

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

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

The description explains the mark_read behavior, which modifies state, but the annotations declare readOnlyHint=true, creating a clear contradiction. Per rules, a contradiction yields a score of 1.

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?

Every sentence adds information: purpose, return format, filtering, mutability, and alternative access. No redundancy or fluff. Front-loaded with core action.

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

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

Despite lacking an output schema, the description details return fields (source, citation_uri, payload) and provides an alternative endpoint for scripts, making the tool fully understandable.

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

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

All 5 parameters are documented in schema (100% coverage). The description adds useful examples (type 'sec_8k', ISO timestamp) and clarifies the effect of mark_read, going beyond the brief schema descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, listing specific return fields and filtering options. It does not explicitly differentiate from sibling tools, but its purpose is specific and action-oriented.

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 mentions that polls work fine and gives an alternative GET endpoint, implying when to use this tool vs a script. However, it does not specify when not to use it or compare to sibling tools like search_articles.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: parallel fan-out to multiple sources, fallback logic, parameter acceptance details, and return structure. No contradictions with annotations.

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

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

The description is dense but every sentence earns its place: front-loaded with example queries, then functional explanation, then alternative tool mention. It is appropriately sized for the tool's complexity and avoids 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, soft-fail, parameter details) and the presence of annotations and full schema coverage, the description is highly complete. It explains behavior, return structure, and edge cases without relying on an 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 coverage is 100%, and the description adds value by clarifying the 'type' enum (only 'company' supported), providing examples and suggestions for 'since' (e.g., '30d'), and explaining 'value' as ticker or CIK. This meaningfully extends the schema descriptions.

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

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

The description clearly defines the tool as a change feed aggregator for a company, listing specific data sources (SEC EDGAR, GDELT→GNews, USPTO) and output structure. It explicitly distinguishes from sibling tool entity_profile, which provides static profiles. This meets the 'specific verb+resource, distinguishes from siblings' criterion.

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 numerous example queries ('What's new with X', 'latest on Y') and explicitly advises when to use the alternative entity_profile. It also explains fallback behavior (GDELT→GNews) and soft-fail conditions for USPTO, giving clear context for usage.

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

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

Beyond annotations (which state readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds valuable behavioral details: key-value pair scoping by identifier, persistence differences (authenticated users vs 24-hour anonymous), and the fact that it is a write operation. 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 concise (three sentences) with a clear front-loaded purpose. Every sentence adds unique value: purpose, when to use, persistence behavior, and companion tools.

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 (2 parameters, no output schema, clear annotations), the description provides all necessary context, including usage guidelines, behavioral details, and parameter semantics.

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

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

Input schema covers 100% of parameters with clear descriptions. The tool description adds examples of what keys and values might contain (e.g., 'subject_property', 'target_ticker'), which enhances understanding beyond the schema alone.

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

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

The description clearly states the verb ('save'), the resource ('data'), and the scope ('across conversations or sessions'). It distinguishes itself from sibling tools like 'recall' and 'forget' by mentioning them as counterparts.

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 ('when you discover something worth carrying forward') and provides alternatives ('Pair with recall to retrieve later, forget to delete'). It also covers context differences (authenticated vs anonymous sessions).

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=true, idempotentHint=true, destructiveHint=false, which describe safety traits. The description adds further context: 'Each call cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups.' This tells the agent about internal complexity without contradicting annotations.

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

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

The description is front-loaded with user-facing examples and uses clear structure. though it includes some internal detail ('cascades through several lookup endpoints') that could be trimmed without loss. Every sentence adds value, but a slightly more concise version would score 5.

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 entity types, multiple input formats, no output schema), the description is remarkably complete. It details input acceptance, returned fields, citation URIs, and even explains internal cascading. The agent has enough information to use the tool effectively without an 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 coverage is 100%, but the description adds substantial meaning: for 'type' it explains what each entity returns (ticker+CIK+company_name for company; RxCUI+ingredient+brand for drug) and mentions citation URIs. For 'value' it provides examples (ticker, CIK, name) and clarifies that company accepts multiple formats with auto-disambiguation. This goes far beyond the schema's minimal descriptions.

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

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

The description starts with concrete example queries ('What's the ticker for…') and clearly states 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It specifies the verb (resolve), resource (identifiers), and the supported entity types (company, drug), distinguishing it from sibling tools that likely operate on 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 says 'Use FIRST whenever you have a name but need an ID,' providing clear when-to-use guidance. It also explains what each entity type returns and input formats. However, it does not explicitly state when not to use this tool or suggest alternative tools for cases where an ID is already known.

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

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

Annotations indicate read-only, idempotent behavior. The description adds behavioral details beyond annotations: it probes each entity with ai_visibility_check, ranks by score, and returns specific fields. It also notes the _apiKey requirement for Anthropic model, providing useful extra context.

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

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

The description is concise and well-structured, with every sentence adding value. It efficiently conveys purpose, usage scenario, and output format 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 full schema coverage, no output schema, and 4 parameters, the description is complete. It explains what the tool returns (ranked list with score, confidence, signal density per entity) and how it operates (probes with ai_visibility_check), leaving no critical gaps.

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

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

Schema coverage is 100%, so baseline is 3. The description adds some value by noting the first entity is treated as 'subject' for narrative, but the schema already provides detailed parameter descriptions. The additional context does not significantly enhance understanding beyond what the schema offers.

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, uses specific verb 'compare' and resource 'AI presence', and distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description explicitly states when to use the tool ('competitive AI-marketing audits') and implies alternatives by mentioning it probes with ai_visibility_check. However, it does not provide explicit 'when not to use' or direct alternative naming, 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 indicate read-only, idempotent, safe. Description adds valuable context: partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed will list timeouts.

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 with rich info, front-loaded with purpose. Slightly dense but each sentence adds value. Could be split into sections for readability, but still concise.

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

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

No output schema, but description details return fields, behavior under partial failures, limitations (NPM only), and provides complete guidance for a composite multi-source 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?

Both parameters have schema descriptions, so baseline is 3. Description adds meaning by explaining scoped packages accepted for 'package' and version default behavior, providing context beyond schema.

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

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

The description clearly states it's a composite check for adding npm packages, listing specific checks (license, advisories, bundle size, etc.). It effectively distinguishes from sibling tools by specifying ecosystem and composite nature.

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

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

Explicitly tells when to use the tool: when agent asks about safety, popularity, size, or cost of adding a package. Also provides when-not: NPM only, directs other ecosystems to deps.dev directly.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds the important behavioral detail 'Keyless' (no API key required), which is 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, well-structured sentence. All information is front-loaded and every part is necessary: source, scope, return fields, and keyless nature.

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 having no output schema, the description lists return fields adequately. Given 24 sibling tools, more context could be provided but the description is sufficient for a straightforward search tool.

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

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

Schema coverage is 100% with both query and limit documented. The description reinforces query usage with an example ('e.g. "crispr base editing"'), adding marginal value beyond the schema.

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

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

The description clearly states the tool searches eLife articles by keyword and specifies the return fields (id, title, type, DOI, etc.). This clearly distinguishes it from siblings like get_article (fetch single) and latest_articles.

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

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

The description says 'Keyless' indicating no authentication needed, but does not explicitly explain when to use this tool versus alternatives such as get_article or latest_articles. No usage exclusions are provided.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds rich behavioral details: 200K char cap with flag, BGE-base-en embeddings, cosine similarity over 500-char windows, and returns passages with offsets and scores. No contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then adds details in a logical order. Every sentence serves a purpose, though slightly lengthy. Still, no waste and well-structured.

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

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

Despite no output schema, the description fully explains return values (passages with offsets and scores) and covers edge cases (truncation flag). For a 3-parameter tool with 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 value by specifying max chars for text, giving example queries, and noting valid range for limit (1-20). It also explains internal mechanics, enhancing understanding beyond schema.

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

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

The description clearly states 'Semantic search INSIDE a fetched record,' with specific verb and resource. It distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded and saving context, and provides concrete examples (SEC 10-K).

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

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

The description explicitly says 'Use when the record is too big to cram into the prompt' and suggests pairing with ask_pipeworx_grounded, giving clear when-to-use guidance. It does not explicitly state when not to use or list all alternatives, but the context is sufficient.

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

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

The description adds significant behavioral details beyond the annotations: requires OAuth, returns subscription id, delivery channels, SMS cap, verification requirements, and per-type nuances. No contradictions with annotations.

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

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

The description is long but well-structured, front-loading the main purpose. Every sentence adds value, though it could be slightly more concise.

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

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

Given the complexity (multiple types, delivery options, no output schema), the description covers requirements, limitations, and edge cases thoroughly, leaving little ambiguity.

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

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

Schema coverage is 100%, and the description enriches each parameter with additional context, such as the patent_grant warning about exact corporate form and the SMS delivery cap and verification requirement.

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

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

The description clearly states the verb 'create' and the resource 'proactive monitoring subscription'. It distinguishes itself from siblings like 'unsubscribe' and 'list_subscriptions' by specifying that it creates a new subscription.

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 context: requires a Pipeworx OAuth account, lists supported types and their parameters, and mentions delivery channels. However, it does not directly contrast with alternative tools like 'recent_alerts', leaving some ambiguity about when to use this vs pulling alerts.

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 deactivation vs deletion and effect on historical events. Annotations already indicate non-destructive; description adds critical context beyond annotations.

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

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

Two concise sentences, front-loaded with action. No unnecessary words.

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

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

Complete for a simple tool: one parameter, no output schema, annotations present. Description covers behavior, ownership, and impact.

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

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

Schema covers parameter fully (100%). Description adds context linking 'id' to subscribe tool, enhancing 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?

Clear verb 'Cancel' and resource 'subscription by id'. Distinguishes from sibling tools 'subscribe' and 'list_subscriptions'.

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

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

Explicit ownership enforcement guides usage: only cancel own subscriptions. Implicitly tells when not to use (when not owner). Could mention alternative for historical data but acceptable.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds value by specifying the return format (verdict, actual value with citation, percent delta) and explaining that it replaces 4-6 sequential calls. No contradictions with annotations.

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

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

The description is dense but front-loaded with key terms. Each sentence adds information, though it could be slightly more concise. It effectively communicates purpose, usage, and return value in a few sentences.

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 claim verification, the description covers the domain, input, output, and efficiency gains. No output schema exists, but the description explains the return fields. It could mention limitations (e.g., only public US companies in v1), but overall is adequate.

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

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

Only one parameter (claim) with 100% schema description coverage. The description adds examples and clarifies the natural-language input style ('Is it true that…'). It goes beyond the schema by explaining the domain scope and expected format.

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

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

The description clearly identifies the tool as a natural-language claim verification tool with specific examples of input patterns. It distinguishes itself from siblings like ask_pipeworx by focusing on fact-checking against authoritative sources for company-financial claims.

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 states 'Use whenever the agent needs to check whether something a user said is factually correct' and limits the domain to company-financial claims for public US companies. It does not explicitly state when not to use it (e.g., for non-financial claims), but the domain limitation implies exclusion.

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