Measure WebSocket

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

Annotations only cover readOnlyHint/openWorldHint; the description adds substantive behavior beyond that: measurement origin (server's network position), the fact that zero messages is a valid observation rather than a failure, and that silence is not diagnosed. It does not cover auth/network-policy expectations or the truncation semantics handled elsewhere, and the readOnlyHint sits slightly uneasily with the optional `send` capability.

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?

Purpose is front-loaded in the first sentence, followed by a one-line measurement-scope note and a compact negative list. The trailing clause 'does not say whether silence is a problem' is mildly redundant with the preceding zero-messages statement, but otherwise every clause carries information.

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 nine parameters, nested `send` objects, and an output schema, the description supplies the behavioral framing the schema cannot (timing origin, silence semantics, no reconnection). It is nearly complete, lacking only mention of the network policy / authorization context that the schema references for `url` and `headers`.

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%, so every parameter (listen_seconds, max_messages, max_message_bytes, headers, send, etc.) is already documented in the schema, including caps and defaults. The description adds only timing semantics ('offset from the open'), so the baseline 3 for schema-driven coverage is correct.

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 states a precise verb chain (connect, listen for N seconds, return arrived messages with absolute time and offset from open) and names the resource (WebSocket), which cleanly separates it from the sibling facts.measure.http. An agent knows exactly what this tool produces without reading the schema.

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?

It gives explicit negative scope -- does not wait for a particular message, does not interpret payloads, does not reconnect -- which tells the agent when this observation tool is the wrong choice for waiting/asserting on a specific message. However, it never names the alternative tool (e.g. facts.recall.assert) that would be correct for that job, so routing is left to inference.

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