Percolate

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

Given that annotations already declare readOnlyHint=true and destructiveHint=false, the description adds value by detailing what the comparison covers: roast, body/acidity/sweetness, shared vs distinct flavors, brew methods, and price difference. This goes beyond the annotations to set expectations about the content returned.

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 tightly written sentence. It front-loads the core purpose and packs the comparison dimensions into a compact list without 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?

With no output schema, the description compensates reasonably by enumerating the comparison categories. An agent knows what kind of response to expect. It does not spell out the response format, but for a read-only comparison tool this is 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 the schema already documents both parameters as coffee id or name. The description does not add extra parameter-level nuance, but it also does not need to because the schema carries the full burden. Baseline 3 is appropriate.

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 verb ('comparison') and resource ('coffees'), and lists concrete comparison dimensions (roast, body/acidity/sweetness, flavors, brew methods, price). This clearly distinguishes it from single-coffee tools like get_coffee and recommendation tools like get_recommendations.

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 the core use case clear—comparing two specific coffees side-by-side—but it does not explicitly state when not to use it or mention alternatives like find_similar or get_coffee. Usage guidance is implied rather than explicit.

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 safety profile is covered. The description adds useful behavioral detail: curated recipes are offered when available, otherwise a roast-based fallback is used. 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?

The description is a single well-structured sentence that front-loads the core purpose and includes only relevant details about fallback behavior and optional scoping. 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?

For a low-complexity tool with annotations covering safety and a schema covering all parameters, the description conveys the core behavior, fallback logic, and optional filtering. There is no output schema, but the description reasonably communicates what kind of guidance will be returned.

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 parameters are already well documented. The description adds minimal extra semantic value beyond mentioning the optional brew-method scoping, which is already captured in the schema.

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

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

The description clearly states the tool provides brew guidance for a specific coffee, with curated recipes or a roast-based starting point. It is distinguishable from search/recommendation tools in spirit, but it does not explicitly differentiate itself from siblings like what_to_brew or get_recommendations.

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 establishes a clear usage context: use when you have a specific coffee and want brew guidance, optionally filtered by brew method. It does not explicitly state when not to use it or name alternatives, so it stops short of a 5.

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

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds meaningful context by disclosing deterministic scoring over Percolate's structured tasting data and the ranking criteria, so the agent knows results are stable and data-driven rather than subjective.

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 concise sentences front-load the core purpose and ranking behavior without redundant details. Every clause 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 two-parameter, read-only tool, the description covers selection, input, and output ordering sufficiently. It does not describe the exact return payload shape or error behavior for an unknown coffee id, but the schema and sibling tool set fill most of the practical 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?

The schema fully documents coffee (id or name) and limit (default 5), so the baseline is 3. The description adds conceptual meaning by explaining that the coffee parameter is a reference profile and that similarity is computed from flavor/roast/body/acidity/sweetness proximity, which helps the agent choose an appropriate input.

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 states exactly what the tool returns—coffees similar to a given one—and adds the ranking basis (shared flavor notes and roast/body/acidity/sweetness proximity). It is distinct from siblings like search_coffees, compare_coffees, and trending_coffees because it anchors on a single reference coffee and returns ranked similar profiles.

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' makes clear the intended context: the agent should use this when the user has a specific coffee and wants similar options. It does not explicitly name sibling alternatives or when-not conditions, but the usage context is unambiguous enough for 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?

The description aligns with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and adds domain context about which attributes the record contains. However, it adds no beyond-annotation behavioral detail such as what happens when an id/name is not found, whether partial name matches are accepted, or any lookup constraints. With annotations already covering the safety profile, the extra context is modest.

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 with no filler: the first front-loads the core purpose and enumerates the returned fields in a compact list, and the second conveys the input form. Every phrase earns its place, and the structure makes the tool's scope immediately scannable.

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, single-parameter, read-only tool with full schema coverage and rich annotations, the description is nearly complete. It tells the agent what the call returns (the listed record attributes) and what input to provide. The only minor gap is not defining what 'Percolate' refers to or how name matching behaves, but these are small omissions for a low-complexity lookup.

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 already fully documents the single parameter with a description and an example. The description's sentence 'Accepts a Percolate id or a name' mostly repeats schema content, adding only the qualifier 'Percolate' to clarify the id type. Since schema_description_coverage is 100%, the baseline of 3 is appropriate; the description provides marginal extra meaning.

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

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

The description clearly states the tool's function: fetching a detailed record for exactly one coffee, listing its constituent fields (roast level, flavor notes, price, etc.). The phrase "one coffee" plus the listed fields cleanly distinguishes it from siblings like search_coffees or compare_coffees, so an agent can select it without ambiguity.

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 usage context is implied rather than explicit: when you have a specific Percolate id or a coffee name and want full details, use this tool. It does not name alternate tools (e.g., 'use search_coffees when you lack an exact id or name') or state when not to use it, so exclusion rules are 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=true, idempotentHint=true, and destructiveHnt=false, covering the safety profile. The description adds the behavioral notion that results are personalized based on the listed inputs, which is useful context beyond schema, but it does not disclose response format, ordering, or no-match behavior. 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?

The description is a single, front-loaded sentence that immediately conveys the core purpose and lists the relevant inputs without fluff. The inline examples are mild but not wasteful; it could be marginally tighter, but it is concise and readable.

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 fully documented parameters, the core invocation details are present. However, with no output schema, the description does not clarify what the returned 'picks' contain, how they are ordered, or what happens when no coffee matches. This is enough to call the tool but not fully self-contained 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 description coverage is 100% and every parameter already has type, constraints, and examples. The description merely paraphrases the inputs (flavor preferences, budget, roast, brew gear) without adding semantic detail such as how budget interacts with recommendations or how limit applies, so it does not raise the baseline 3.

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

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

The description states a specific action (get) and resource (coffee recommendations) and characterizes them as personalized picks driven by taste, budget, roast, and brewing equipment. This differentiates it from siblings like trending_coffees or search_coffees, though it does not explicitly name alternatives, 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?

No when-to-use guidance or exclusion criteria is provided. The description implies a personalization use case, but the agent is left to infer when get_recommendations is prefered over search_coffees, find_similar, or trendig_coffees. Explicit routing would be needed for a 4 or 5.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds minor context about the database size (1,100+) and that results include tasting profiles and where-to-buy links, but it does not disclose pagination or default ordering behavior. This is acceptable given the annotation coverage, but not deeply informative.

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

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

The description is two sentences, concise, and front-loaded with the core action and scope. Every sentence adds value: the first defines the search domain and size, the second lists filters and return content. 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?

With no output schema, the description should clarify what the agent can expect. It mentions returns (tasting profiles, brew methods, links), which is helpful. However, it does not mention the limit default or that results are capped at 10, nor how results are ordered. For a search tool with 7 optional filters, this leaves some ambiguity.

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 every parameter is already documented in the schema. The description repeats some of this information (e.g., category and price filters) without adding new semantics. It does not clarify default values beyond what the schema provides, so it does not exceed the baseline.

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 a search over a curated coffee database, using the specific verb 'Search' and naming the resource. It lists filter categories, making the scope obvious. It does not explicitly differentiate from sibling tools like get_coffee or find_similar, but the general search 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?

No guidance is given on when to use this tool versus alternatives. It does not mention that get_coffee should be used for fetching a specific coffee, or that find_similar is for similarity searches. The description only states what the tool does, leaving the agent to infer when it is appropriate.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: the fallback to catalog popularity and the fact that the response labels which method was used, which helps the agent interpret results correctly.

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 with no filler; the primary behavior and fallback are both stated efficiently. The phrasing 'are adding ... most over the last 30 days' is slightly awkward but does not hurt clarity.

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, optional-parameter, read-only list tool, the description covers the key expectation (trending live data), the fallback, and the response labeling. Without an output schema, a bit more detail about the response shape would help, but the tool is simple enough that this is 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?

There is only one parameter, limit, and the schema fully documents its type, range, and default. The description adds no parameter-specific detail, but no additional meaning is needed given 100% 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 identifies a specific resource (coffees users are adding to collections) and a time window (last 30 days), making the purpose clear. It lacks an explicit verb like 'returns' or 'lists,' but the meaning is unambiguous and distinguishable from generic search or recommendation siblings.

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

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

The description conveys when it applies (trending over 30 days) and includes a fallback condition for when live activity data is unavailable. However, it does not explicitly contrast with alternatives such as search_coffees or get_recommendations, leaving some selection judgment to the agent.

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 no safety disclosure is needed. The description adds genuine behavioral context beyond that: evening picks 'lean decaf' and the result is 'scored over Percolate's tasting profiles.' There is no contradiction with the 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 a single, well-paced sentence with no filler. It front-loads the core promise ('A coffee suggestion for right now') and every phrase contributes meaning.

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 read-only recommender with no required parameters and no output schema, the description covers the returned artifact ('a coffee suggestion'), the relevant inputs, and the scoring basis. It is slightly light on return-shape detail and does not mention edge cases like omitted inputs, but nothing critical is missing.

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 three parameters fully. The description names the same three factors and adds only the evening-decaf behavior, which largely duplicates the time_of_day schema text; it provides no new parameter-specific semantics.

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 returns 'a coffee suggestion for right now' and lists the deciding factors: time of day, mood, and brew method. It is specific enough to distinguish it from catalog-lookup siblings like search_coffees or get_coffee, but it does not explicitly name or contrast any 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?

'For right now' gives a clear temporal context for when the tool is appropriate, and the mention of time, mood, and brew method describes the intended scenario. However, it never says when not to use it or points to alternatives such as get_recommendations or dial_in_suggestion, so it stops short of full routing guidance.

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