papajohns_india_deal

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

No annotations are provided, so the description carries the full disclosure burden. It does add meaningful behavioral information: it discloses the price_type values and the important rule that only fixedPrice deals report a non-zero price, which prevents an agent from misreading the price field. It also sets the India-only boundary. It does not explicitly state read-only side effects, error behavior, or pagination, but for a 'get single object' tool the description covers the key expected 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 only a few sentences, and each sentence serves a purpose: it states the operation, describes the return payload, contrasts with the menu endpoint, explains price_type behavior, and gives the India-only scope. There is a minor redundancy in restating 'India' in the resource and again as a boundary sentence, but the description is otherwise lean and front-loaded.

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 tool has only one required parameter, and the schema covers it. Since there is no output schema, the description itself explains what the caller should expect: slots, menu items, prices, and the price_type rule. It is also unambiguous about the market scope and the relationship to the menu endpoint, so an agent has enough to decide whether to call this tool and what the result will look like.

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 schema already documents deal_id fully as coming from GET /papajohns/india/menu (items with kind=deal). The description refers to a deal's composition but does not add extra nuance beyond what the schema says about the identifier. With full schema coverage, the baseline of 3 is correct.

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 begins with a specific verb and resource: 'Get one Papa John's India deal's composition (INR)'. It then explains exactly what the composition contains, including slots, quantities, sizes, skippability, eligible item choices, and prices. It also distinguishes itself from the similarly-scoped GET /papajohns/india/menu row and from non-India variants by stating 'India market only'.

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?

It explicitly names the closest alternative, GET /papajohns/india/menu, and clarifies that this tool provides materially more detail than that menu row, giving a strong signal for when to use it. The 'India market only' guard also tells an agent when not to use it (e.g., for other Papa John's markets). It does not explicitly name sibling deal-level tools like papajohns_deals, but the scope and purpose are clear enough.

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