Label facts (caffeine, sugar, ingredients) and community ratings for 1,000+ energy drinks.
Scored across 4 tools
Each tool has a distinct retrieval shape: single-drink lookup (get_drink), multi-drink comparison (compare_drinks), filter-based discovery (find_drinks), and free-text name/brand lookup (search_drinks). The only soft boundary is between find_drinks and search_drinks, since both return ranked drink lists, but the descriptions clearly separate attribute filtering from name text matching.
All four tools follow a clean verb_noun snake_case pattern: compare_drinks, find_drinks, get_drink, search_drinks. The verbs are distinct and predictable, and the shared '_drinks' object noun reinforces the pattern.
Four tools is a tight, well-scoped surface for a read-only ratings catalog, and each tool covers a genuinely different access pattern (lookup, compare, filter, search). Nothing is redundant or filler.
The core lifecycle for a catalog—search, filter, fetch details, compare—is fully covered, and error cases like missing slugs are handled. Minor gaps remain: no way to list all drinks or brands, and no tool to submit a rating despite get_drink linking out to rate the drink.
Side-by-side facts for 2-4 drinks by slug. Slugs not found in the catalog are reported, not silently dropped.
| Name | Required | Description | Default |
|---|---|---|---|
| slugs | Yes | 2-4 EDR drink slugs to compare |
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 a genuinely useful behavioral detail beyond them: unknown slugs are surfaced in the response rather than dropped, which tells the agent how to handle partial failures. It stops short of describing the shape of the returned comparison facts.
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 short sentences with no filler, and the core capability is front-loaded ahead of the error-handling note. Every clause carries information an agent needs.
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 a single required parameter, full schema coverage, and rich annotations, the definition covers invocation and partial-failure behavior well. Since there is no output schema, 'side-by-side facts' is a slightly thin account of what is actually returned, which is the only 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 coverage is 100% and the schema already encodes minItems 2 / maxItems 4 plus the slug array type, so the description's '2-4 drinks by slug' restates rather than extends it. No added detail on slug format or case sensitivity beyond what the schema provides.
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 resource (drinks), a specific output framing (side-by-side facts), and a bounded scope (2-4 drinks by slug), which cleanly separates it from the single-drink get_drink and the lookup siblings. It does not explicitly name those siblings, so the differentiation is inferable rather than stated.
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 2-4 slug comparison framing implies when to reach for it, but there is no explicit when-to-use/when-not language and no pointer to find_drinks or search_drinks for resolving slugs first. An agent can infer the use case but must do the routing work itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filters the catalog by caffeine, sugar, sweetener type, flavor family, carbonation and extras, with the same filters as energydrinkratings.com/find. Returns only available drinks, ranked by real community rating where rated, then by name, along with the total number of matches.
| Name | Required | Description | Default |
|---|---|---|---|
| fizz | No | ||
| limit | No | Maximum results to return (max 10) | |
| sugar | No | 'zero' = 0g, 'low' = <=5g | |
| extras | No | Required ingredient tags (AND'd together): preworkout (Pre-workout), focus (Focus) | |
| flavors | No | Flavor families (OR'd together): citrus (Citrus), berry (Berry), tropical (Tropical), stone_fruit (Stone Fruit), cherry (Cherry), grape (Grape), melon (Melon), apple_pear (Apple & Pear), fruit_punch (Fruit Punch), candy_dessert (Candy & Dessert), cola (Cola), root_beer_cream_soda (Root Beer & Cream Soda), coffee_tea (Coffee & Tea), original (Original) | |
| caffeine | No | Caffeine bands (OR'd together): le100 (≤100 mg), 100-199 (101–199 mg), 200-299 (200–299 mg), 300plus (300+ mg) | |
| sweetener | No | 'no-artificial' excludes artificial sweeteners; 'natural' requires a plant-based one (Plant-based sweeteners). Sweetener categories: sugar=Sugar, artificial=Artificial sweeteners, natural=Plant-based sweeteners |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds useful behavioral context: only available drinks are returned, ranking is by community rating where present and then by name, and the total match count is included.
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, front-loading what is filtered and then what is returned. Every clause contributes useful information without repetition.
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?
Given seven optional parameters, no output schema, and annotations that already cover safety, the description is largely complete for invocation. It explains filtering, availability, ranking, and total matches, though it does not describe the shape of individual drink records.
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 86%, so parameter details are already well documented. The description enumerates the filter categories (caffeine, sugar, sweetener, flavor family, carbonation, extras) but adds little semantic detail beyond what the schema already provides.
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 verb and resource: it filters the drink catalog by named criteria and returns available, ranked results. It is clear what the tool does, though it does not distinguish itself from the sibling search_drinks tool.
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 implied by the filtering criteria and the reference to the website's find page, but there is no explicit guidance on when to use this tool versus search_drinks, compare_drinks, or get_drink. No exclusions or alternative-routing instructions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full label facts for one drink identified by its EDR slug: caffeine, sugar, calories, serving size, sweetener and flavor info, availability, the community rating with its count and, when there are enough written reviews, a one-line summary of what raters say. Also returns links to the drink page, to rate the drink and to a free caffeine tracker.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The drink's EDR slug, e.g. 'bang-purple-haze' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotent, so the description appropriately focuses on return value details: it lists the specific facts returned, notes that the community summary only appears when there are enough reviews, and mentions included links. This adds useful behavioral context beyond the structured fields.
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 lists the returned information. Every element earns its place, with no redundancy or 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 simple single-parameter tool with no output schema, the description is complete: it fully describes what data is returned, including conditional elements (community summary) and links. An agent has everything needed to understand the tool's output.
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 description coverage is 100% and the single parameter 'slug' is fully documented in the schema. The description adds the term 'EDR slug' but no additional syntax or format details beyond what the schema provides, so it meets 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 states it returns 'full label facts for one drink identified by its EDR slug' and enumerates the data fields, making it easy to distinguish from multi-drink siblings like search_drinks. However, it does not explicitly name those siblings to reinforce the differentiation.
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 implied: use this tool when you have a specific drink slug and need detailed facts. There is no explicit guidance on when to use it versus alternatives like compare_drinks or search_drinks, nor any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Text search over energy drink names and brands. Returns up to 10 matching drinks with caffeine, sugar and a link to each drink page, or no results when EnergyDrinkRatings has no entry for the name.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum results to return (max 10) | |
| query | Yes | Drink name or brand to search for, e.g. 'Bang Purple Haze' or 'Celsius' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: the return payload (caffeine, sugar, link), the ~10-result cap, and the empty-result behavior when no entry exists. It does not state result ordering/ranking, which is the main remaining gap.
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, front-loaded with what the tool does and followed by the return/empty-result contract. Every clause carries information; nothing is redundant with the title or annotations.
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 the return fields and the no-result case, which it does. Remaining gaps are secondary for a simple two-parameter search: result ordering and whether brand matching is prefix or substring.
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 documented with examples and bounds, giving a baseline of 3. The description adds nothing about how `limit` interacts with the stated 'up to 10' cap, and that phrasing could even read as a fixed ceiling independent of the parameter.
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 ('Text search over energy drink names and brands'), which is unambiguous. It does not distinguish itself from the sibling find_drinks, which by name sounds like it does something very similar, so an agent cannot fully route between them from the description 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?
Usage is only implied: 'Text search' suggests a name/brand lookup, and the note about no results when EnergyDrinkRatings has no entry hints at coverage limits. There is no explicit when-to-use, when-not-to-use, or reference to find_drinks / get_drink / compare_drinks as alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
compare_drinksfind_drinksget_drinksearch_drinksBarcode lookup, nutrition search, and product comparison for 3M+ crowd-sourced food products.
Calories, sugar, carbs, ABV, gluten status, congeners and Hangover Index for 222 alcoholic drinks.
Nutrition facts for 24,000+ menu items of 100+ Japanese restaurant chains (kcal, PFC, salt, vitamins), each with the chain's source document. Search items, total a meal, and request missing chains.
Lab results, FDA recalls and additive rules for US packaged foods, with sources; never a grade.
Add one secure layer between your agents and this server.