Create Restaurant Menu Item (Admin)

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

Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description goes beyond annotations by clarifying the new item starts active and available, and that only restaurant_id and name are required, with price_cents needed for ordering. It also warns it's a WRITE operation requiring user confirmation, adding behavioral context not captured in annotations. It doesn't contradict annotations.

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 concise, front-loading the essential purpose and critical requirements (admin, WRITE, required fields) in the first two sentences. It includes necessary operational details like role requirements and where to get restaurant_id without fluff. Slightly verbose with the role and confirmation details, but each sentence 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?

Given the tool's complexity (7 params, admin role, WRITE operation) and that an output schema exists (so return format is covered there), the description covers the key operational aspects: required fields, role permissions, initial state, and reference to update tool. It doesn't mention potential validation or side effects, but these are minor given the annotations and output schema. Adequate 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 input schema already provides descriptions for all 7 parameters (100% coverage), including examples like '550 = $5.50' for price_cents. The description adds minimal new semantic information, but does emphasize that only restaurant_id and name are required and that price_cents is important for ordering, which slightly enhances understanding of the parameter's role. Given the high schema coverage, a baseline of 3 is appropriate.

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 clearly states the tool creates a new menu item on a restaurant, a specific verb and resource, and mentions the requirement for restaurant_id and name. It also differentiates from the sibling update_restaurant_menu_item by noting that changes are made via that tool, and mentions the WRITE nature, which distinguishes it from read-only siblings.

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 says when to use it (to create a new menu item) and when to use the alternative (update_restaurant_menu_item for changes later). It also provides a prerequisite: obtaining restaurant_id from list_school_restaurants, and clarifies the need for admin roles, which prevents misuse.

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