Channel socket (undocumented)

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true), and the POST in the description is consistent with a non-read-only call. Beyond that, the description adds a genuinely useful meta-signal: the upstream API is undocumented and the side effects are unknown, which is real context an agent needs. It still does not disclose auth requirements, what succeeds/destroys, or the response behavior.

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?

Three short sentences, front-loaded with the route, with no padding. The middle sentence about StreamElements documenting the endpoint without a description is meta-commentary that could be compressed, but nothing is bloated.

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?

For a POST with no output schema and unknown semantics, the description leaves the agent without any means of predicting the effect or even confirming the call is safe to make. Honesty about the gap is better than fabrication, but the definition still does not give enough to invoke the tool confidently.

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 coverage is 100% with a single optional parameter, and the schema already documents the channel id format and its SE_CHANNEL_ID fallback. The description adds nothing about the parameter, so the baseline of 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?

The description gives the raw HTTP route and admits the purpose is unknown ('appears to relate to the channel's realtime socket connection'), so it never states a concrete verb+resource an agent can act on. It is more informative than a bare tautology, but it stops short of telling the agent what the tool actually does.

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?

'Only use it if you know what it does' is an explicit warning against use, which has some routing value. However, it names no alternatives among the many siblings (channels_get, sessions_get, etc.) and gives no positive condition for when this call is appropriate.

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