burgerking_locations

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

With no annotations provided, the description carries the full behavior burden, and it delivers: it discloses that a coordinate with no nearby restaurant returns an empty list, that include_availability is capped at a fixed page rather than honoring max_results, and that delivery_only is a genuine delivery-zone match distinct from filtering on has_delivery. These are non-obvious behaviors beyond what the schema conveys.

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 information-dense but contains a redundant opening: 'Find Burger King restaurants near a location' and 'Returns Burger King restaurants near a latitude/longitude' say essentially the same thing. The long lists of fields, hours, and flags are valuable, but the structure could be tightened without losing meaning.

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 output schema and no annotations, the description is remarkably complete: it enumerates returned fields, hours categories, empty-list behavior, availability mode shape and cap, delivery-only semantics, and flag incompatibility. An agent has enough information to invoke the tool and interpret the result without resorting to outside documentation.

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?

Although schema coverage is 100%, the description adds meaningfully beyond it: it clarifies what include_availability returns and its page cap, defines delivery_only as a delivery-zone match rather than a flag filter, and states the exclusivity between the two flags. It also connects the store id output to parameters consumed by sibling tools.

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 Burger King restaurants near a latitude/longitude.' It also differentiates from sibling tools by explicitly noting that the returned numeric store id is the value /burgerking/menu and /burgerking/availability take, so an agent can connect this location tool to its related endpoints.

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 contextual instructions for the two optional modes: include_availability returns the same shape as /burgerking/availability but with a page cap, and delivery_only matches actual delivery zones rather than the has_delivery flag. It also states that the flags cannot be combined. It does not explicitly tell the agent when to prefer this tool over sibling endpoints, but it gives enough behavioral context to choose correctly.

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