Coffees Percolate users are adding to their collections most over the last 30 days (falls back to catalog popularity when live activity data is unavailable). The method used is labeled in the response.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 10) |
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.
Add one secure layer between your agents and this server.
Each tool has a clearly distinct job: searching, fetching details, comparing, finding similar coffees, personalized recommendations, trending picks, immediate what-to-brew suggestions, and brew dial-in guidance. No two tools appear to perform the same core action.
Most tools follow a readable snake_case verb_noun pattern (compare_coffees, get_coffee, search_coffees), and the exceptions (trending_coffees, what_to_brew, find_similar) are still intuitive and consistent in style. The deviations are minor rather than chaotic.
8 tools is a well-scoped size for a specialty-coffee discovery and recommendation server. Each tool covers a different user-facing step without bloating the surface or leaving the domain feelig thin.
The tool surface covers the main coffee journey: search, inspect, compare, find similar, get personalized/or-trending/now suggestions, and brewing guidance. Minor gaps exist around enumerating available option values or filtering directly by flavor tags, but agents can work around these using search and the structured data returned.