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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safe-read profile is covered. The description adds scope content (reconnect/replay protocol, wallet-scoped auto-delivered execution.report channels) but says nothing about whether this returns static reference docs or live server state, or how large the payload is — a real gap for the only tool in the set describing the WS surface.

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?

One sentence, zero filler, front-loaded with the transport description before the taxonomy bridge and fallback context. Dense but every clause names a distinct, substantive section an integrator would need.

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 an output schema present, the description needn't describe the returned document's structure, and with annotations covering safety the remaining burden is scope naming — which it does exhaustively (URL, auth, message shapes, reconnect/replay, taxonomy bridge, auto-delivered channels, webhook fallback). Nothing required to call a zero-parameter documentation tool correctly is missing.

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?

Zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. The enumeration of topics plausibly maps to the sections the returned document contains, which is a mild extra benefit over an empty schema.

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 (Describe) and a specific resource (the Agent WebSocket transport), and enumerates the exact sub-topics covered: URL, auth schemes, message shapes, reconnect/replay, taxonomy bridge. The only wobble is the tool name 'discover_events', which suggests event-type enumeration and overlaps conceptually with siblings like kellian_list_event_types and kellian_discover_webhooks; the title and description correct that, but an agent skimming names could misfile it.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no named alternative ('for the webhook-only path see kellian_discover_webhooks'). The clause 'webhooks as the async fallback' hints at the WS-vs-webhook decision but never tells the agent which tool to call in that situation, leaving routing to inference from the sibling names.

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