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 establish read-only and idempotent behavior; the description adds valuable context by noting deterministic scoring over Percolate's structured tasting data. This tells the agent that results are reproducible and grounded in structured attributes rather than subjective or opaque ranking. It does not cover edge cases like no matches or invalid coffee references, but for a simple read-only tool this is acceptable.

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 tight sentences with no wasted words. The first sentence front-loads the purpose and ranking criteria, while the second adds a meaningful note about determinism and the data source. Every element 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 low-complexity read-only tool, the description, schema, and annotations together cover input format, ranking behavior, result count limits, and safety profile. The only minor gap is information about behavior when no similar coffees are found, but that is not critical for a listing tool. Overall this is complete enough for an agent to invoke 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?

Both parameters are fully documented in the schema: 'coffee' accepts an id or name, and 'limit' specifies max results with a default of 5. The description does not add further parameter-level meaning beyond restating the ranking logic, so it appropriately relies on the schema's 100% coverage. No gaps require compensation.

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: return coffees similar to a given one, ranked by shared flavor notes and roast/body/acidity/sweetness proximity. This specifies a concrete verb, resource, and output ordering, which is more specific than a vague 'find similar'. However, it does not explicitly contrast with sibling tools like get_recommendations or search_coffees, so some differentiation is left to inference.

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 intended use case is implied: provide a reference coffee and obtain ranked similar coffees based on tasting data. But there is no explicit guidance on when to choose this tool over alternatives, such as search_coffees for text queries or get_recommendations for curated suggestions. The description implies usage but does not state exclusions or alternatives.

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 this as read-only/idempotent, and the description adds useful behavioral context: database scope, curation, available filters, and what results contain (tasting profiles, brew methods, buy links). It does not mention result ordering or pagination behavior, but those are minor for a search tool.

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

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

Two compact sentences: the first establishes scope, the second covers filters and returns. No filler, redundant qualifiers, or boilerplate; 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?

For a search tool with seven optional parameters, all documented in the schema, the description supplies the missing context: result contents, currency for price filters, and the catalogue's curated nature. No output schema is provided, but the returns are described well enough for correct invocation.

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

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

Schema coverage is 100%, so the schema already documents every parameter and even the enum values. The description repeats the main filters but adds little semantic detail beyond the schema; this is the baseline 3 rather than a higher score.

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 ('Search'), a bounded resource ('1,100+ curated specialty coffees in the Percolate database'), and the main filter dimensions. This clearly distinguishes a catalogue lookup from siblings like get_coffee, compare_coffees, 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?

It gives clear context: use this when you need to find coffees by text, category, roast, brew method, or price. It does not explicitly state when to prefer a sibling such as get_coffee for a known coffee ID or compare_coffees for side-by-side comparison, 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 declare the tool read-only, idempotent, and non-destructive. The description adds useful behavior beyond annotations: the 30-day time window, the fallback to catalog popularity when live activity data is unavailable, and the response labeling of the method used. These details enrich the agent's understanding of runtime behavior.

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 with no wasted words. The first sentence states the core purpose and time window, and the second covers fallback and response labeling. Every sentence contributes meaningful 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?

For a simple read-only listing tool with one optional parameter, the description is sufficiently complete. It explains the data source, the time period, the fallback behavior, and that the response labels the method used. No output schema exists, but the description provides enough context for correct invocation.

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 schema description coverage at 100%, the single `limit` parameter is fully documented in the schema (min, max, default). The description adds no further parameter semantics, which is acceptable because the schema already carries the full explanatory 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 identifies the resource (trending coffees) and the specific criteria (most added to collections over the last 30 days). It distinguishes itself from sibling tools like search_coffees or get_recommendations by describing a popularity-based aggregation, including a fallback behavior.

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 use case is implied (discovering trending coffees), but the description does not explicitly state when to use this tool versus alternatives such as get_recommendations or what_to_brew, nor does it provide any exclusions or conditions for choosing an alternative.

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.