Compare with a previous snapshot

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

Annotations already declare readOnlyHint=false and idempotentHint=false, and 'Take a new snapshot' is consistent with that write-ish, non-idempotent profile. However, the description never explains why it is non-idempotent or stateful — notably that each call presumably replaces the stored 'previous' snapshot that future comparisons use, which materially affects repeated invocation. That is the single most useful behavioral fact an agent needs here and it is absent.

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?

Two tight sentences: the first establishes the operation and both comparison targets, the second gives the follow-up action. Nothing is repeated or wasted, and the core action is front-loaded.

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 no output schema, the description should explain the shape of the result, and 'reported cells' only hints at a region-based diff without saying how cells are expressed or how they map to `region` values. The baseline and camera semantics are covered, but the return-value contract and the effect on the stored snapshot remain unclear.

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 carry parameter meaning. It does add value for `camera` (which camera's snapshot) and `baseline` (a named baseline saved in that scene, versus the default previous-snapshot behavior), but `quality` is never mentioned, so the high/low tradeoff and its default are undisclosed.

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 gives a specific verb (take a snapshot and report changes) and resource (this camera's previous snapshot), and it scopes the operation to a single camera within its current scene, which implicitly separates it from the scene-wide sibling scene_compare. An agent can tell what it produces and at what granularity without opening the schema.

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?

It gives a clear follow-up path: use the reported cells as `region` in camera_snapshot to zoom in, which tells the agent when to chain this tool with another. It also clarifies that the baseline is either the implicit previous snapshot or a named baseline saved in that scene. It stops short of naming when to prefer scene_compare or camera_snapshot instead.

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