plan_joint_trajectory

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

With no annotations provided, the description carries the full burden of behavioral disclosure—and it excels. It states the call never executes, returns an opaque id, distinguishes collision_checked reporting between planners, and explains start_joint_positions default behavior. It also notes reproducibility concerns, which is valuable behavioral context absent from the schema.

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 description is three tight sentences with no filler. It front-loads the core purpose, then packs high-value behavioral and parameter details into a compact structure. Every sentence earns its place.

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?

The description covers the most critical behavioral aspects, and the output schema presumably documents the returned trajectory_id. However, given the tool's 10-parameter complexity and 0% schema coverage, several non-obvious parameters (prim_path, timeout_ms, random_seed, idempotency_key) remain unexplained. It is adequate but has clear gaps around prerequisites and parameter semantics.

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. It does explain planner values and start_joint_positions, but 8 of 10 parameters (prim_path, goal_joint_positions, timeout_ms, random_seed, robot_model, max_iterations, command_id, idempotency_key) receive no semantic explanation. The description adds meaning for only a minority of the parameters.

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 specific action ('plan a bounded joint trajectory'), the resource (joint trajectory), and the return type (opaque trajectory_id). The phrase 'This call never executes' clearly distinguishes it from execute_trajectory, which is a sibling tool. This is a precise, non-tautological purpose statement.

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 gives explicit guidance on planner selection (rrt vs cspace) and on when to pass start_joint_positions explicitly for reproducible offline planning. 'This call never executes' implies the caller should use execute_trajectory for execution, though it does not name that sibling explicitly. No alternative tool is directly referenced, so it falls just short of the strongest possible guidance.

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