jimmy_johns_menu

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

No annotations are provided, so the description carries the full burden. It discloses a critical behavioral quirk: many sandwiches price through size selection, so base cost is commonly 0, and the real price is in the modifiers endpoint. This is exactly the kind of non-obvious behavior an agent needs to know to interpret the response correctly. It doesn't mention pagination or error cases, but for a menu-fetch tool the disclosed quirk is the most important 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 three sentences, each earning its place: what the tool returns, where the parameter comes from, and the critical pricing caveat. It is front-loaded with the core purpose and return shape, then adds the routing and caveat information. No wasted words.

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 single-parameter read-only menu tool with no output schema, the description covers the essential context: what the response contains, where the parameter comes from, and the key pricing caveat. It doesn't describe pagination or error behavior, but those are less critical for this tool. The description is complete enough for an agent to call it correctly and interpret the response.

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% and the parameter description already says 'Olo restaurant id from /jimmy-johns/nearby'. The description reinforces this by repeating the source of restaurant_id and adds context about what the returned menu contains. Since the schema already documents the parameter well, the description's additional context about the return structure and pricing quirk adds value beyond 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 states a specific verb ('Get'), a specific resource ('one Jimmy John's restaurant's full menu'), and the exact return shape ('category tree: every category and its products, with name, description, calorie range, base cost and image'). It also distinguishes itself from sibling tools like jimmy_johns_modifiers and jimmy_johns_nearby by explaining where restaurant_id comes from and where to get real prices. This is a clear, specific, and well-differentiated purpose.

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 explicitly tells the agent when to use this tool: to get a full menu for a specific restaurant, with restaurant_id sourced from GET /jimmy-johns/nearby. It also explicitly points to the alternative (GET /jimmy-johns/modifiers) for real per-size prices, which is a clear when-not-to-use signal. This is exactly the kind of routing guidance an agent needs.

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