Read instrument error queue

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower, yet the description adds genuine behavior: it is a draining loop that repeatedly issues SYST:ERR? rather than a single read. It does not disclose what happens if the queue exceeds the cap or whether errors are consumed irretrievably.

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, each earning its place, with the core mechanism front-loaded before the usage cue.

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 so return values need not be described, but the description omits parameter meaning for a 0%-coverage schema and creates an unresolved tension with max_errors: it claims the queue is popped 'until empty' while the schema caps errors at 20 by default, leaving the agent without guidance on that interaction.

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 carries the full burden, yet it never mentions either parameter. 'resource' (which instrument, presumably defaulting to the active session) and 'max_errors' (cap on the drain loop) are left entirely for the agent to infer from property names.

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 ('Pop SYST:ERR?') and names the actual mechanism (draining the instrument error queue until empty). No sibling tool covers error retrieval, so it is unambiguous even without explicit sibling contrast.

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?

'Call this after any failed command' gives a clear trigger condition for invocation. It stops short of stating when not to call it or how it relates to write/query siblings that would surface the same failures.

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