Percolate

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world behavior, so the safety profile is covered. The description adds genuinely useful disclosure beyond that: it enumerates what the comparison returns (roast, sensory scores, shared vs distinct flavors, brew methods, price delta), which matters because there is no output schema. It does not cover failure behavior for an unknown coffee id/name.

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?

A single compact fragment, front-loaded with the operation and then the compared dimensions. Every listed item earns its place by telling the agent what the comparison surfaces; there is no 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?

With no output schema, the description correctly takes on the burden of describing return content, which it does well. What is missing is routing context against the sibling tools and any statement about invalid or unresolvable coffee identifiers.

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

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

Schema description coverage is 100% and both required parameters are documented in the schema as 'id or name' with maxLength. The description adds nothing about how coffee_a and coffee_b are supplied or whether order matters, so the baseline 3 applies.

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 operation (side-by-side comparison) and enumerates the compared attributes: roast, body/acidity/sweetness, flavors, brew methods, price. It is clearly distinguishable from get_coffee or find_similar by scope. It stops short of naming those siblings explicitly, so it is clear but not sibling-differentiating.

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?

There is no when-to-use guidance and no mention of alternatives such as find_similar or get_coffee, which an agent could plausibly reach for instead. The two-input comparison is only inferable from the field list, so usage must be inferred rather than read.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses graceful degradation (curated catalog recipe 'when available, or a roast-based starting point') and that brew-method scoping is optional. It does not say what happens with an unrecognized coffee or what the returned recipe shape looks like.

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?

One compact sentence, front-loaded with the core purpose followed by a colon that enumerates the returned fields, then the fallback and the optional scoping. Every clause carries information; nothing is padding.

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

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

For a two-parameter, read-only tool with no output schema, the description tells the agent what it gets back (ratio, temperature, grind) and what happens when no curated recipe exists. Only the exact response shape/format is left unspecified, a minor gap.

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 both parameters are already documented ('Coffee id or name', 'Your brewer, e.g. V60'). The description adds only the mild nuance that brew_method is optional and scopes the guidance, which does not go beyond what the schema conveys; baseline 3 applies.

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+resource: it returns brew guidance (recipe: ratio, temperature, grind) for one coffee. An agent can distinguish it from list-style siblings like search_coffees or trending_coffees, though it never explicitly contrasts itself with what_to_brew, the closest sibling.

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?

Usage is only implied: 'for a specific coffee' and 'optionally scoped to your brew method' suggest when it applies, and the fallback clause hints at reliability, but there is no explicit when-to-use vs. what_to_brew / get_recommendations 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 cover readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is free. The description still adds real value by disclosing that scoring is deterministic and derived from Percolate's structured tasting data, which tells the agent results are reproducible and explainable.

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 tightly written sentences with zero filler; the core operation is front-loaded and the scoring detail follows as support.

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?

With no output schema, the description does enough by explaining the ranking criteria, so an agent understands the shape of the result. It leaves the exact return structure and limit behavior unstated, which is a minor gap for a low-complexity read 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% with both parameters documented (coffee id/name, limit default 5), so the baseline is 3. The description adds some meaning by defining what 'similar' means (shared flavor notes plus roast/body/acidity/sweetness proximity), but it adds nothing about the limit or input format 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 names a specific resource (coffees) and a specific operation (find ones with a similar profile to a given one), and it even states the ranking basis. It does not explicitly distinguish itself from siblings like compare_coffees or get_recommendations, so it stops 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?

It implies the trigger (you have one coffee and want analogous ones) but never states when to use this versus compare_coffees, search_coffees, or get_recommendations. No exclusions or prerequisites are given.

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 safety is covered structurally. The description adds genuinely non-structural context: the exact shape of the returned record and the explicit exclusion 'no purchase links,' which sets expectations about what the response will and won't contain.

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?

A single dense sentence that front-loads the purpose and then enumerates returned fields. The field list is long but each item earns its place given there is no output schema; no filler or redundant phrasing.

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?

With no output schema, the description correctly carries the burden of describing the return payload in detail, including prices and retailer names, and notes the absence of purchase links. It omits only edge-case behavior such as what happens when the id or name is not found.

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% for the single parameter, so the schema already documents the id/name input and gives a name example. The description adds only the minor clarification that the id is a 'Percolate' id, which is marginal value over 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?

Opens with a specific verb+resource+scope: 'Detailed record for one coffee.' The singular, detail-oriented framing cleanly separates it from list-oriented siblings like search_coffees and compare_coffees without needing to name them.

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

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

No statement of when to use this tool versus search_coffees, compare_coffees, or find_similar. 'Accepts a Percolate id or a name' is invocation detail, not selection guidance, so an agent must infer routing from the tool name 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds a little behavioral color by indicating that output is driven by taste, budget, roast, and equipment, but it discloses nothing about result count, ranking, or fallback behavior when no match exists.

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?

A single tightly packed sentence with no filler; the required taste dimension is front-loaded ahead of the optional filters. Every clause maps to a real 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?

For a read-only, non-destructive recommendation tool with 100% schema coverage and no output schema, the description is minimally adequate. It covers inputs but omits return-shape expectations and sibling disambiguation, which is the main remaining gap.

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 all five parameters with examples, units, and defaults. The description merely restates the same dimensions in prose ('budget in USD', 'brew gear you own') without adding format or constraint detail beyond the schema, so the baseline of 3 applies.

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 conveys a specific operation on a specific resource: producing personalized coffee picks from flavor preferences, budget, roast, and brew gear. However, it never distinguishes this from siblings such as find_similar, what_to_brew, or trending_coffees, so an agent cannot route between them from text alone.

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?

There is no when-to-use or when-not-to-use guidance and no mention of alternatives. The description only enumerates the input dimensions, leaving the agent to infer that this is the personalization tool versus the browsing or comparison siblings.

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

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

Annotations already declare this a safe, idempotent, closed-world read, so the safety burden is met. The description adds genuinely valuable context that annotations cannot: the 1,100+ corpus size and the shape of what comes back (tasting profiles, brew methods, retailer names with prices, no purchase links).

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 tight sentences: what it searches, how to filter, what comes back. The scope and filter list are front-loaded and nothing is padded.

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?

With no output schema, the description usefully compensates by describing the return payload, and the filter dimensions are covered. It stops short of explaining result ordering or how the 10-item limit interacts with broad queries, which is a minor gap for a 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?

Schema coverage is 100%, so every parameter is already documented with types, enums, and bounds. The description restates category options and USD pricing without adding syntax, ranking, or defaulting behavior beyond the schema, so the baseline 3 applies.

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 ('Search 1,100+ curated specialty coffees in the Percolate database') and enumerates the filterable facets. It is clearly distinct from get_coffee or compare_coffees by virtue of being a catalog search, though it never explicitly names a sibling to route against.

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?

Usage is only implied: the description tells you what can be filtered but not when to choose this over find_similar, get_recommendations, or trending_coffees. No prerequisites or exclusions are stated.

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 readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered. The description still adds real behavioral value beyond them: the fallback to catalog popularity when live activity data is unavailable, and the fact that the response labels which method was used, which matters because no output schema exists.

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

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

Two sentences, both front-loaded: the primary ranking definition first, the fallback caveat second. No filler, no restatement of the tool name, and the parenthetical qualifies rather than pads.

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 zero-required-parameter read tool with no output schema, the definition covers the ranking signal, its time window, its degraded mode, and that the method is labeled in the response. What is missing is ordering/response-shape detail, but the labeling note plus rich annotations make this adequate.

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

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

Schema description coverage is 100% and the single optional parameter is fully documented there ('Max results (default 10, max 10)'). The description adds nothing about the limit parameter, so the baseline of 3 applies for a schema that carries the load.

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-plus-resource (coffees users are adding most often) with a defined 30-day window and an explicit fallback to catalog popularity. That is far more precise than a generic 'get trending' label, but it never names or contrasts a sibling such as get_recommendations or what_to_brew, leaving the agent to infer the boundary 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?

Usage is only implied: the phrase 'coffees users are adding most over the last 30 days' suggests a discovery/discovery-feed use case. There is no when-to-use guidance, no when-not-to-use, and no pointer to an alternative sibling when live activity data matters or when the user wants a personalized pick instead.

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, non-destructive and closed-world (openWorldHint=false). The description usefully adds that picks are scored over Percolate's tasting profiles and that evening selections lean decaf, which is genuine behavioral context. It does not say what the response actually contains (a single pick, a ranked list, scores), leaving the return shape opaque with no output schema to fall back on.

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?

A single dense sentence, front-loaded with the outcome ('a coffee suggestion for right now') and then the drivers. No filler, nothing repeated, and the most important clause comes first.

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

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

For a zero-required-parameter read-only tool with full schema coverage and no output schema, the definition covers inputs adequately but leaves the return value unexplained — the agent cannot tell whether it gets one coffee, a ranked shortlist, or scores. Annotations carry the safety profile, but the output gap keeps this only minimally 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 description coverage is 100%, so mood, brew_method and time_of_day are already well documented, including the enum semantics for time_of_day. The description restates the same mapping (time of day, mood, brew method, evening leaning decaf) without adding format, weighting, or default-behavior detail beyond the schema, so the baseline 3 applies.

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 names a specific action and resource: it returns a coffee suggestion to brew now, scored over Percolate's tasting profiles, driven by three named inputs. That is far more than a restatement of the name. It stops short of distinguishing itself from close siblings like get_recommendations or dial_in_suggestion, which an agent could easily confuse it with.

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?

'For right now' plus the time/mood/method inputs implies the decision moment this tool serves, so usage is reasonably inferable. However, it never states when to prefer this over get_recommendations or dial_in_suggestion, and gives no exclusions, so the agent must guess at routing.

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