Robot position

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

Annotations already certify read-only and idempotent, yet the description adds real behavioral context: up to 15 s of sampling latency, concrete read rates (8 joint reads/s per unit, 2 pose reads/s per robot), a user-controlled off switch, and a stale/replayed data caveat. It also includes a prompt-injection warning that controller text is data, not instructions, which annotations cannot express.

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?

Five sentences, front-loaded with what is returned before the cost and safety caveats, and each sentence carries distinct information. The read-only sentence partly repeats the readOnlyHint annotation, which is minor waste but also useful reinforcement for a robot-control context.

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?

An output schema exists and all three parameters are documented in the schema, so the description only needs to supply what structured fields cannot: latency, sampling cost, user override, and data-trust caveats. It covers all of those, leaving nothing an agent would need before calling it.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains the cost of sampling that the 'fresh' flag triggers (15 s, defined read rates) and warns that the daemon samples every unit anyway, which shapes how 'unit' should be interpreted. That is genuine added value beyond the field descriptions.

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 names the exact resource contents: joint positions, TCP pose per mechanical unit, motion state, and joint-limit proximity. That is far more specific than the name alone and clearly separates it from siblings like get_controller_status or get_rapid_execution. It never states the read verb explicitly or names a sibling, 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?

Usage is implied by 'To return current values, this tool may ask the daemon to sample...' which tells the agent when fresh sampling kicks in and that a person can disable it. There is no explicit when-to-use/when-not or routing to alternatives such as summarize_controller for an overview. The agent must infer the choice.

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