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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety and side-effect profile is fully covered. The description adds clarity about what the comparison includes but does not add further behavioral details such as output structure, ordering, or handling of ambiguous coffee names. This matches the baseline expectation when annotations carry the behavioral burden.

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, front-loaded sentence that efficiently communicates the purpose and key output dimensions. Every element earns its place, with no redundant wording or repetition of schema 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?

The description lists the specific comparison facets, which effectively serves as an informal output description given that no output schema exists. The schema covers both required parameters, annotations cover safety, and the tool is simple enough that the description is sufficient for correct invocation in most cases.

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

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

Schema coverage is 100%, with both coffee_a and coffee_b described as 'id or name'. The description refers to 'two coffees' but does not add meaningful detail beyond what the schema already provides. This meets the baseline for schema-covered parameters.

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 (compare), the resource (two coffees), and the scope (side-by-side comparison of roast, body/acidity/sweetness, flavors, brew methods, and price). This distinguishes it from siblings like get_coffee, which targets a single coffee, and find_similar, which implies recommendation rather than direct 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 phrase 'side-by-side comparison' and the two coffee parameters make the intended use clear: when an agent needs to compare two specific coffees. It does not explicitly name alternatives or exclusions, but the contrast with the sibling tools is strongly implied by the 'two coffees' framing.

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 annotations already signal read-only, idempotent, non-destructive behavior. The description adds a useful behavioral detail beyond those annotations: if curated Percolate recipes aren't available, it falls back to a roast-based starting point. This conditional behavior is exactly the kind of nuance an agent would not otherwise know.

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 text is compact and front-loaded: the first sentence gives the core purpose and details immediately, and the parenthetical adds concrete recipe fields without extra prose. The optional scoping clause earns its place. There is no repetition or filler.

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 read-only tool with only two parameters, no output schema, and rich annotations, the description covers the important behavior: what guidance is returned, the fallback when curated data is unavailable, and an optional filter. A tiny bit more explicit return-structure detail could push it higher, but overall it is complete for the tool's simplicity.

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 already 100%, with both coffee and brew_method described clearly. The description adds only light extra context by saying the request can be 'scoped to your brew method' and by listing recipe fields like ratio and temperature; this is helpful but not necessary to understand the parameters.

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 opens with a specific verb and resource — 'Brew guidance for a specific coffee' — and states what the result includes: curated recipes from the Percolate catalog (ratio, temperature, grind) or a roast-based starting point. This clearly differentiates it from sibling tools like search_coffees or get_coffee, which focus on finding or describing coffee, not brewing instructions.

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 makes it clear when to use the tool: once the agent has a specific coffee and wants brew guidance, optionally scoped to a brew method. It does not explicitly name alternatives or say 'use X if you have no coffee selected,' but the provided context is sufficient to route the call correctly.

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 establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral detail beyond the schema: deterministic scoring and ranking based on structured tasting data. This clarifies what the agent can expect without promising anything contradictory.

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 one tightly composed sentence with no wasted words. It front-loads the core purpose, states the ranking factors, and then qualifies determinism and data source—all in under 25 words.

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

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

For a simple two-parameter read-only tool, the description is complete enough: it explains what the tool does, how results are ranked, and that scoring is deterministic. No complexity or safety caveat is left to guesswork.

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 input schema already documents the 'coffee' and 'limit' parameters. The description adds no extra parameter-level context, which is fine because the schema carries the full burden.

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 coffees similar to a given one, ranked by shared flavor notes and roast/body/acidity/sweetness proximity. It identifies the specific resource and comparison criteria, distinguishing it from generic search or recommendation tools.

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

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

The phrase 'to a given one' clearly frames when the tool is appropriate: the caller already has a specific coffee in mind and wants similar options. It does not explicitly name sibling tools as alternatives, so it falls just short of the strongest usage guidance.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so no side-effect disclosure is needed. The description adds useful context by spelling out what the returned record contains, which helps set expectations because there is no output schema.

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

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

Two focused sentences with no filler; the main purpose is front-loaded and the parameter behavior is stated compactly. The content list is long but each item earns its place in telling an agent what to expect.

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 one-parameter, read-only lookup tool, the description is largely sufficient: it names the lookup modes and previews the output fields despite there being no output schema. It does not address ambiguous-name behavior or error cases, but those are not major gaps for this low-complexity 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 description coverage is 100%, so the schema already explains id_or_name as a coffee id or a name with an example. The description mostly repeats this information, adding only the 'Percolate' identifier context, which is minor.

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?

States a specific verb and resource: it returns 'Detailed record for one coffee' rather than a list or comparison. The inventory of content fields makes the scope clear and helps distinguish it from broader siblings like search_coffees or compare_coffees.

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?

Clearly implies when this is appropriate: when an agent needs a single coffee's full record and already has an id or name. It does not explicitly name alternative tools or excluded conditions, but the singular-scope phrasing gives solid 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?

The AI is a read-only, idempotent operation, which the annotations already disclose. The description adds a light behavioral fact: it turns the user's stated preferences into a set of coffee picks. It doesn't describe the output format, pagination behavior, or how the bouncer factors in each parameter, but given the annotation context, this is sufficient.

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?

It is a single, short sentence that is front-loaded with the main result: 'Personalized coffee picks.' The sentence packs all of the key inputs into a natural summary with no filler, making it ideal for scanning by an agent.

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 tool is a read-only, logically simple recommendation engine; the schema covers parameter types and defaults (limit default 5, allowed enums). The description adequately describes what the tool returns (coffee picks). An output schema would be helpful, but the absence is not critical here because the tool's purpose and inputs are fully identified. A small gap: it doesn't explicitly note that 'limit' controls the maximum number of picks, but that is already in the 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 description coverage is 80% (4 of 5 parameters have descriptions), so the schema already documents most fields. The description adds small real-world semantics: 'budget in USD' and 'the brew gear you own' as a way to describe brew_method. It does not significantly clarify the roast_level or limit, but those are already covered by the schema or acceptable defaults.

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 opens with 'Personalized coffee picks', which clearly states that this tool returns a set of recommendations based on the user's taste profile. It names the four key inputs (flavor preferences, budget, roast, brew setup) and effectively sets it apart from the sibling search and similarity tools. It doesn't explicitly single out any sibling, but the core purpose is unambiguous.

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

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

The description implies the expected usage: provide preferences, budget, roast, and brew gear to receive tailored coffee recommendations. But it doesn't tell the agent when to prefer this tool over alternatives like find_similar_coffee, what_to_brew, or difficult search_coffees. There is no exclusion or explicit contrasting with the sibling tools.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds value by clarifying the curated nature (1,100+ coffees) and the return payload (tasting profiles, brew methods, where-to-buy links), which is genuinely useful given there is no output schema. There is no contradiction with annotations.

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

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

Two tight sentences lead with the core searching action and then immediately cover filters and results. Every clause adds useful information, with no empty marketing 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 7-parameter optional search with no output schema, the description successfully communicates scope, fluent filtering, and return value content. It leaves details such as default pagination and sorting to the schema, which is acceptable for a read-only search tool.

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

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

The schema already describes 5 of 7 parameters and includes enums for category and roast_level, so the baselines are moderately high. The description adds a concise framing by enumerating the filter dimensions, but it largely repeats enum values and price unit information already present in the schema, providing only minimal extra parameter insight.

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 opens with 'Search 1,100+ curated specialty coffees in the Percolate database', naming the verb, resource, and scope precisely. It also lists concrete filter dimensions and return contents, making it easy to distinguish from siblings like get_coffee or trending_coffees.

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 clearly frames when to use this tool: searching the curated Percolate catalog with filters on category, roast, brew method, and price. It provides clear context but does not explicitly mention alternatives or exclusion criteria, so agents are left to infer that more targeted tools like get_recommendations or find_similar are for other cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description needn't repeat the safety profile. It adds meaningful detail: text goes into catalog popularity fallback when live activity data is unavailable, and the response is labeled with the method used. These are non-obvious traits not present in the schema or 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 one sentence with no filler or redundancy. It front-contains the core logic, quickly includes the fallback behavior, and uses the last clause to set expectations for the response. Every part earns its place.

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 a single optional parameter and no output schema, this description covers the central data, the fallback path, and the response label. It does not explicitly state the output shape (e.g., a list), but the start and behavior make that easy for an agent to infer. Minor room for an explicit return-format note, hence not a 5.

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 only parameter, limit, is fully documented in the schema with min, max, and default. The description does not augment the parameter's meaning, and this is acceptable because schema coverage is 100%. A baseline 3 is appropriate since the schema carries the burden.

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

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

The description clearly defines the tool as returning coffees that users have been adding to collections most over the last 30 days, including the fallback behavior. This identifies a specific resource and behavior without tautology. It does not explicitly contrast the tool with sibling options like get_recommendations or what_to_brew, but the intent is unambiguous.

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

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

The description implies the primary use case: retrieving trending coffees. It provides no explicit guidance on when to choose this over sibling tools, such as search_coffees or get_recommendations, and does not state when not to use it. The usage is clear from phrasing but left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful conditional behavior ('evening picks lean decaf') and a scoring source, but it does not describe the return shape or any environment dependencies.

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 front-loaded sentence that communicates purpose and key influencing factors with no fluff. Even the contextual detail about evening decaf earns its place by signaling how time_of_day influences the result.

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 tool is fairly simple and the annotations cover safety, but there is no output schema and the description does not state what a recommendation actually returns or what happens when parameters are omitted. It is adequate for basic invocation but leaves those details to be discovered.

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 67%, and the description generally repeats relationship of mood, brew_method, and time_of_day without adding much detail. The main extra insight is the evening→decaf mapping; brew_method still lacks concrete possible values, so the description does not fully compensate for the medium 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 identifies the tool as providing a coffee suggestion based on time of day, mood, and brew method — a specific verb+resource. However, it does not explicitly differentiate itself from siblings like `get_recommendations` or `dial_in_suggestion`, so it stays short of a 5.

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 phrase 'for right now' and the listed inputs give a fairly clear context for when to use this tool: for an immediate, context-aware suggestion. There is no explicit mention of alternatives or when-not-to-use, so the guidance is present but not fully explicit.

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