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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds meaningful behavior beyond that: it does not persist state, does not use a draftId, returns a new document, and performs a re-layout/check pass. The note that follow-on components must include placement when dimensions change is useful operational context.

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 information-dense sentences with the merge/delete semantics front-loaded and the non-persistence and placement caveats following. Every clause carries operational meaning, though the packing is tight enough that a reader must parse carefully; it stays within the appropriate size for the tool's complexity.

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?

There is no output schema, so the description appropriately states that a new document is returned. For a nested-object patch tool with 50% schema coverage the description covers the essential call semantics and state-behavior caveats, though the placement requirement is mentioned without full detail on where it belongs in the patch.

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?

With 50% schema coverage, the description carries real weight: it clarifies that `document` is the full SceneDocument from the previous call and that `patch` is applied by id merge with explicit deletion via the remove structure. The added semantics (merge-by-id, dimension-change/placement coupling) go beyond the raw schema, though it does not map every patch subfield.

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 precise verb-and-resource operation: take the previously returned full document plus a patch, merge by id or explicitly delete, then re-layout and re-check. This clearly distinguishes it from siblings like build_scene (full construction) and inspect_scene (read-only inspection), so an agent can identify the incremental-update tool 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 the prerequisite that the input must be the document returned by the last call and that a patch must accompany it, which implies when this tool applies. However, it never explicitly contrasts with build_scene or preview_scene, nor states when NOT to use it, so the routing guidance is only implied.

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