read_device

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

With no annotations, the description carries the burden of disclosing behavior. It clearly indicates a read-only operation, which implies no mutation, and it lists the admissible slot values, adding scope boundaries. However, it does not disclose potential error conditions, permission requirements, or behavior when the device is unavailable, though the output schema may cover return structure.

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?

A single sentence that front-loads the action and resource, then efficiently lists the acceptable slot values. Every word contributes, with no fluff or redundancy.

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 tool is simple with two parameters and an output schema present, so the description is largely sufficient. The only potential gap is the ambiguity between reading the emergency_stop slot and the separate emergency_stop sibling tool, but the verb 'Read' mitigates this and indicates no triggering behavior occurs.

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 the 'slot' parameter by enumerating its possible values, which is essential and absent from the schema. It does not elaborate on 'device_id', but the parameter name is self-explanatory, and the description as a whole makes the tool's semantics understandable.

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 uses a specific verb ('Read'), names the resource ('a device slot'), and enumerates the exact slot values it can read: state, position, enabled, or emergency_stop. This clearly separates it from mutating siblings like write_device and emergency_stop, and from discover_devices which enumerates devices.

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 only implied through the verb 'Read' and the sibling names, suggesting it is for inspecting device slots rather than writing or triggering emergency stops. There is no explicit statement of when to choose this tool over write_device or emergency_stop, nor any exclusions or prerequisites.

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