cocktails

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?

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?

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?

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?

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.