get_meal_history

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the 'immutable' trait of the history, which is useful context. However, it doesn't disclose what the output structure looks like or whether include_snapshots affects payload size/performance, though the output schema exists to partially cover return details.

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, tight sentence with zero waste. It front-loads the verb and resource clearly. Appropriate for a simple read-only tool.

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?

With an output schema present, return-value documentation is covered by structured data. However, the include_snapshots parameter is unexplained in both schema and description (0% coverage), creating a real gap. The tool is relatively simple, so completeness is adequate but leaves the boolean parameter ambiguous—an agent can't tell what a 'snapshot' means in this context from the description alone.

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 carries the burden of explaining parameters. The description mentions 'revision history' but doesn't explain meal_id semantics or the include_snapshots boolean's meaning. The baseline 3 applies since schema is minimal; the description adds only marginal value by implying meal_id identifies which meal, but include_snapshots is completely unexplained.

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 'Get immutable revision history for one meal' with a specific verb (get), specific resource (meal history), and scope (one meal). It's clear, though it doesn't explicitly distinguish from the sibling get_meal or the restore_meal tool, so sibling differentiation is implicit rather than explicit.

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 usage by noting it retrieves revision history for a single meal, which contrasts with list_meals. However, there's no explicit when-to-use vs alternatives guidance, no mention of how it relates to restore_meal (which would consume this history), and no exclusion criteria to help an agent choose between get_meal and get_meal_history.

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