Test driving speed

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

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description usefully reinforces this by warning that the robot drives straight ahead and needs clear floor, implying collision risk. It does not explain blocking/time cost, what happens at the end of the run, or how return_to_start interacts with the physical motion. Adequate given annotations but adds only partial 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?

Two tight sentences with the experiment framing front-loaded and the physical constraint last. No filler, though the trailing clearance sentence fragments the flow slightly and could be folded into the first.

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 a motion tool with no output schema, an agent is not told what results are returned (top speed figure? acceleration time? position) beyond the general intent, nor how long the robot is committed to the run. It covers the purpose and the main prerequisite, but leaves the outcome and timing behavior underspecified.

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 coverage is only 33%: distance_mm carries a description (oddly framed as clearance rather than a measurement), while speed_percent and return_to_start are undocumented. The description partly compensates by referencing the 'measured distance', the 'speed setting', and the clearance requirement, but return_to_start's behavior and units/ranges for speed are left to the schema alone.

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?

States a specific verb and resource: drive a measured distance and time it to derive top speed and acceleration. This clearly differentiates it from the generic 'move' sibling, though it never names the contrast explicitly. An agent can tell this is a measurement experiment, not a locomotion command.

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?

Usage is implied by the goal ('to find the robot's top speed at this speed setting'), so an agent can infer it is a benchmarking/characterization tool. However, there is no explicit when-not guidance or naming of alternatives such as move or test_kick for other measurement needs. The spatial prerequisite ('needs that much clear floor ahead') is the only hard usage constraint given.

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