move_gun

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

With no annotations, the description carries the full burden. It usefully discloses that hands listed in keep_hands maintain their hold and that the return includes each hand's displacement from its hold plus the barrel angle relative to the view line. However, it omits whether the move is relative to the current pose, what happens on failure, and whether any constraints or permissions apply.

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 purpose is front-loaded, and the dense middle sentence efficiently maps all parameters and output. It is appropriately sized for an 8-parameter spatial tool, with only minor redundancy and awkwardness in the axis clauses.

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, but the description helpfully summarizes the return values. For a spatial manipulator with no annotations, it still leaves gaps around the coordinate frame referred to by 'the view,' whether motion is relative or absolute, and what happens when hands cannot keep their hold. It is minimally viable but not fully complete.

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 25%, so the description must compensate, and it largely does: it assigns directional meaning to roll, swing, pitch, right, forward, and up, specifies centimeters for translational moves, and ties pivot to the bore or pivot point. This adds substantial meaning beyond the bare schema, though the exact axis conventions remain slightly ambiguous.

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 specific verb and resource: 'Moves the rifle from where it stands.' It is clear what physically happens, but it never names or contrasts with the sibling tool move_part, so an agent cannot tell from the description alone why it should choose move_gun over move_part.

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 explains the mechanics of the six movement axes but gives no when-to-use context, no prerequisites, and no alternatives. It does not state whether this is for aiming, posing, or collision avoidance, nor when to prefer reach or solve instead.

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