starbucks_product

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

With no annotations and no output schema, the description carries the full burden and handles it exceptionally: it discloses that Starbucks exposes no dollar pricing so no price is returned, that star_cost is the Rewards star cost, that invalid product/form combinations return not found, that store_number optionally scopes availability, that market defaults to us, and that default_recipe is a required prerequisite for the downstream nutrition endpoint. These are exactly the behavioral surprises an agent could not infer on its own.

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 every sentence earns its place: purpose first, then return contents, then per-parameter semantics, then caveats, then error behavior. The nutrition subfact enumeration is verbose, but with no output schema it serves as the de facto return contract, so the length is justified rather than padded. Well front-loaded and logically ordered.

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 no annotations, no output schema, 4 parameters, and a moderately complex return shape (nested per-size nutrition panels, forms, market catalogs), the description is nearly complete: it defines the return structure in detail, documents defaults, discloses missing-price behavior, specifies error conditions, and chains to the nutrition endpoint. The only real gap is underspecification of what store_number scoping means in the response when a product is unavailable at that store.

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, and the description adds genuine value beyond the schema: product_number gains sourcing semantics ('from a /starbucks/menu result or a product page URL'), form gains the 'not sold in that form returns not found' condition, and the price/star_cost caveat clarifies market semantics. The additions for product_number and form go well past the schema's bare 'numeric product id' and enum list, justifying a step above 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 opens with a specific verb+resource scope: 'Get one Starbucks product with nutrition.' It enumerates the exact return contents and frames itself as the single-product deep-dive ('one Starbucks product') while sourcing product_number from a /starbucks/menu result, which implicitly differentiates it from the menu-listing sibling starbucks_menu and the separate nutrition endpoint. No ambiguity about what this tool does.

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 gives clear context for when to use the tool: it is the single-product detail lookup, its product_number comes from a /starbucks/menu result, and its default_recipe is the required starting point for the nutrition endpoint — establishing the tool's position in a workflow. It stops short of explicitly naming alternatives or stating when-not-to-use ('use starbucks_menu for a list'), so it lacks formal exclusions, but the implied usage is unmistakable.

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