glass_diff

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

Annotations declare readOnlyHint=true, so the description doesn't need to restate that. The description adds valuable behavioral context: it explains the error behavior for unsaved baselines ('an unsaved name errors rather than reporting no change'), the effect of `ignore` on `changed_pct`, and the region-relative bbox. This goes beyond the annotations and helps the agent understand side effects and edge cases.

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 two sentences, front-loaded with the core purpose and return value, then the optional behavior. Every clause earns its place: the first sentence states the action and output, the second explains the optional parameter and its edge case. No fluff, no repetition of schema details.

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, 1 required) and the rich schema, the description covers the key behavioral aspects: error on unsaved baseline, ignore/region interaction, and conditional image return. It doesn't explain the return format in detail (no output schema), but the description mentions 'change stats + bbox' which is sufficient for an agent to know what to expect. The only minor gap is not explaining the `mode` and `threshold`/`tolerance` interplay, but the schema covers those.

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 100%, so the schema already documents all parameters. The description adds value by explaining the interaction between `ignore` and `region` (intersection), the default behavior of `mode`, and the conditional return of `include_image`. It doesn't repeat schema details but adds semantic context that helps the agent choose parameters correctly.

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 a specific verb ('Diff'), a clear resource ('current frame against a named baseline'), and the return value ('change stats + bbox'). It also distinguishes itself from siblings like glass_wait_for_region and glass_baseline_save by naming the baseline concept and the optional image return. This is a clear, specific purpose that an agent can act on.

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 context: it's for comparing frames against a saved baseline, and the `include_image` option is explained. It doesn't explicitly state when NOT to use it or name alternatives, but the sibling list includes glass_wait_for_region and glass_wait_stable which are related; the description doesn't explicitly route to them. However, the context is clear enough for an agent to infer when to use this tool.

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