Ui (write)

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

Annotations already declare destructive/non-idempotent/write, and the description adds real context beyond them: changes may overwrite current values, every change is read back with receipt.verified=false signalling it did not take, and invoke_menu has the side effect of bringing Resolve to front. That read-back verification semantics is precisely the kind of behavior an agent cannot infer from annotations.

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?

Front-loaded with the core behavior and a warning, then a compact bulleted action list — high signal per sentence. The closing line ('Calls known in advance...: ONE batch_run') is telegraphic to the point of being slightly awkward to parse.

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, the description needn't explain return values, and it still usefully explains the receipt.verified field. For a destructive, four-action tool it covers behavior, prerequisites, and batch alternatives; minor gaps are the interplay with ui_read and what a 'keyboard_preset' actually is.

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 100% and the nested op object accepts additionalProperties, so the schema alone does not tell an agent which payload keys each action needs — the description does, listing keyboard_preset, path/validate_path, and command per action and marking required ones with '*'. It stops short of a 5 because it omits per-param value formats (e.g. what a valid menu path looks like) and rides on describe_action for the rest.

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 opening sentence names the resource and mutation ('Change ui state'), and each of the four ops is spelled out with a specific verb and object: split clips at playhead, click a menu item, open the Gallery panel, run a named command. An agent can distinguish this from ui_read and from batch_run without opening either 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?

Explicit routing guidance is present: use batch_run when calls are known in advance, use describe_action for param lookup, and open_gallery_panel is flagged as a prerequisite for GalleryStillAlbum.ExportStills. It lacks a 'use ui_read instead when...' exclusion, so it stops just short of the top score.

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