cocktails

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

Discloses default model, BYO key for Anthropic, return format (per-model + combined), and cost implications; annotations already indicate read-only, open-world, idempotent, non-destructive.

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

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

Four sentences, each adding unique value; front-loaded with action and output, then details, then use cases.

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 purpose, parameters, return structure, and use cases thoroughly despite no output schema.

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

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

Schema coverage is 100% and description adds context: entity examples, supported models, conditional _apiKey, disambiguation for 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 probes LLMs for knowledge about an entity and scores visibility, distinguishing it from siblings like scan_competitor_ai_presence by being general-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?

Use cases are listed (AI-marketing audits, pre-launch brand checks, competitive monitoring) but no explicit when-not-to-use or alternatives mentioned.

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 effectively describes key traits: the tool acts as an intermediary that selects and invokes other tools based on the question, handles argument filling, and returns results. However, it lacks details on error handling, rate limits, or authentication needs, which are important for a tool with such broad functionality.

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 in the first sentence, followed by explanatory details and examples. Every sentence adds value: the second explains the mechanism, the third provides usage guidance, and the examples illustrate practical applications. It is 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 (acting as a meta-tool that selects other tools), the description is mostly complete. It explains the input parameter well and the tool's behavior. However, without an output schema, it doesn't describe return values or potential errors, and with no annotations, it misses details like safety or performance traits, leaving some gaps for an agent to infer.

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, so the baseline is 3. The description adds value by explaining the parameter's purpose beyond the schema: it specifies that the question should be in 'plain English' or 'natural language' and provides examples (e.g., 'Look up adverse events for ozempic'), which clarifies the expected format and scope, though it doesn't detail constraints like length or supported topics.

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'), distinguishing it from sibling tools like search_cocktails or get_cocktail, which are more specific and structured.

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 examples (e.g., 'What is the US trade deficit with China?') and implies alternatives by contrasting with sibling tools that require specific parameters or schemas, making it evident this is for natural language queries.

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

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

Annotations declare read-only, open-world, non-destructive. Description adds rich behavioral details: market resolution, classification into categories (crypto, Fed, etc.), fan-out to relevant packs, and the nature of the output. No contradictions.

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

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

Three dense sentences, front-loaded with purpose. Every sentence provides essential information: what it does, how it works, and when to use it. 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?

No output schema, but description explains return value (evidence packet + comparison). For a complex research tool with fan-out, it covers inputs, process, and output adequately, though could detail evidence packet contents further.

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

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

Input schema covers both parameters with descriptions (100% coverage). Description adds value by explaining the 'depth' default ('thorough') and providing concrete examples for 'market'. Exceeds baseline 3.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types (slug, URL, question text) and output (evidence packet + market-vs-model comparison), distinguishing it from sibling tools like validate_claim.

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 example queries ('should I bet on X?', 'what does the data say...'), but does not mention when to avoid using the tool or point to alternatives. Still provides clear context for appropriate use.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'finds' cocktails, implying a read-only operation, but does not disclose any behavioral traits such as rate limits, pagination, error handling, or response format. The description is minimal and lacks critical operational details for effective use.

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 functionality ('Find cocktails that use a specific ingredient') and includes helpful examples. There is no wasted text, and it is appropriately sized for a simple tool with one parameter.

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 lack of annotations and output schema, the description is incomplete. It does not address behavioral aspects like response format, error conditions, or usage constraints. For a tool with no structured metadata, the description should provide more context to ensure the agent can use it correctly, but it falls short.

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 'ingredient' well-documented in the schema. The description adds minimal value beyond the schema by providing examples ('e.g., "vodka", "lime juice", "gin"'), but does not explain semantics like case sensitivity, partial matches, or validation rules. Baseline score of 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 a specific verb ('Find') and resource ('cocktails'), specifying it filters by ingredient. It distinguishes from 'get_cocktail' (likely retrieves a single cocktail), 'random_cocktail' (random selection), and 'search_cocktails' (broader search), but does not explicitly contrast with siblings. The examples ('vodka', 'lime juice', 'gin') help clarify the 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 when looking for cocktails based on a specific ingredient, but does not provide explicit guidance on when to use this tool versus alternatives like 'search_cocktails'. No exclusions or prerequisites are mentioned, leaving the agent to infer context 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, the description must disclose behavioral traits. It describes the return format ('paired data + pipeworx:// resource URIs') and data sources (SEC EDGAR for companies, FDA for drugs). It implies a read-only operation and no destructive side effects, but does not mention rate limits or error handling.

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

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

The description is three sentences, front-loaded with the core action. Every sentence adds value: purpose, type-specific details, and efficiency justification. No extraneous information.

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

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

Given no output schema, the description adequately explains the return data and provides context for each type. It covers the essential aspects of input, behavior, and output. The tool is well-specified for an agent.

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

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

Schema coverage is 100%, and the description adds significant context beyond the schema. For example, it explains what metrics are returned for each 'type', and provides examples for 'values' (e.g., tickers/CIKs for company, drug names for drug). This helps the agent select appropriate inputs.

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: 'Compare 2–5 entities side by side in one call.' It specifies the two entity types (company, drug) and the exact data fields returned for each. It also distinguishes from siblings by noting it replaces 8–15 sequential agent calls, implying efficiency.

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 indicates when to use the tool (to compare multiple entities in a single call) and emphasizes its efficiency over sequential calls. However, it does not explicitly list conditions when not to use it or name alternative tools.

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

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

No annotations are provided, so the description carries the full burden. It describes the search behavior and return format ('most relevant tools with names and descriptions'), but doesn't disclose important behavioral traits like whether this is a read-only operation, potential rate limits, authentication requirements, or how relevance is determined. The description adds some context but leaves significant behavioral aspects unspecified.

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 explains what the tool does, and the second provides crucial usage guidance. No wasted words, and the most important information ('Call this FIRST') is appropriately 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 purpose (discovery/search), 2 parameters with 100% schema coverage, no output schema, and no annotations, the description is reasonably complete. It explains the core functionality and when to use it, though it could benefit from more detail about the return format and search behavior. The lack of output schema means the description should ideally explain what the response looks like, which it partially does by mentioning 'names and descriptions'.

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 thoroughly. The description mentions searching 'by describing what you need' which aligns with the 'query' parameter, but doesn't add meaningful semantic context beyond what the schema provides. Baseline 3 is appropriate when 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 sibling tools by mentioning it's for when you have '500+ tools available' (unlike the cocktail-related siblings). It explicitly tells what it returns ('most relevant tools with names and descriptions').

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 ('Call this FIRST when you have 500+ tools available and need to find the right ones for your task') and distinguishes it from alternatives by implying this is the discovery mechanism rather than direct tool invocation. It clearly sets the 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?

No annotations provided, so description carries full burden. It discloses that it returns citation URIs and aggregates data from multiple sources. Lacks details on destructive behavior, auth needs, or rate limits, but provides sufficient behavioral context for typical use.

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 dense paragraph that front-loads purpose and specifics. Efficient but could benefit from bullet points or clearer separation of alternatives.

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 multi-source complexity and no output schema, description covers included data types and alternatives. Lacks mention of error handling or data freshness, but overall complete for an aggregation 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 adds useful context: explains value can be ticker or CIK, clarifies that names are not supported (hinting to use resolve_entity). Adds value beyond schema fields.

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

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

The description clearly states it returns a full profile of an entity across Pipeworx packs, specifies supported type (company), and lists included data types. It distinguishes itself from siblings by noting 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 tells when to use (company profile) and when not (federal contracts -> usa_recipient_profile). Also advises using resolve_entity if only a name is available.

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 states the tool deletes a memory, implying a destructive mutation, but doesn't cover critical aspects like whether deletion is permanent, requires specific permissions, has side effects (e.g., affecting other tools), or what happens on success/failure. This is a significant gap for a mutation tool.

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 directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy to parse 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 (a destructive operation with no annotations and no output schema), the description is incomplete. It lacks details on behavioral traits (e.g., permanence, error handling), usage context, and expected outcomes, which are crucial for safe and effective tool invocation by 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 description coverage is 100%, with the single parameter 'key' documented as 'Memory key to delete'. The description adds no additional meaning beyond this, such as key format or examples. With high schema coverage, the baseline score of 3 is appropriate, as the schema handles the parameter documentation adequately.

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 the resource ('a stored memory by key'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'recall' or 'remember', which likely handle memory retrieval and storage respectively, so it misses the highest 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?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing memory key), exclusions, or comparisons to siblings like 'recall' (for retrieval) or 'remember' (for storage), leaving usage context unclear.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive behavior. The description adds behavioral details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also confirms no destructive actions. 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: two sentences plus a bullet list of use cases. It front-loads the purpose and action, with every sentence contributing value. No fluff.

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

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

For a simple tool with 2 parameters and no output schema, the description adequately explains the output ('single text blob ready to drop at site-root/llms.txt') and the process. It could mention that the output is a markdown string, but it is 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 the baseline is 3. The description does not add extra meaning beyond the schema for the parameters (url and max_links). It mentions 'Fetches the page' but does not elaborate on parameter details.

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: generating a production-ready llms.txt file for a given URL. It explains the process (fetch, extract, emit) and the output format. This is a specific verb+resource that distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 three use cases (client indexing, personal drafting, competitor auditing), giving clear context for when to use it. However, it does not explicitly state when not to use it or compare it to alternatives, which would make 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?

No annotations are provided, so the description carries the full burden. It states it retrieves details but does not disclose behavioral traits such as error handling (e.g., what happens if the ID is invalid), rate limits, or authentication needs. This leaves gaps 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 purpose ('Get full details') and includes essential context ('by its TheCocktailDB ID, including all ingredients and instructions') with zero waste, 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 low complexity (1 parameter, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose but lacks details on behavioral aspects like error handling or output format, which are important for a read operation with no structured output 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?

The schema description coverage is 100%, so the schema already documents the 'id' parameter with examples. The description adds minimal value by mentioning 'TheCocktailDB ID' but does not provide additional syntax or format details beyond what the schema provides, meeting the baseline for high 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 full details'), the resource ('a cocktail'), and the method ('by its TheCocktailDB ID'), distinguishing it from sibling tools like 'random_cocktail' or 'search_cocktails' which serve different purposes.

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 when you have a specific cocktail ID and need comprehensive details, but it does not explicitly state when not to use it or name alternatives like 'search_cocktails' for when you don't have an ID. The context is clear but lacks explicit exclusions.

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

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

The description discloses rate limiting (5 per day) and notes the tool is free. It also warns against including end-user prompt verbatim. Since no annotations exist, the description bears the transparency burden and handles it well, though it does not detail the tool's internal behavior or response.

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 four sentences long, each serving a purpose: stating the action, listing use cases, giving formatting guidelines, and mentioning rate limits/cost. 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 simple feedback tool with no output schema, the description covers purpose, usage, and constraints adequately. It could mention what happens after submission (e.g., team review), but it is largely 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% with descriptions for all parameters. The description adds value by reinforcing the enum's purpose (e.g., 'Use for bug reports...') and by giving specific guidance on the message field (describe what was tried, exclude prompt).

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 to the Pipeworx team and lists specific use cases (bug reports, feature requests, missing data, praise). It distinguishes itself from sibling tools like ask_pipeworx (for questions) or discover_tools (for exploration).

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 tells when to use the tool (for feedback types) and provides guidance on what to include/exclude. It mentions rate limiting but does not explicitly state when not to use it (e.g., for general questions). Still, it offers clear context.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. Description adds valuable context: data derived from CF analytics, no PII, caching behavior (5min-1h). Goes beyond annotations to inform agent about data freshness and safety.

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

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

Three sentences, front-loaded with core purpose, no filler. Every sentence adds value, achieving high information density without verbosity.

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 (1 param, no output schema), the description covers purpose, usage, behavior, and parameter semantics thoroughly. Leaves no significant gap for the agent to infer.

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 the only parameter 'window' with enum and description. Description adds practical guidance on window selection ('shorter windows surface what's hot right now; longer windows show steady-state demand'), enriching schema meaning.

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

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

Clearly states it returns top tools, packs, and call volume over recent windows, using specific verbs like 'returns' and 'What other AI agents are calling'. Distinct from siblings like ask_pipeworx or discover_tools by focusing on aggregated trending data.

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?

Lists three concrete use cases (discovering hot sources, confirming canonical choice, checking alignment) but does not explicitly mention when not to use or alternatives. However, the use cases are clear and contextually appropriate.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds detailed behavioral context: the tool walks child markets, extracts dates/thresholds, and sorts them to enforce monotonicity. It discloses that it reports violating pairs, which is consistent with read-only behavior. 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 (~5 sentences) and well-structured: it begins with the core purpose, explains the underlying logic, specifies input, and summarizes output format. Every sentence adds essential information without redundancy.

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

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

Given the tool has one parameter, good annotations, and no output schema, the description is complete. It details input use, the algorithmic process, and the output structure including fields. No missing information is necessary 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?

The input schema has one parameter 'event' with a brief description. The tool's description adds significant meaning by explaining how the event slug is used (e.g., 'walk the child markets'), linking it to the arbitrage logic. Despite 100% schema coverage, the description enriches the parameter semantics beyond the schema's minimal text.

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: finding arbitrage opportunities in Polymarket events by detecting monotonicity violations. It explains the underlying logic with an example (e.g., later window should have higher price) and specifies input requirements (event slug or URL) and output format (list of pairs with gap and suggested trade). This uniquely distinguishes it from sibling tools like polymarket_edges.

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

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

The description implicitly provides usage context by explaining when arbitrage arises (when earlier market trades higher than later one). However, it does not explicitly state when to use this tool versus alternatives like polymarket_edges or bet_research, nor does it list prerequisites or when not to use it.

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

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

Annotations already provide readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds rich behavioral context: it covers crypto-price bets, uses a lognormal model from FRED and live coinpaprika price, fetches price history once, computes model probability per market, and ranks by |edge|. This goes beyond the annotations to inform the agent about data sources, computational steps, and output content.

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 yet comprehensive, structured as a single paragraph that logically flows from purpose to methodology to output. Every sentence adds value, and the core action is front-loaded. It avoids verbosity while covering all necessary aspects.

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 (scanning, grouping, fetching, computing, ranking) and the absence of an output schema, the description provides a thorough overview. It explains the algorithm in sufficient detail for an agent to understand data sources and processing steps. However, it could be slightly more explicit about the exact output fields (e.g., market name, edge, direction), though the mention of 'suggested trade direction' is 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?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema: it mentions 'default 10' for limit and 'Polymarket volume window' for window, but these are already in the schema descriptions. No new parameter semantics 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 clearly states it scans high-volume Polymarket markets and returns those where Pipeworx data disagrees with market price, specifying the asset class (crypto-price bets) and model (lognormal from FRED + coinpaprika). It explicitly says it's built for the 'what should I bet on today' question, distinguishing it from siblings by emphasizing opportunity discovery and edge ranking.

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 usage context: scanning top markets, grouping by asset, computing model probability, and returning ranked edges. It implies when to use (discovering opportunities without manual browsing) but does not explicitly state when not to use or compare to alternative sibling tools like polymarket_arbitrage.

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 confirm the tool is read-only, idempotent, and non-destructive. The description adds context that the spread is a real arb signal (2-25pp) and details the return format (leg prices in 0-1, spread in percentage points). 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 (two paragraphs), well-structured, and front-loaded with the core purpose. Every sentence adds useful information without redundancy.

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

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

The description covers the main use cases and return format. However, it is slightly incomplete regarding behavior when both topic and explicit parameters are provided simultaneously, and does not mention error handling or edge cases. Nonetheless, it is adequate for the tool's complexity.

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

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

All three parameters have schema descriptions. The description adds value by listing the specific topic values and providing examples of explicit tickers and slugs. It explicitly states that explicit parameters override the topic-mapped side, which is not in the schema.

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

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

Description clearly states it calculates spread between Kalshi and Polymarket for the same event, explains why the spread exists (different participant pools), and specifies two usage modes (topic shortcuts or explicit tickers). This distinguishes it from siblings like polymarket_arbitrage which likely focuses on intra-platform 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 explains two modes: topic for pre-mapped macro shortcuts and explicit tickers for custom pairings. It lists the topic keywords and gives examples of explicit identifiers. However, it does not provide explicit guidance on when not to use this tool or how it compares to alternative 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'full details including ingredients and instructions,' which adds useful context about the output format. However, it lacks information on potential behavioral traits such as rate limits, error conditions, or whether the randomness is truly uniform, leaving gaps in 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 a single, well-structured sentence that efficiently conveys the tool's purpose and key details ('full details including ingredients and instructions'). It is front-loaded with the main action and contains no redundant information, making it highly concise and effective.

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

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

Given the tool's simplicity (0 parameters, no annotations, no output schema), the description is adequate but minimal. It explains what the tool does but does not address potential complexities like output format details or error handling. For a read-only tool with no parameters, this is acceptable but leaves room for more 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?

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately does not discuss parameters, focusing instead on the tool's purpose. This meets the baseline for tools with no parameters, as it avoids unnecessary details.

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 ('Get a random cocktail') and the resource ('cocktail'), specifying that it returns 'full details including ingredients and instructions.' However, it does not explicitly differentiate from siblings like 'get_cocktail' (which likely fetches a specific cocktail) or 'search_cocktails' (which allows filtering), leaving some ambiguity in 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 implies usage when a random cocktail is needed, but it does not provide explicit guidance on when to use this tool versus alternatives like 'cocktails_by_ingredient' or 'get_cocktail.' No exclusions or prerequisites are mentioned, leaving the agent to infer context from tool names 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 full burden. It discloses the tool's dual behavior (retrieve vs list) and persistence across sessions, which is valuable. However, it doesn't mention error handling (e.g., what happens if key doesn't exist), return format, or any rate limits/constraints, leaving 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 efficiently structured in two sentences: the first defines the dual operations with parameter logic, the second provides usage context. Every phrase adds value with zero redundancy, making it easy to parse and apply.

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 annotations and no output schema, the description adequately covers purpose and basic usage but lacks details on return values, error conditions, or performance characteristics. For a tool with one parameter and simple operations, it's minimally complete but leaves the agent to infer behavioral specifics.

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 adds meaningful context: it explains the semantic effect of omitting the key (switches to list mode) and relates the parameter to 'memory key to retrieve,' reinforcing the schema's description. This provides practical usage insight beyond the schema's technical definition.

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', 'all stored memories'), distinguishing it from sibling tools like 'remember' (store) and 'forget' (delete). It explicitly defines two distinct operations based on parameter presence.

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

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

The description provides explicit usage guidance: 'Use this to retrieve context you saved earlier in the session or in previous sessions' establishes the primary use case. It also specifies when to use each mode: 'Retrieve... by key, or list all stored memories (omit key)' with clear parameter-based branching.

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 parallel fan-out to SEC EDGAR, GDELT, USPTO, and return structure (structured changes, total_changes, pipeworx:// URIs). No annotations provided, so description carries burden well, though missing rate limits or auth.

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

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

Three sentences with zero waste. Front-loaded with main purpose, then details. Ideal 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?

No output schema, but description covers return format adequately. All parameters explained, behavior clear. Complete for the tool's moderate complexity.

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

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

Schema coverage is 100%, but description adds value: explains 'since' format with examples (ISO date, relative), 'value' as ticker/CIK, and 'type' limitation to company. Exceeds schema explanation.

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 'What's new about an entity since a given point in time' with specific verb and resource. Distinguishes from siblings as a change-monitoring tool, no direct overlap.

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

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

Gives explicit use cases: 'brief me on what happened with X' or change-monitoring workflows. Does not list alternatives or 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?

With no annotations provided, the description carries the full burden of behavioral disclosure and does this well. It reveals important behavioral traits: persistence characteristics (authenticated users get persistent memory, anonymous sessions last 24 hours) and the tool's role in maintaining context across tool calls, which goes beyond basic parameter documentation.

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 sized with two focused sentences that each earn their place. The first sentence states the core purpose, and the second provides crucial behavioral context about persistence. There's zero wasted language or redundancy.

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

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

For a 2-parameter tool with no annotations and no output schema, the description provides good contextual completeness. It covers purpose, usage context, and important behavioral traits. The main gap is lack of information about return values or error conditions, but given the tool's relative simplicity, this is acceptable.

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

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

With 100% schema description coverage, the input schema already documents both parameters thoroughly. The description doesn't add significant meaning beyond what the schema provides about key and value parameters, though it does reinforce the use cases through examples like 'findings, addresses, preferences, notes'.

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 resources ('in your session memory'), distinguishing it from sibling tools like 'recall' (retrieve) and 'forget' (delete). It explicitly identifies the tool's function as data persistence across tool 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 provides clear context for when to use this tool ('to save intermediate findings, user preferences, or context across tool calls'), but doesn't explicitly mention when not to use it or name specific alternatives. It distinguishes from 'recall' by implication but doesn't provide explicit exclusion 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?

No annotations are provided, so the description must fully disclose behavior. It mentions the return values (ticker, CIK, name, URIs) but fails to disclose whether the operation is read-only, requires authentication, or has any side effects or error states. This is insufficient for an unannotated tool.

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: two sentences plus a short example. It front-loads the purpose, then provides key details and a benefit statement. 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 tool with only two parameters and no output schema, the description covers the core functionality, inputs, and outputs. It is missing any mention of error handling or limitations (e.g., only company type in v1), but overall it is sufficient for an agent to understand and use the tool correctly.

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

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

Schema coverage is 100%, so the schema documents both parameters. However, the description adds concrete examples (e.g., 'AAPL', '0000320193', 'Apple') and clarifies that 'value' can be a ticker, CIK, or name, which goes beyond the schema's generic 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 verb 'resolve', the resource 'entity', and the outcome 'canonical IDs'. It also distinguishes itself by claiming it replaces 2–3 lookup calls, implying efficiency over alternative approaches.

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 specifies that v1 supports type 'company' and gives example inputs (ticker, CIK, name). While it does not explicitly state when not to use it, the examples and the 'Replaces 2–3 lookup calls' provide clear context. No sibling tool directly competes.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral details: it probes each entity with ai_visibility_check, ranks results, and returns a list. No contradictions, and it adds value beyond annotations.

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

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

The description is two sentences. The first sentence captures the core function, and the second adds use case and return details. No wasted words; front-loaded and efficient.

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

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

Despite no output schema, the description explains the return value (ranked list with score, confidence, signal density per entity). It also describes the internal process. Given the tool's complexity and available annotations, 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 coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is treated as the 'subject' and the rest as competitors, and that context disambiguates names, which is not in the schema.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, using verbs like 'compare', 'probes', 'ranks', and 'surfaces'. It distinguishes from the sibling 'ai_visibility_check' which is a single-entity 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 provides a concrete use case ('competitive AI-marketing audits') and an example question. It implies comparison of multiple entities but does not explicitly state when not to use it or list 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 mentions the tool returns a list with key details, but lacks information on error handling, rate limits, authentication needs, or pagination. For a search tool, this is a significant gap in transparency, though it doesn't contradict 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 two concise sentences that efficiently convey the tool's function and output without unnecessary words. It is front-loaded with the core purpose, making it easy for an agent to parse 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 no annotations and no output schema, the description is incomplete for a search tool. It lacks details on the structure of returned data (e.g., what 'key details' include), error cases, or performance constraints, which are crucial for effective tool invocation by 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?

The input schema has 100% description coverage, with the 'query' parameter documented as 'Cocktail name or partial name to search for'. The description adds no additional parameter details beyond implying the search is name-based, so it meets the baseline 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: 'Search for cocktails by name' specifies the verb (search) and resource (cocktails), and 'Returns a list of matching cocktails with key details' indicates the outcome. However, it doesn't explicitly differentiate from sibling tools like 'cocktails_by_ingredient' or 'get_cocktail', 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?

The description provides no guidance on when to use this tool versus alternatives like 'cocktails_by_ingredient' (search by ingredient) or 'get_cocktail' (retrieve a specific cocktail). It only states what the tool does, without context for selection among siblings, leaving the agent to infer 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?

Without annotations, the description provides some behavioral context: it's v1, supports specific claim types, and replaces multiple calls. However, it does not disclose limitations (e.g., only US companies, only certain metrics) or other behavioral traits like auth requirements or rate limits.

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 three sentences, each providing essential information. It is front-loaded with the main purpose and efficiently covers domain, return values, and value proposition 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 tool with one parameter and no output schema, the description is sufficiently complete. It explains the tool's purpose, supported claims, return values (verdict, citation, delta), and even its composite nature, covering all necessary context.

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

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

Schema description coverage is 100%, providing a clear description of the 'claim' parameter. The description adds value by specifying the nature of claims (natural-language financial claims) and giving examples, enriching the schema's meaning.

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

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

The description explicitly states the tool's purpose: fact-check a natural-language claim against authoritative sources. It specifies the domain (company-financial claims for public US companies) and the sources (SEC EDGAR + XBRL), making it clear and distinct 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 implies the tool is for financial claim verification but does not explicitly state when to use it versus alternatives or when not to use it. It lacks exclusions or context about other tools.

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