ureweries

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 picks the right data source and fills arguments automatically, handles natural language questions, and returns results. However, it doesn't mention limitations like rate limits, authentication needs, or error handling, leaving some 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 appropriately sized and front-loaded: the first sentence states the core purpose, followed by explanatory details and examples. Every sentence earns its place by clarifying functionality or providing practical guidance, with no wasted words.

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

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

Given the tool's complexity (natural language processing to select data sources) and lack of annotations/output schema, the description is mostly complete: it explains what the tool does, how to use it, and provides examples. However, it doesn't detail the return format or potential limitations, leaving some gaps for an AI agent to infer behavior.

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

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

Schema description coverage is 100%, so the schema already documents the single 'question' parameter as 'Your question or request in natural language.' The description adds marginal value by emphasizing 'plain English' and providing examples, but doesn't offer 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 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 from data source'), and distinguishes from siblings by emphasizing natural language input without needing to browse tools or learn schemas.

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

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

The description explicitly states when to use this tool: 'No need to browse tools or learn schemas — just describe what you need.' It provides clear alternatives (implicitly, use other tools if you want to browse or learn schemas) and includes concrete examples like 'What is the US trade deficit with China?' to illustrate appropriate use cases.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Find breweries') but doesn't describe key traits like whether it's a read-only operation, potential rate limits, error handling, or the format of results. This leaves significant gaps in understanding how the tool behaves beyond its basic purpose.

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: 'Find breweries located in a specific city.' It is front-loaded with the core purpose, has zero wasted words, and is appropriately sized for the tool's complexity. Every part of the sentence earns its place by clearly conveying the tool's function.

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

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

Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is incomplete. It lacks details on behavioral traits, usage context, and result handling. Without annotations or an output schema, the description should provide more context to help the agent invoke the tool correctly, but it falls short, leaving gaps in understanding.

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

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

The input schema has 100% description coverage, with clear details for both parameters ('city' and 'limit'). The description adds no additional meaning beyond what the schema provides, such as explaining parameter interactions or edge cases. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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

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

The description clearly states the tool's purpose: 'Find breweries located in a specific city.' This includes a specific verb ('Find') and resource ('breweries'), and it specifies the scope ('in a specific city'). However, it does not explicitly differentiate from sibling tools like 'get_brewery' or 'search_breweries', which might have overlapping or distinct functionalities, so it doesn't reach 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 lacks any mention of sibling tools, prerequisites, or exclusions. For example, it doesn't clarify if this is for exact city matches or broader searches, leaving the agent to infer usage without explicit direction.

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 carries full burden. It states the tool returns paired data plus pipeworx:// URIs and sources data from SEC EDGAR and FDA. While it doesn't detail auth, rate limits, or idempotency, the behavior is adequately implied as a read-only comparison operation.

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 serving a purpose: purpose statement, type-specific details, output description, and efficiency claim. No redundant information. Front-loaded with the core action.

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

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

Given no output schema, the description explains return content (paired data, URIs). It covers the main use cases (company and drug) and key metrics. Minor omissions: no mention of error handling or prerequisites, but overall complete for this comparison tool.

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

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

Input schema has 100% description coverage for both parameters. The description enriches the schema by specifying example formats for values (e.g., ["AAPL","MSFT"] for company) and explaining the enum choices for type. This adds meaningful context beyond the schema.

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

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

The description explicitly states the tool compares 2-5 entities side by side in one call, with distinct metrics for company (revenue, net income, cash, long-term debt from SEC EDGAR) and drug types (adverse-event reports, FDA approvals, active trials). This clearly differentiates from sibling tools like get_brewery or search_breweries.

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

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

The description provides usage context by noting it replaces 8-15 sequential calls, implying efficiency gains. It gives type-specific guidance for input formats (tickers for company, names for drug). However, it lacks explicit when-not-to-use or alternative tool mentions.

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 full burden. It discloses that this is a search/read operation (implied by 'Search' and 'Returns'), but doesn't mention behavioral aspects like rate limits, authentication needs, or what happens with empty results. The description adds some context about the catalog size but lacks details on performance 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 perfectly concise with two sentences that each earn their place. The first sentence states the purpose and return value, the second provides crucial usage guidance. No wasted words, and the most important information ('Call this FIRST') is front-loaded in the second sentence.

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

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

Given the tool's moderate complexity (search function with 2 parameters), 100% schema coverage, but no annotations or output schema, the description does well by explaining the core purpose and critical usage context. However, it could better address what the return format looks like (though no output schema exists) and potential limitations. The sibling tool context is appropriately addressed.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description doesn't add any parameter-specific information beyond what's in the schema (it mentions 'describing what you need' which aligns with the query parameter but adds no new details). Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('Search the Pipeworx tool catalog') and resource ('tool catalog'), and distinguishes it from siblings by mentioning it's for when you have '500+ tools available' (unlike the brewery-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 it's for discovery rather than direct operations (unlike the brewery tools which perform specific actions). It gives clear context about the tool catalog size prerequisite.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Delete' implies a destructive mutation, it doesn't specify whether this operation is reversible, what permissions are required, whether it's idempotent, or what happens on success/failure. For a destructive tool with zero annotation coverage, this represents a significant gap 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 perfectly concise at just 6 words, front-loading the essential action ('Delete') and resource. Every word earns its place with zero redundancy or unnecessary elaboration, making it immediately scannable 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?

For a destructive mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what constitutes success/failure, return values, error conditions, or system implications. Given the complexity of a delete operation and lack of structured coverage, more contextual information is needed for safe and effective use.

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

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

Schema description coverage is 100%, with the single parameter 'key' clearly documented as 'Memory key to delete.' The description adds minimal value beyond this, merely restating that deletion occurs 'by key' without explaining key format, constraints, or examples. 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 action ('Delete') and resource ('a stored memory by key'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'recall' (which presumably retrieves memories) or explain what constitutes a 'stored memory' in this context, preventing 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 'recall' (for retrieval) or 'remember' (for storage). There's no mention of prerequisites, error conditions, or what happens if the key doesn't exist, leaving the agent with insufficient context for optimal tool selection.

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 this is a read operation ('Get'), but doesn't mention any behavioral traits like error handling (e.g., what happens if the ID is invalid), rate limits, authentication needs, or response format. For a tool with no annotation coverage, this leaves significant gaps in understanding how it behaves.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Get full details for a specific brewery') and specifies the key constraint ('by its Open Brewery DB ID'). There is no wasted verbiage, and every word earns its place in clarifying the tool's function.

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

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

Given the tool's low complexity (single parameter, no nested objects) and high schema coverage, the description is minimally adequate. However, with no annotations and no output schema, it lacks details on behavioral aspects like error handling or response structure. For a simple lookup tool, this is acceptable but leaves room for improvement in transparency.

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 'id' fully documented in the schema as the Open Brewery DB brewery ID with an example. The description adds no additional parameter semantics beyond what the schema provides, such as format constraints or usage notes. 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 verb ('Get full details') and resource ('for a specific brewery'), making the purpose unambiguous. It specifies the lookup mechanism ('by its Open Brewery DB ID'), which distinguishes it from siblings that filter by city or search broadly. However, it doesn't explicitly contrast with sibling tools like 'breweries_by_city' or 'search_breweries' in the description text itself.

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 brewery ID and need full details, which is clear from context. However, it doesn't explicitly state when to use this tool versus alternatives like 'search_breweries' for broader queries or 'breweries_by_city' for location-based filtering. No exclusion criteria or prerequisites are 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, the description carries full burden. It discloses the rate limit and states 'Free' (no cost). However, it does not mention whether the tool returns a response, is asynchronous, or how feedback is processed, leaving some behavioral ambiguity.

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

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

The description is concise (three sentences) and well-structured: purpose first, then usage guidelines and constraints. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity (fire-and-forget feedback submission) and no output schema, the description adequately covers why, what, and constraints. It could mention whether there is a confirmation, but overall it is complete for typical use.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context for the message parameter (e.g., 'Describe what you tried...') but does not significantly enhance understanding of the type enum or context object beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Send feedback to the Pipeworx team.' It enumerates specific use cases (bug reports, feature requests, missing data, praise), making it distinct from sibling tools which are focused on data retrieval or memory operations.

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

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

The description explicitly specifies when to use the tool (for feedback types) and provides an exclusion rule: 'do not include the end-user's prompt verbatim.' It also mentions the rate limit (5 per day), guiding appropriate usage frequency.

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

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

No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: it can retrieve by key or list all memories, and memories persist across sessions. However, it doesn't mention error handling (e.g., if a key doesn't exist), performance aspects like rate limits, or the format of returned data, leaving gaps in behavioral context.

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

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

The description is appropriately sized and front-loaded, with two concise sentences that directly state the tool's purpose and usage. Every sentence adds value: the first explains what the tool does, and the second provides context on when to use it, with no wasted words 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?

Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and parameter behavior adequately. However, it lacks details on return values (since no output schema exists) and error cases, which could be helpful for full contextual understanding.

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

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

Schema description coverage is 100%, so the schema already documents the 'key' parameter. The description adds meaningful semantics by explaining the dual functionality: retrieving by key or listing all keys when omitted. This clarifies the parameter's role beyond the schema's basic description, though it doesn't provide additional syntax or format 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 with specific verbs ('retrieve', 'list') and resources ('previously stored memory', 'all stored memories'), and distinguishes it from siblings like 'remember' (store) and 'forget' (delete). It explicitly mentions retrieving context saved earlier in the session or previous sessions, which clarifies its role in memory management.

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.' It also distinguishes when to use this tool versus alternatives by specifying behavior based on parameter presence ('omit key' to list all keys), though it doesn't name specific sibling alternatives, the context of memory operations 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 and discloses key behavioral traits: it explains storage persistence (authenticated users get persistent memory; anonymous sessions last 24 hours), which is crucial for understanding data lifespan. However, it lacks details on error handling or capacity 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 appropriately sized with two sentences: the first states the purpose and usage, and the second adds critical behavioral context. Every sentence earns its place by providing 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's complexity (simple storage with 2 parameters), no annotations, and no output schema, the description is mostly complete: it covers purpose, usage, and key behavioral traits like persistence. However, it does not explain return values or error cases, which could be helpful.

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

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

Schema description coverage is 100%, so the schema already documents both parameters ('key' and 'value') with examples. The description adds no additional parameter semantics beyond what the schema provides, meeting the baseline for high schema coverage.

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

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

The description clearly states the verb 'store' and the resource 'key-value pair in your session memory', specifying it's for saving intermediate findings, user preferences, or context across tool calls. It distinguishes from siblings like 'recall' (retrieval) and 'forget' (deletion) by focusing on storage.

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

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

It provides clear context on when to use this tool (e.g., for saving intermediate findings, user preferences, or context across tool calls), but does not explicitly mention when not to use it or name alternatives like 'recall' for retrieval or 'forget' for deletion, though the purpose implies differentiation.

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

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

No annotations are provided, so the description carries the full burden. It discloses the operation (resolve, likely read-only) and mentions versioning (v1: type='company'). It does not discuss error handling, rate limits, or permissions, but the core behavior is adequately described.

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, each serving a purpose: first states the overall function, second details parameters and examples, third summarizes benefits. No wasted words, and the key information is front-loaded.

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

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

Given the tool's simplicity (2 params, no output schema), the description covers inputs, outputs, and benefit. It does not mention behavior for ambiguous names or errors, but overall it provides sufficient context 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?

With 100% schema coverage, the description adds value by providing concrete examples (AAPL, 0000320193, Apple) and explaining how the 'value' parameter can be a ticker, CIK, or name. This enriches the schema's generic descriptions.

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

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

The description clearly states the tool resolves an entity to canonical IDs across Pipeworx data sources, specifies the current version supports company type, and lists accepted inputs (ticker, CIK, name) and outputs (ticker, CIK, name, URIs). It is distinct from sibling tools like get_brewery or search_breweries, which focus on breweries.

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 gives context by stating it replaces 2–3 lookup calls, implying efficiency for entity resolution. However, it does not explicitly state when not to use this tool or name alternative tools, but the sibling list shows no direct competitor for company resolution.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the return format ('list of matching breweries with location and contact details') which is helpful, but doesn't cover important aspects like pagination behavior, rate limits, authentication requirements, error conditions, or whether this is a read-only operation. For a search tool with zero annotation coverage, this represents significant 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 appropriately concise with two sentences that efficiently convey the core functionality and return format. It's front-loaded with the main purpose. While slightly more detail about behavioral aspects could improve it, every sentence earns its place, warranting a score of 4.

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 search tool with 2 parameters (100% schema coverage) and no output schema, the description provides adequate but incomplete context. It covers the basic purpose and return format but lacks behavioral details that would be important for an AI agent. Without annotations or output schema, the description should do more to explain how results are structured and what limitations exist.

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 adds minimal value beyond the schema - it mentions searching 'by name' which aligns with the 'query' parameter description, but doesn't provide additional context about parameter interactions or search semantics. This meets the baseline of 3 when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Search for breweries by name' specifies the verb (search) and resource (breweries). It distinguishes from 'breweries_by_city' by focusing on name-based search rather than location, but doesn't explicitly differentiate from 'get_brewery' which might retrieve a single brewery by ID. This earns a 4 for clear purpose without full sibling differentiation.

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 'breweries_by_city' or 'get_brewery'. It doesn't mention prerequisites, exclusions, or contextual factors. This lack of comparative usage information results in a score of 2.

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