update_meal

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

Annotations include destructiveHint=true and readOnlyHint=false, so the mutation nature is already indicated. The description adds the 'after checking its expected revision' detail, which implies optimistic concurrency control but doesn't explain what happens on revision mismatch (error? no-op?). No disclosure of side effects beyond the patch, or behavior when revision is stale.

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 a single concise sentence with no wasted words, which is positive. However, it's under-specified rather than appropriately concise. It front-loads the core purpose but leaves out essential details about parameters and behaviors.

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?

This is a mutation tool with destructiveHint=true, no schema description coverage, and a complex nested patch object (MealPatchRequest with ~12 fields). Despite having an output schema, the description still needs to explain the revision-checking behavior, what fields are patchable, and what happens on failure. For a tool of this complexity (3 required params, nested patch structure, concurrency semantics), the description is notably under-complete.

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 0%, so the description must compensate, but it doesn't mention any parameters. The description references 'expected revision' conceptually but doesn't explain what it means, how the patch object works, or how meal_id is used. With 3 undocumented parameters in the schema and zero coverage, the description fails to add meaning beyond what the raw schema field names convey.

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 the verb ('Update') and resource ('meal') but 'selected meal fields' is vague about what fields can be updated. It distinguishes itself from delete_meal and log_meal siblings by being an update operation, but doesn't clarify what 'selected fields' means or how it differs from related operations. The revision-checking mention adds useful specificity about the update mechanism.

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 gives no guidance on when to use this tool versus alternatives like log_meal, delete_meal, or get_meal. It doesn't mention when the expected_revision check would be relevant or what scenarios require updating vs logging. No exclusions or conditions for use are provided.

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