sonic_store

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

With no annotations provided, the description must carry the behavioral burden itself. It discloses the expected input format and the return contents (hours per channel, delivery deep links), but it does not mention whether any authentication is needed, rate-limit implications, error behavior for invalid paths, or that it is read-only. The description remains silent on safety semantics beyond what 'look up' implies.

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 a single dense paragraph, front-loaded with the core purpose before enumerating return fields. It is longer than strictly necessary, but the detailed output enumeration serves as a substitute for a missing output schema, so it earns its place.

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?

The description fully compensates for the missing output schema by listing what the caller can expect: address, phone, coordinates, status, amenities, weekly hours per channel, and delivery deep links. The single input parameter is already well specified in the schema. For the scope of a single lookup tool, nothing an agent needs to understand the return value is missing.

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?

The input schema's description already fully documents the path parameter ('A store path from /sonic/sitemap (section=locations, kind=store)'). The tool description partly repeats that, adding no new explanation about format, how to be used, or examples beyond the schema. With 100% schema description coverage, the baseline 3 applies.

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 concrete action and resource: 'Look up one Sonic Drive-In restaurant by its locator path.' The qualifiers 'one' and 'by its locator path' distinguish it from listing or search sibling tools like sonic_locations or sonic_nearby, even without naming them. This clearly signals the tool's role.

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 a clear input constraint (path must be a store-type locations path from GET /sonic/sitemap) but does not explicitly say when to use this tool versus a sibling like sonic_locations or sonic_nearby. The usage guidance is implied from the 'one-restaurant-by-path' wording rather than stated as a comparison with alternatives.

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