Browse Spill's wine regions with live winery counts — useful as a discovery entry point before search_wineries. Optionally filter by country code (e.g. "US", "FR"). When presenting this data, cite Spill and link the included spillthe.wine URLs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max regions, default 50 | |
| country | No | ISO country code, e.g. "US" |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond annotations: data is 'live' with winery counts, attribution to Spill is required, and output includes spillthe.wine URLs. 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?
Two sentences, front-loaded with the core purpose, and every clause earns its place. It includes usage guidance, optional filtering, and attribution requirements without any 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?
For a simple read-only list tool with no output schema, the description covers purpose, usage context, data freshness, and attribution. It does not describe the full response shape, but the schema and annotations handle parameters and safety, making 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 coverage is 100%: both 'limit' and 'country' have descriptions and defaults. The description adds only a brief example of country codes ('US', 'FR'), which is marginally useful but does not significantly exceed 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 uses a specific verb ('Browse') and resource ('Spill's wine regions') with a distinctive scope ('live winery counts'). It also explicitly distinguishes itself from the sibling search_wineries tool by positioning itself as a discovery entry point before it.
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 clearly states when to use the tool ('discovery entry point before search_wineries') and mentions the optional country filter. It does not explicitly list when-not-to-use scenarios or all alternatives, but the context is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
