sonic_item

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

With no annotations, the description carries the full burden. It discloses the return fields and the link to the nutrition guide, but it doesn't explicitly state it's a read-only operation or mention any side effects. Since it's a lookup, read-only is implied, but not stated. It also doesn't mention any required permissions or error 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 two sentences with no unnecessary words. It front-loads the purpose ('Look up one Sonic Drive-In menu item's detail.') and then details the return and path requirements. It is well-structured and 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 simple tool with one parameter, the description covers the purpose, return content, and path requirements. It doesn't mention error handling or explicit read-only status, but for a basic lookup this is acceptable. The description is sufficiently complete for an agent to call it correctly.

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 schema already describes the path as 'A menu page path from /sonic/sitemap (section=menu)', but the description adds more detail: it specifies the kinds (category, subcategory, item) and alternative sources (menu-adjacent pages). This adds meaning beyond the schema, providing practical guidance on how to construct a valid path.

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 states a specific verb and resource: 'Look up one Sonic Drive-In menu item's detail.' It clearly distinguishes this from list/menu tools by emphasizing it returns a single page's detail with specific fields (name, description, image, nutrition link). This makes it unambiguous what the 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 provides explicit guidance on when to use it: the path must be a menu section path from GET /sonic/sitemap or a menu-adjacent page. This gives clear context, though it doesn't explicitly name alternative tools for cases where the path is unknown, but it's implied that this is the tool for a known path.

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