wb_live_snap

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

No annotations are supplied, so the description carries the full load. It does disclose two real behavioral traits: the default preview mode and the fact that the operation is collapsed into one WB undo action, which tells the agent about atomicity and rollback. It says nothing about prerequisites such as requiring an active selection, the live-connection requirement, or what a preview returns, so the picture is only partly drawn.

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?

Two short sentences, with the operation stated first and the preview caveat second, so nothing is buried. There is no padding or repetition. It is efficient but leaves no room for the parameter detail the tool needs.

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?

This is a mutating live-scene tool with no annotations, no output schema, and six parameters at 0% schema coverage. A description this thin leaves key gaps: what preview mode actually does (dry-run output vs. nothing), whether a selection must exist first, and what rpc_dir and the direction vector mean. It is under-specified for the tool's complexity.

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% across six parameters. The description only hints at 'apply' and 'along a direction' and never explains the required rpc_dir string, the dir_x/dir_y/dir_z breakdown, or the timeout. The most important parameter, rpc_dir, is completely unexplained in both the schema and the prose.

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 gives a concrete verb and resource: 'Drop/snap the current selection to the live scene surface along a direction.' This separates it from the generic transforms in the sibling list (wb_live_move, wb_live_rotate) by naming the surface snapping operation. It never names a sibling to compare against explicitly, so it stops short of a 5.

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 phrase 'Preview unless apply=true' gives usable guidance on how to invoke it safely, which is better than nothing. But it never says when to use this instead of wb_live_surface_scatter, wb_live_move, or wb_live_align, which all touch selection placement. The agent has to infer the choice from the names alone.

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