starbucks_stores

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

With no annotations provided, the description carries the full burden, and it delivers. It discloses that the upstream returns at most 50 stores with no pagination, that result_capped indicates truncation, that unresolved places return a well-formed empty result with place_not_found rather than an error, and that hours/amenities/phone may be absent outside the US and UK. These are exactly the behavioral quirks an agent needs to know.

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 dense but well-organized, front-loading the core purpose and return fields before diving into parameter requirements and behavioral caveats. Every sentence adds information; there is no filler. It loses one point because it is long and packs many caveats into a single paragraph, which could be slightly restructured for scannability, but it remains efficient.

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 4-parameter tool with no output schema and no annotations, the description is remarkably complete. It covers input requirements, parameter semantics, return fields, error behavior, pagination limits, and market-specific data gaps. An agent has everything needed to invoke it correctly and interpret results, including edge cases like place_not_found and result_capped.

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 baseline is 3. The description adds meaningful semantics beyond the schema: it explains that place is free-text and geocoded by Starbucks itself, that market defaults to us and affects operational data, and that lat/lng must be used together. It doesn't add syntax details for lat/lng, but the schema already covers those. The added context about market's non-cosmetic effect and place's worldwide geocoding justifies a 4.

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 opens with a specific verb and resource: 'Find nearby Starbucks stores worldwide.' It then enumerates the exact fields returned (store number, name, phone, full address, coordinates, weekly opening hours, amenities, pick-up options), which clearly distinguishes it from sibling tools like starbucks_nearest_store or datasets_starbucks_stores_nearby. The scope and output are 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?

The description explicitly states the input requirement: 'Either place, or both lat and lng, is required.' It explains when to use place vs coordinates, clarifies that market selects the country site and is not cosmetic, and explicitly warns that there is no filter parameter because the upstream silently ignores it. It also tells the agent to filter on returned amenities instead, which is direct usage guidance.

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