arrange_props

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

With no annotations at all, the description carries the full burden and does well: it discloses collision checks and undo support, the 32-instance cap, the mutation semantic that 'Existing instances move, extra ones are duplicated,' that fit can shrink under-anchor props, and the two queued states (inspection vs. arrangement) with recovery instructions. It omits permission/auth requirements and any timing or rate considerations for a placement operation.

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 core purpose is front-loaded in the first sentence, followed by compact, high-density clauses covering item shape, relations, mutation semantics, and error recovery. No sentence is filler, and the terse fragment style suits an agent audience.

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 an 8-parameter mutation tool with no annotations, no output schema, and 0% schema coverage, the description covers the important behavioral and error-recovery surface but leaves several parameters (gap, anchor_id, face_anchor, snap_to_surface) and the return/result shape unexplained. It is useful but not fully self-sufficient.

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 0%, so the description must compensate, and it partially does: it documents the items shape ({asset_id, count=1, object_id?}), the 32 cap, the valid relation values (around, along, under, right, front), and the fit shrink behavior. It says nothing about gap units/meaning, anchor_id selection, face_anchor, or snap_to_surface, leaving four of eight parameters undocumented anywhere.

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 opens with a concrete verb+resource+scope: 'Place managed props relative to a selected real scene anchor,' which is far more specific than a tautology and clearly separates it from build/create/import sibling tools. It never explicitly names a sibling such as compose_scene or edit_selected_prop, so differentiation is inferred from the anchor-relative placement framing rather than stated.

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 operational routing for queued/failed calls ('retry with inspection_request_id', 'poll its exact request with get_task_status; do not submit the layout again'), which is useful when-to guidance for the error path. However, it never says when to pick this tool over the many adjacent scene-editing siblings (compose_scene, edit_selected_prop, create_prop_set), leaving the primary selection decision to inference.

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