join_session

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

With zero annotations, the description carries the full burden of behavioral disclosure, and it does add useful content: the bind is to an existing session, the tool does not archive anything, and it is a mandatory precondition for other radio tools. However, it omits equally important idempotency/failure content — what happens if the session id does not exist, whether a second call reinstates or errors, and what identity/authorization guarantees 'declare the calling agent's id' implies. The description earns a mid score by adding some behavioral context but leaves the agent to guess on boundary cases for a stateful binding operation.

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, front-loaded sentences each serve a distinct purpose: the core operation, a negative behavioral qualifier, and the usage precondition. The only slight weaknesses are the exactly GNATC — 'Does not archive anything' does meaningful work only if the reader had expected archiving otherwise, and 'radio tool' is internal jargon — so the score stops short of top marks, but almost every word earns its place.

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?

The output schema removes the need to describe return values, and the description covers the cardinal points: what the tool does and why/needing when to call it. Given the tool's role in a session-lifecycle stateful binding with a spawned-child override path, the description stays incomplete on edge-behavior — repeated joins, what determines an 'active' session, invalid session_id handling, and the child-token role — meaning an agent may need to probe to discover consequences. It suffices for the standard flow but is not fully complete for its complexity.

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 67%, so the structured data already documents agent_id and child_token and the override of session_id/agent_id. The description adds meaning to the otherwise undescribed session_id by invoking 'an existing active session', which distinguishes it from a session that must be created, and ties agent_id to 'the calling agent's id'. It does not mention child_token at all, and the general statement 'declares the calling agent's id' is slightly inaccurate for the child-token path where session_id/agent_id are ignored, so the added semantic value is partial.

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 specific verb+resource combination — 'bind this connection to an existing active session' — and clarifies the scope by saying 'existing active session', immediately differentiating it from session creation tools like plan_session. It also names the calling agent's identity declaration, which is a precise second behavior. This makes the tool recognizably distinct from most of the 61 sibling tools without needing to open their schemas.

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 gives an explicit invocation condition: 'Required before any other radio tool when the agent did not itself call plan_session.' It names the alternative (plan_session) as the source of the session, so the when-to-use and the when-not-to-use are both strongly derivable, and the consequence of not using it (subsequent radio tools would misapplied at this session) is implicitly clear.

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