dunkin_nearby

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 rich behavioral detail: returns are ordered nearest first; each result includes distance, hours, closure status, amenities, payment methods, delivery options, and URLs; `total_in_radius` may exceed page size; `offset` walks pages; and a coordinate with no nearby stores returns an empty list rather than an error. This goes far beyond a bare 'find stores' statement and removes most guessing about response 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 long but appropriately dense, given the absence of an output schema. It front-loads the core action, then the comprehensive field list, then the sibling differentiation, chaining, paging, and edge-case behavior. There is mild redundancy ('nearest first' appears twice), but every sentence contributes operational value; no filler or generic marketing phrases.

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?

Considering the tool has 5 parameters, no annotations, and no output schema, the description is exceptionally complete: it covers what the tool returns, how results are ordered, how to chain to the store detail endpoint, how to handle multi-page results, and the no-result behavior. The only minor omission is whether there is any upper bound on radius beyond the schema range, but the schema provides that. An agent has enough to make correct calls confidently.

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 the baseline is 3. The description adds meaningful context by explaining that `total_in_radius` drives paging via `offset`, that results are ordered nearest first (connecting to the radius concept), and that radius is in miles. It does not redefine every parameter, but the paging and ordering context goes beyond the schema. The one small gap is that latitude/longitude format is left entirely to the schema.

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 Dunkin stores near a coordinate, nearest first.' It then explicitly contrasts itself with the sibling directory tool ('This is the proximity search the directory browse cannot do'), making it immediately distinguishable from dunkin_directory and dunkin_store. The behavior and output scope 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 states exactly when this tool is appropriate versus the directory alternative: 'GET /dunkin/directory walks a state to city to store tree, which requires knowing the administrative path in advance.' It also explains how to chain results to GET /dunkin/store via the `path` field, and how to page through many results with `offset`. This gives the agent clear conditions for selection and usage.

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