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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description corroborates and enriches that: same quantities overwrite rather than add, the server derives sold as made minus waste minus leftover, and the server rejects amounts exceeding made-minus-sold. That is real server-side behavior beyond the flags, though permission requirements and the response shape are unmentioned.

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?

Five short sentences, front-loaded with the WRITE marker and the resource, then escalating to derivation rule, validation rule, overwrite semantics, and endpoint. No filler and no repetition of schema content.

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 nested, destructive write tool with no output schema, the description covers mutation semantics, idempotency behavior, and the key server-side validation error an agent will hit. What's missing is any hint of the success response or whether partial item failures are possible when up to 500 items are sent.

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 roughly 50% (section and station are undocumented, the amount/uom fields carry their own descriptions), so the description only needs to add the 'and/or' semantics — that waste_amount, leftover_amount, and their uoms are independently optional per item. It does that, but gives no guidance on the section/station fields or on how amounts interact with the chosen uom.

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?

Opens with an explicit 'WRITE:' verb marker and names the resource precisely: waste and leftover quantities per menu item on a cafe/hot bar event. It also pins the endpoint (PUT /events/{id}/waste_leftover), so an agent can trivially distinguish it from sibling writers like parsley_record_event_sales or parsley_update_event_covers.

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 cafe/hot-bar-event scope is stated, which implicitly rules out other event types, and 'waste and/or leftover' tells the agent it may supply either or both. But no sibling is named as an alternative and there is no explicit when-not guidance (e.g. use record_event_sales for sold counts).

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