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

Annotations already cover safety (write, idempotent, non-destructive, closed-world). Beyond those, the description adds real behavioral context: the call is scoped strictly to the explicit project_id, the active-project pointer is never guessed, the return includes project identity, and each panel's rect is reported. It still doesn't say what happens on partial overlap with existing stacks or how conflicting panel counts are handled.

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?

Three dense sentences, front-loaded with the PROJECT-SCOPED constraint, and each sentence carries content rather than filler. The panel-format shorthand is compact but slightly cryptic, and the return-value sentence could be folded in more tightly.

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 9-parameter write tool with 11% schema coverage and no output schema, the description does useful work by explaining the panel syntax and the return payload. However, half the parameters (start/end/grow/direction/id) are undocumented anywhere, which leaves the agent under-informed for a moderately complex layout call.

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 11% (just project_id), so the description must carry the load, and it partially does: it defines the panel string syntax (asset:<key> | source:<seconds> | <storage key>), the 2-4 panel bound, labels, and grow_at. It leaves id, start, end, grow, and direction unexplained, so several parameters remain opaque.

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?

States a concrete outcome: stacking 2-4 panels of independent footage with labels and an optional grow-to-full-frame panel. That is specific enough to know it configures a multi-panel layout rather than, say, compositing a single element. It stops short of naming or contrasting the closest siblings (compose_panels, add_collage), so it is clear but not differentiating.

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 where this fits ('so a flash or effect can be clipped to one') and insists the call is project-scoped, which is genuine selection guidance. But it gives no when-to-use-vs-alternative rule against the many sibling layout tools, leaving the agent to infer the choice.

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