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

Annotations declare readOnlyHint=true and openWorldHint=true, so safety is already covered. The description adds genuine behavioral context beyond that: prices are in roubles, results include variants and customization detail, and critically the catalog is national with no city variation. That last point is a real behavioral trait an agent would otherwise have to guess.

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?

Three sentences, front-loaded with the core capability and payload, then the market-separation and no-city-variation notes. Efficient overall, though the 'six international markets' framing is slightly wordier than needed to establish the boundary.

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?

An output schema exists, so return-value detail is not required from the description. Combined with readOnly/openWorld annotations and the 100%-covered parameter schema, the description covers the remaining gaps (currency, national scope, no city filtering). Minor room remains on sibling routing, but nothing essential 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?

Schema description coverage is 100% and the single category parameter is fully documented in the schema (optional, case-insensitive match on name or slug, with an example). The description adds nothing about the parameter, so the baseline 3 for high-coverage schemas 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?

States a specific verb+resource: the Papa John's Russia priced menu in roubles, enumerating the returned content (variants, pizza diameter, dough type, stuffed crust). It also differentiates from the sibling market menus by noting Russia runs its own platform separate from the international and Latin American catalogs. A dedicated sibling name (papajohns_menu, papajohns_intl_menu) isn't cited directly, but the market boundary is clear.

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 implies when to use it (retrieving the Russian national menu) and clarifies that the catalog does not vary by city, so no location input is needed. However, it never states when to prefer this over papajohns_menu or papajohns_intl_menu, so the routing guidance is only implied.

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