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

Annotations mark this as a non-idempotent, non-destructive mutation. The description adds genuinely useful context beyond the annotations: that the call is strictly project-scoped via explicit project_id and that it returns the project identity with the result (helpful since there is no output schema). It stops short of saying what is modified when re-invoked or how the added furniture interacts with existing overlays.

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?

Reasonably short, but the scope statement is front-loaded while the actual purpose sentence is buried in stylized phrasing ('small, steady, in the brand colour, clear of the corner mark'). That stylistic clause costs space without adding callable information.

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?

For a 15-parameter mutation with 7% schema coverage and no output schema, the description covers a good share of the boolean furniture flags and discloses both the project scope and the return shape. It leaves several string parameters (id, accent) and the start/end range semantics unexplained, so an agent still cannot configure the call confidently.

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 only 7%, so the description must carry the load and it partially does: it maps tl/tr/bl/br, rec, timecode, brackets, crosshair, grid, and colour (brand colour) to their intent. However it says nothing about id, accent, or start/end, and gives no format guidance for the corner-label or colour strings.

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 never states a plain verb+resource ('adds an HUD overlay'), instead using framing jargon like 'Frame furniture through the piece'. The enumerated elements (corner labels, REC dot, timecode, brackets, crosshair, grid) do let an agent infer the resource, but only after parsing. No differentiation from siblings such as add_overlay, add_title_card, or set_screen_frame.

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 only scope guidance is 'Defaults to the whole program', which implies a range default but not when to reach for this tool versus add_overlay/add_screen_frame. There are no stated prerequisites, exclusions, or alternatives.

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