disease

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

Adds details beyond annotations: default model, API key cost implication, and return structure (per-model {score, confidence, signals, raw_response} + combined view). 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?

Description is concise (about 70 words), front-loaded with core action, and every sentence adds useful information. No redundancies.

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?

Input schema fully described, return structure explained, and annotations cover behavioral aspects. Tool is not overly complex; description suffices for an agent to use it 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%, baseline 3. Description adds concrete examples for each parameter and clarifies model options, which adds value beyond schema.

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

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

Description clearly states the tool probes LLMs for visibility, scores per model, and gives use cases (marketing audits, brand checks). Distinguishes from siblings with specific functionality.

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

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

Explains default model and option to probe Anthropic with API key. Implicitly guides when to use (visibility checks), but lacks explicit exclusion of when not to use or direct comparison to 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?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool automatically selects data sources and fills arguments, and it handles natural language questions. However, it lacks details on limitations (e.g., response format, error handling, rate limits, or authentication needs), which are important for a tool with no output schema.

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

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

The description is front-loaded with the core functionality, followed by benefits and examples. Every sentence earns its place: the first defines the tool, the second explains the automation, the third contrasts with alternatives, and the examples provide concrete guidance. It's efficiently structured 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 (natural language processing with automated tool selection) and no annotations or output schema, the description is incomplete. It explains the input well but lacks details on output behavior (e.g., result format, potential errors, or data source limitations), which are crucial for an agent to use it effectively.

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

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

The schema description coverage is 100%, so the baseline is 3. The description adds value by explaining that the 'question' parameter should be in 'plain English' or 'natural language,' and provides examples like 'Look up adverse events for ozempic' to illustrate the expected format, enhancing understanding beyond the schema's basic 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: 'Ask a question in plain English and get an answer from the best available data source.' It specifies the verb ('ask'), resource ('answer'), and mechanism ('Pipeworx picks the right tool, fills the arguments'). It distinguishes from siblings by emphasizing natural language input versus structured tool selection.

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: 'No need to browse tools or learn schemas — just describe what you need.' It provides clear alternatives by implication (use other tools for structured queries) and includes practical examples like 'What is the US trade deficit with China?' to illustrate appropriate use cases.

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

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

Annotations (readOnlyHint=true, openWorldHint=true, destructiveHint=false) are consistent. The description adds behavioral details: it resolves markets, classifies bets, fans out to packs, and returns a comparison. No contradictions.

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

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

Two sentences, but the first is long and dense. It packs a lot of information without being wasteful. Could be slightly more structured, but overall efficient and front-loaded with purpose.

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

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

No output schema, so the description explains outputs (evidence packet, market-vs-model comparison). It covers classification and fan-out logic. For a complex tool, this is sufficiently complete, though more detail on the comparison format would help.

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

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

Schema coverage is 100% with descriptions for both parameters. The description expands on the 'market' parameter by listing accepted formats (slug, URL, question text) and on 'depth' by explaining quick vs thorough. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: researching Polymarket bets by pulling Pipeworx data. It specifies the input types (slug, URL, question text) and output (evidence packet + comparison). This distinguishes it from sibling tools like ask_pipeworx or validate_claim, which focus on different tasks.

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 ('should I bet on X?', 'what does the data say?', 'is there edge?'). It implies this is the preferred tool over manually discovering packs, but does not explicitly state when to avoid it. Still, usability 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?

Describes the data returned for each entity type (revenue, net income, etc. for companies; adverse-event reports, FDA approvals, trial counts for drugs) and mentions returning pipeworx:// URIs. No annotations, but description provides adequate 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?

Concise, front-loaded with the main purpose, and includes the key operational details in three sentences without unnecessary 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?

Covers the main functionality and data returned, but lacks detail on the structure of the output or potential side effects. Given no output schema, slightly more detail on return format would improve completeness.

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

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

Schema coverage is 100%, and description adds meaning beyond schema: explains that 'values' expects tickers/CIKs for companies or drug names, and clarifies the data fields returned for each type.

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

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

Clearly states 'Compare 2–5 entities side by side in one call' and distinguishes between 'company' and 'drug' types with specific data fields. Also mentions replacing 8–15 sequential calls, highlighting its unique value.

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 when to use (comparing entities) and hints at efficiency gains over sequential calls, but lacks explicit when-not-to-use or 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?

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it's a search operation that returns relevant tools, and it should be called first in large catalogs. However, it lacks details on rate limits, error handling, or response format, which are important for a search tool with no output schema.

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

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

The description is front-loaded and concise, consisting of two sentences that efficiently convey purpose and usage guidelines without redundancy. Every sentence adds value, making it easy to scan and understand quickly.

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 (search with natural language query), lack of annotations, and no output schema, the description is mostly complete. It covers purpose and usage well but could benefit from more behavioral details like response structure or limitations. It adequately compensates for the missing output schema by specifying what is returned.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('query' and 'limit') thoroughly. The description adds no additional parameter semantics beyond what's in the schema, such as examples or constraints not covered. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('Search the Pipeworx tool catalog') and resource ('tool catalog'), and distinguishes it from siblings by emphasizing its role in discovery among 500+ tools. It explicitly mentions returning 'the most relevant tools with names and descriptions,' making the function unambiguous.

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

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

The description provides explicit usage guidelines: 'Call this FIRST when you have 500+ tools available and need to find the right ones for your task.' This clearly indicates when to use it (for discovery in large catalogs) and implies alternatives (other tools for specific tasks), though it doesn't name specific 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?

No annotations present, but description discloses it returns pipeworx:// citation URIs, bundles multiple sources, and is a single call replacement. Lacks explicit statement on idempotency or read-only nature, but the nature of a profile tool implies non-destructive 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?

Concise with four sentences, front-loaded with main purpose. Each sentence adds value. Could be slightly more structured, but no waste.

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

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

Given no output schema, description sufficiently explains what is returned (pipeworx:// URIs). With two simple parameters and context signals indicating high schema coverage, the description is complete for its complexity.

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

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

Schema coverage is 100%, but description adds significant value: clarifies type only supports 'company', gives examples for value (ticker or CIK), and warns names not supported, directing to resolve_entity. Goes beyond schema.

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

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

Clearly states it returns a full profile of an entity across multiple data sources in one call. Distinguishes itself from siblings like resolve_entity (name resolution) and compare_entities, and notes it replaces 10-15 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?

Explicitly says when to use (for company profiles) and when not to (for names, use resolve_entity first; for federal contracts, use usa_recipient_profile). Provides 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?

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Delete' implies a destructive mutation, the description doesn't specify whether this operation is reversible, what permissions are required, what happens on success/failure, or whether there are rate limits. This leaves significant behavioral gaps.

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 perfectly concise at 5 words, front-loading the essential information ('Delete a stored memory') with no wasted words. Every element earns its place in this minimal but complete statement of function.

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 destructive mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what constitutes a 'stored memory', what format the response takes, error conditions, or behavioral implications. Given the tool's complexity (destructive operation), more context is needed.

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 the single 'key' parameter adequately. The description adds minimal value beyond what's in the schema ('Memory key to delete'), meeting the baseline expectation when schema does the heavy lifting.

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

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

The description clearly states the action ('Delete') and resource ('a stored memory by key'), making the purpose immediately understandable. However, it doesn't distinguish this tool from potential sibling operations like 'recall' or 'remember' beyond the deletion aspect, which prevents a perfect score.

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

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

No guidance is provided about when to use this tool versus alternatives like 'recall' or 'remember'. The description only states what it does, not when it should be used, what prerequisites exist, or what happens if the key doesn't exist.

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 context about the internal process (fetch page, extract title/description/key links) and output format, going beyond annotations without contradiction.

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

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

The description is concise (three sentences plus a bullet list of use cases) and front-loaded with the main action. 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 explains the output (single text blob, markdown format, to be placed at site-root/llms.txt), covers behavior (fetch, extract, emit), and the use cases. With strong annotations and simple parameters, this is fully 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?

Input schema covers both parameters with descriptions (100% coverage), so the description adds limited value. It reinforces the URL format and max_links constraint but doesn't elaborate 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 generates a production-ready llms.txt file for any URL, specifying the verb 'generate' and the resource 'llms.txt file'. It distinguishes itself from siblings like 'ai_visibility_check' by focusing on the specific output format and use cases for AI crawlers.

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 use cases (getting a client's site indexed, drafting for own project, auditing competitors) but does not explicitly state when not to use or alternatives. However, the context of sibling tools implies some differentiation.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes the return data (cases, deaths, etc.) but lacks critical behavioral details such as data freshness (e.g., real-time vs. delayed), error handling (e.g., for invalid country names), rate limits, or authentication requirements. This is a significant gap for a tool with no annotation coverage.

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, efficient sentence that front-loads the core purpose ('Get COVID-19 statistics for a specific country') and follows with essential return details. Every word earns its place, with no redundant or vague phrasing, making it highly concise 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?

Given the tool's moderate complexity (single parameter, no output schema, no annotations), the description is adequate but incomplete. It covers the purpose and return data, but lacks behavioral context (e.g., data sources, update frequency) and does not compensate for the absence of an output schema by detailing response structure. This meets minimum viability with clear 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%, with the parameter 'country' fully documented in the schema (type, required, description with examples). The description does not add any parameter-specific information beyond what the schema provides, such as format constraints or validation rules, so it meets the baseline for high schema coverage.

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

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

The description clearly states the specific action ('Get COVID-19 statistics') and resource ('for a specific country'), distinguishing it from sibling tools like get_global_stats (global data), get_historical (time-series), and get_vaccine_stats (vaccination data). It explicitly lists the returned metrics (cases, deaths, recovered, etc.), making the purpose unambiguous.

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

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

The description implicitly suggests usage for country-specific COVID-19 data, but does not explicitly state when to use this tool versus alternatives like get_global_stats or get_vaccine_stats. It provides clear context (COVID-19 statistics for a country) without exclusions or prerequisites, falling short of naming specific 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the return data (total cases, deaths, etc.), which is helpful, but lacks details on data freshness, sources, error handling, or rate limits. It adequately covers the core behavior but misses operational context.

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

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

The description is a single, well-structured sentence that front-loads the purpose ('Get global COVID-19 statistics') and efficiently lists the returned data. Every word adds value, with no redundancy or wasted space, making it highly concise and clear.

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

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

Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is nearly complete: it states the purpose, usage context, and return data. However, it could improve by mentioning data sources or update frequency, slightly reducing completeness for a statistical tool.

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

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

The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately omits parameter details, focusing on the tool's function. A baseline of 4 is applied for zero-parameter tools, as it efficiently avoids unnecessary information.

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 specific action ('Get global COVID-19 statistics') and resource ('global COVID-19 statistics'), distinguishing it from sibling tools like get_country_stats (country-specific) and get_historical (time-series data). It provides concrete details about what data is returned, making the purpose unambiguous.

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

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

The description implicitly suggests usage for global-level COVID-19 data, with sibling tools indicating alternatives for country-specific, historical, or vaccine-related statistics. However, it lacks explicit guidance on when to choose this tool over others or any prerequisites, keeping it from a perfect score.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what data is returned (daily timeline of cases, deaths, recoveries) and the scope (country or global), which is useful. However, it doesn't mention important behavioral aspects like rate limits, data freshness, error conditions, or whether this is a read-only operation (though 'get' implies read). The description adds some value but lacks comprehensive 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 extremely concise and well-structured in just two sentences. The first sentence clearly states the purpose and scope, while the second sentence specifies the return format. Every word earns its place with zero waste or redundancy, making it easy for an agent to quickly understand the tool's function.

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

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

Given the tool's moderate complexity (historical data retrieval with optional parameters), no annotations, and no output schema, the description provides adequate but incomplete context. It covers the basic purpose and return data types but lacks information about response format structure, data sources, limitations, or error handling. For a data retrieval tool with no output schema, more detail about the return structure would be helpful.

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

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

The input schema has 100% description coverage, with both parameters (days and country) well-documented in the schema itself. The description doesn't add any parameter-specific information beyond what's already in the schema descriptions. According to the scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.

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: 'Get historical COVID-19 timeline data for a country or globally' with specific resources (cases, deaths, recoveries) and a daily timeline format. It distinguishes from sibling tools like get_vaccine_stats by focusing on historical case data rather than vaccination statistics. However, it doesn't explicitly differentiate from get_country_stats or get_global_stats which might overlap in scope.

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

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

The description implies usage context by specifying 'for a country or globally' and mentioning the return format, but it doesn't provide explicit guidance on when to use this tool versus alternatives like get_country_stats or get_global_stats. No when-not-to-use scenarios or prerequisites are mentioned, leaving the agent to infer appropriate usage from the tool name and description alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format ('daily cumulative vaccine doses administered') and time scope ('over the last 30 days'), which adds useful context. However, it does not cover aspects like rate limits, error handling, or data freshness, leaving gaps in behavioral understanding for a tool that likely queries external 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?

The description is highly concise and front-loaded, consisting of two sentences that efficiently convey the tool's purpose and return data. Every sentence earns its place by adding value: the first states the action and resource, and the second specifies the data format and time range, with 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 the tool's moderate complexity (querying vaccination data with an optional parameter) and no annotations or output schema, the description is adequate but incomplete. It covers the core functionality and return scope, but lacks details on output structure (e.g., data format, fields), error cases, or prerequisites, which would be helpful for an AI agent to use it correctly.

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

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

The input schema has 100% description coverage, with the 'country' parameter well-documented in the schema ('Country name to get vaccine data for. Omit for global totals.'). The description does not add any parameter-specific information beyond what the schema provides, such as format examples or constraints, so it meets the baseline score of 3 where the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Get COVID-19 vaccination coverage timeline' specifies the verb ('Get') and resource ('vaccination coverage timeline'), and 'Returns daily cumulative vaccine doses administered over the last 30 days' elaborates on the data returned. It distinguishes from siblings like 'get_country_stats' by focusing specifically on vaccination data rather than general statistics.

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 by specifying what data is returned (vaccination coverage over the last 30 days), but does not explicitly state when to use this tool versus alternatives like 'get_global_stats' or 'get_historical'. It provides some context (e.g., 'Omit for global totals' in the schema hints at a default), but lacks clear guidance on exclusions or direct comparisons to 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?

The description discloses a key behavioral trait: rate limit of 5 messages per identifier per day. Since no annotations are provided, this is valuable. It does not cover other behaviors like acknowledgment or privacy, but the core constraint is clearly stated.

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

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

The description is concise with four sentences, each adding unique value. The first sentence immediately defines the purpose, and every sentence is necessary 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?

For a simple feedback tool with no output schema, the description covers purpose, usage, content guidelines, and rate limits. It could mention if there is an acknowledgment or response, but overall it is sufficiently 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?

The input schema has 100% coverage with descriptions for each parameter, so the description adds limited value beyond reiterating usage context. The mention of 'Describe what you tried' aligns with the message parameter but doesn't add new semantic detail.

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 sends feedback, listing specific use cases (bug reports, feature requests, data gaps, praise), which distinguishes it from sibling tools like ask_pipeworx or 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?

It explicitly says when to use (bug reports, etc.) and what not to include (user prompt verbatim), providing clear guidance. However, it does not mention when not to use or suggest alternatives, but sibling context suffices.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds valuable beyond-annotation details: caching (5min-1h), self-aggregation, no PII, derivation from CF analytics-engine. 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?

Slightly longer but each sentence earns its place. Bullet-pointed use cases aid scanning. Could be trimmed slightly, but overall efficient for the information conveyed.

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 (one optional param, no output schema, strong annotations), the description is remarkably complete. Covers what it returns, how it works, caching, data origin, privacy, and use cases. No gaps.

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

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

Schema coverage is 100% (one param with enum well-described). The description adds extra context about window interpretation (short vs long) and default, which goes beyond the schema. Provides meaningful additional guidance.

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

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

Clearly states it returns trending tools, packs, and call volume over specified windows. The verb 'trending' combined with the resource 'tools/packs on Pipeworx' makes the purpose unmistakable. It distinguishes from siblings by specifying a unique aggregated signal.

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 three explicit use cases: discovering hot data sources, confirming canonical choice, and seeing alignment. Also explains window choice (short for hot, long for steady-state). Lacks explicit when-not-to-use or alternatives, but the use cases are 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?

Annotations indicate read-only, non-destructive, open-world. Description adds behavioral details: walks child markets, searches across events, groups markets, checks monotonicity, returns ranked opportunities with reasoning. Does not contradict annotations.

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

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

Concise at 5 sentences, front-loaded with purpose, well-structured with clear mode explanations. 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?

Covers the main use cases and modes well. Could be improved by describing the return format or structure of 'ranked opportunities', but overall sufficient for 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?

Schema coverage is 100% with descriptions for both parameters. Description adds examples and explains mode usage, providing additional 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?

Clear verb 'find' + resource 'arbitrage opportunities on Polymarket' + condition 'monotonicity violations'. Two modes clearly distinguished with examples. No confusion with 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 explains when to use event vs topic mode with concrete examples. Provides context for cross-event mode. Does not explicitly state when not to use, but it's clear from description.

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 far beyond annotations (readOnlyHint, openWorldHint, destructiveHint) by detailing the underlying model (lognormal from FRED + live coinpaprika price), the process (scans top markets, groups by asset, fetches price history once, computes model probability, ranks by |edge|), and the output (top N with suggested trade direction). This provides full behavioral transparency without contradicting any 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 slightly long (about 100 words) but each sentence adds value. It is front-loaded with the main purpose and then elaborates on the process and context. Could be trimmed slightly without losing meaning, but it remains clear and well-organized.

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

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

Given the tool's complexity (model, data sources, ranking), three parameters, and no output schema, the description thoroughly explains what the tool does, how it works, and what it returns. It covers the input processing, the ranking logic, and the output format. The annotations (readOnlyHint=true, openWorldHint=true) are consistent. The description is complete for an agent to decide when and how to invoke the tool.

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

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

Input schema covers 100% of parameters with descriptions, so baseline is 3. The description adds extra context by explaining how each parameter fits into the ranking process (e.g., 'Top N edges to return after ranking' for limit, 'Polymarket volume window to filter markets' for window, 'Minimum |edge| in percentage points to include' for min_edge_pp). It does not add syntax details but enriches understanding, justifying 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 starts with a specific verb+resource: 'Scan the highest-volume Polymarket markets and return the ones where Pipeworx data disagrees most with the market price.' It clearly states the tool's purpose and scope, distinguishes it from sibling tools like 'polymarket_arbitrage' by focusing on edge detection for betting opportunities. The mention of 'V1 covers crypto-price bets' further clarifies the domain.

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

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

The description explicitly states the use case: 'Built for the "what should I bet on today" question — agents/users discover opportunities without paging through hundreds of markets by hand.' This provides clear context on when to use the tool. However, it does not mention when not to use it or alternative tools, which would earn 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 declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds details about return format (raw probability 0-1, spread in percentage points) and the override mechanism. No contradictions.

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

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

The description is informative but slightly dense; it could benefit from clearer sectioning. It front-loads the main purpose efficiently. No wasted 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 no output schema, the description adequately explains the return structure (leg-by-leg prices, spread). It covers modes and use cases but could include an example or interpretation guidance.

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 each parameter. The description adds value by explaining that 'topic' is a pre-mapped shortcut and that explicit tickers override the topic-mapped side, enhancing understanding beyond the schema.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, explains the reason for the spread, and distinguishes two usage modes (topic and explicit). This differentiates it from siblings like 'polymarket_arbitrage'.

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 outlines when to use each mode: topic for pre-mapped shortcuts, explicit for custom pairings. It also implies usage for arbitrage signal detection. Clear context and alternatives 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?

With no annotations provided, the description carries full burden. It describes the core behavior (retrieve by key or list all) and persistence scope ('session or previous sessions'), but doesn't disclose error handling, performance characteristics, or data format details. It provides basic behavioral context but lacks depth for a tool with potential complexity.

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 sentences with zero waste. First sentence states the dual functionality, second provides usage context. Every word earns its place with clear front-loaded information about the tool's capabilities.

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 good schema coverage but no output schema or annotations, the description provides adequate context about what the tool does and when to use it. However, it doesn't describe return format or error conditions, leaving some gaps for an agent to understand full behavior.

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

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

The schema has 100% description coverage, so baseline is 3. The description adds value by explaining the conditional logic: 'omit key to list all keys' clarifies the optional parameter's semantic effect beyond the schema's technical documentation. This provides meaningful usage context.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'list') and resources ('previously stored memory by key', 'all stored memories'). It distinguishes from sibling tools like 'remember' (store) and 'forget' (delete) by focusing on retrieval operations.

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

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

The description provides explicit guidance on when to use this tool ('retrieve context you saved earlier in the session or in previous sessions') and includes clear conditional logic ('omit key to list all keys'). It distinguishes usage from other tools by specifying its retrieval/list functionality.

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

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

With no annotations, the description fully discloses behavior: parallel fan-out to multiple sources, return of structured changes, total_changes count, and pipeworx:// URIs. It also explains 'since' parameter semantics and entity type restriction, providing comprehensive behavioral context.

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

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

The description is a single, well-structured paragraph front-loading the purpose, then detailing behavior, parameter specifics, and use case. Every sentence adds essential information with no redundancy or fluff.

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

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

For a tool with 3 required parameters, no output schema, and no annotations, the description fully explains inputs, outputs, behavior, and use cases. It covers parameter constraints, return format, and workflow examples, making it complete for agent understanding.

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

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

Schema coverage is 100%, but the description adds value by elaborating on 'since' with both ISO and relative formats, giving examples like '7d' and '1y', and suggesting '30d' for typical monitoring. It also clarifies 'value' as ticker or zero-padded CIK, which is already in schema but reinforced.

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

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

The description clearly states the tool's purpose: retrieving recent changes for an entity since a point in time. It specifies entity type "company" and data sources (SEC EDGAR, GDELT, USPTO) fanned out in parallel, distinguishing it from sibling tools like entity_profile.

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: "brief me on what happened with X" or change-monitoring workflows. It explains the 'since' parameter formats (ISO or relative) but does not explicitly state when not to use or name alternatives, though the context is clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully explains key behavioral traits: the persistence differences between authenticated users (persistent memory) and anonymous sessions (24-hour lifespan). This goes beyond what the input schema provides about parameters and addresses important operational characteristics.

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 perfectly concise with two sentences that each earn their place. The first sentence states the core purpose, the second provides important behavioral context about persistence. There's no wasted language, and the most critical information (what the tool does) comes first.

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-parameter tool with no annotations and no output schema, the description provides good contextual completeness. It explains the tool's purpose, usage context, and key behavioral characteristics (persistence differences). The main gap is the lack of information about return values or error conditions, but given the tool's relative simplicity, the description is reasonably complete.

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

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

The schema description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any additional parameter semantics beyond what's in the schema properties. It mentions what can be stored in general terms but doesn't provide specific guidance about parameter usage beyond what the schema descriptions already state.

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 with specific verbs ('store a key-value pair') and resource ('in your session memory'). It distinguishes from sibling tools like 'recall' (which likely retrieves) and 'forget' (which likely deletes) by focusing on storage. The description goes beyond the name 'remember' by explaining what kind of data can be stored.

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

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

The description provides clear context for when to use the tool ('to save intermediate findings, user preferences, or context across tool calls'), giving concrete examples of appropriate use cases. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools, though the distinction from 'recall' is implied.

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

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

No annotations are provided, so the description carries the full burden. It mentions returned fields (ticker, CIK, name, URIs) and that it replaces multiple calls, but it does not disclose error handling, rate limits, or authentication requirements. The description is adequate but not exhaustive.

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

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

The description is two well-structured sentences that front-load the purpose and provide concrete details. Every sentence serves a clear function 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?

For a two-parameter tool with no output schema, the description covers the essential input/output behavior. It could be more thorough by specifying the output format (e.g., JSON structure), but it is sufficiently complete for most agent interactions.

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

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

Schema description coverage is 100%, and the description adds minimal extra value beyond examples. The schema already documents the enum for type and the flexible format for value; the description only reinforces with examples, which is helpful but not essential.

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: 'Resolve an entity to canonical IDs across Pipeworx data sources in a single call.' It specifies the input type (company) and acceptable values (ticker, CIK, name), and distinguishes itself from siblings by noting it replaces multiple lookup 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?

The description implies when to use this tool (for entity resolution) but does not provide explicit when-not conditions or name specific alternatives. However, the context of sibling tools (e.g., get_historical, get_vaccine_stats) suggests this is the canonical entity resolution endpoint.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these: it explains the probing mechanism, ranking by score, and output fields (score, confidence, signal density). 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 (4 sentences), front-loaded with the main purpose, and every sentence adds unique information: purpose, mechanism, use case, and output format. 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 the tool has 4 parameters and no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density) and key behavior (probing each entity with ai_visibility_check). It covers the core functionality without 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 semantic value by explaining that the first entity is treated as the 'subject' for narrative and clarifying model options (workers-ai default, anthropic requires _apiKey). This goes beyond the schema descriptions.

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

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

The description uses a specific verb ('Compare') and resource ('AI visibility across multiple entities side-by-side'). It clearly distinguishes from sibling tool ai_visibility_check by emphasizing side-by-side comparison and from compare_entities by specifying the AI visibility domain. The use case ('competitive AI-marketing audits') further clarifies purpose.

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 ('useful for competitive AI-marketing audits') and implies its context (comparing multiple entities). It mentions the underlying mechanism using ai_visibility_check. However, it does not explicitly state when not to use or provide direct comparisons to other sibling tools like compare_entities.

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

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

With no annotations, the description fully discloses the tool's behavior: it returns a verdict, extracted structured form, actual value with citation, and percent delta. It also states the version (v1) and supported domain. While it doesn't mention rate limits or side effects, the read-only nature is implied in 'fact-check.' More details on potential errors or limitations could improve transparency.

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

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

The description is concise and well-structured: the first sentence states the main purpose, the second specifies scope, the third lists outputs, and the fourth highlights efficiency. Every sentence adds value, and the information is front-loaded.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers input, output format, and purpose. It also explains the tool's advantage over alternatives. Missing details include error handling or prerequisites, but overall it is sufficiently complete for effective use.

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

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

The schema has 100% coverage for the single 'claim' parameter with a description. The tool description adds valuable context by providing examples of valid claims ('Apple's FY2024 revenue was $400 billion') and specifying the expected format (natural-language factual claim). This goes beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Fact-check a natural-language claim against authoritative sources.' It specifies the supported domain (company-financial claims for public US companies) and distinguishes itself from sibling tools like ask_pipeworx by its specialized function. Mentioning that it replaces 4-6 sequential agent calls further clarifies its unique value.

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

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

The description provides clear context on when to use the tool: for fact-checking company-financial claims via SEC EDGAR and XBRL. It implies the tool is not suitable for non-financial claims, but does not explicitly state exclusions. No alternative tools are named, but the scope is well-defined.

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