stim_status

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

No annotations are provided, so the description carries the behavioral disclosure burden. The description indicates a read-only reporting action ('Report...'), which is clear. However, it doesn't disclose what happens with an invalid session_id (error behavior, failure mode), whether it reflects real-time state or a snapshot, or any side effects. For a status tool this is reasonably low-risk, so the gaps are moderate.

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 a single concise sentence listing the exact three things reported. Zero wasted words, front-loaded with the verb 'Report'. Ideal conciseness for a status tool.

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?

There is an output schema present, so return values are presumably documented there. The description names the three report dimensions (backends, arming state, dispatch counts), which is sufficient context for an agent to know what to expect. Minor gap: it doesn't note that this is a monitoring/snapshot call vs. a subscription, but for a 'status' tool this is reasonably complete.

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 100% (the only parameter `session_id` is documented as 'The session to report on'). The description adds no additional semantics beyond the schema, and with a single simple parameter there's little to add. Baseline 3 is appropriate when the schema fully documents the parameter.

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 clear resource+aspect pattern: 'Report attached stimulation backends, arming state, and dispatch counts.' It clearly states what is reported. However, it doesn't explicitly differentiate from siblings like `list_stim_backends`, `stream_status`, or `processor_status`, though the specific enumerations (attached backends, arming state, dispatch counts) provide reasonable distinction for a status tool.

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 implies this is a status/read tool for a given session (via `session_id`), but provides no explicit guidance on when to use it versus `list_stim_backends`, `arm_stim`, `disarm_stim`, or `stream_status`. It does not state whether it should be called before arming, after attaching backends, or for monitoring. Usage context is only implied by the status-reporting nature.

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