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

Goes well beyond the readOnly/idempotent annotations: discloses that results are RECONSTRUCTED from connect/subscribe/close records rather than live state, that it can lag a few seconds, that 'open' merely means no close was recorded (server crashes record none), that channels appear only after close, and that `truncated` signals a partial read of the window. This is exactly the caveat set an agent needs to interpret results correctly.

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 resource framing is front-loaded and every clause carries information — the field list substitutes for a missing output schema. It is dense and runs as one long sentence, which costs readability, but nothing is padding.

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?

With no output schema, the description supplies the full return shape (path, url, api_key_id/oauth_client_id, connected_at, state, counts, closed_at, duration_s, channels, close_code, events_sent, truncated) plus interpretation caveats. An agent can call and read this correctly without further context.

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% and both parameters (hours, limit) are documented with ranges and defaults in the schema itself, including the non-obvious 'a connection opened before it is not listed'. The description adds no additional parameter guidance, so the baseline 3 applies.

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 resource (stream connections) with explicit scope: this account only, across every API key and OAuth app, newest first, plus the exact field set returned. That field disclosure clearly separates it from the other stream_* siblings (events, info, check_filter) without ambiguity.

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?

Gives concrete use cases: 'see why a socket was closed or whether two programs share a key (each closes the other with 4410)'. It doesn't explicitly say when NOT to use it or name a sibling alternative, which keeps it below a 5.

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