live_session_start

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

With no annotations, the description takes on the full burden of behavioral disclosure. It adds important details: default context_type 'lesson', and that an existing active room leads to joining rather than starting anew (joined_existing). However, it does not mention return values, success/error outcomes, or permission requirements, leaving some transparency gaps.

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 description is a single dense sentence that packs several critical facts: the entry point change, schema default, and existing-session behavior. It is front-loaded with the core action and avoids filler, though the date and narrative could be more compressed.

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 description covers the key scenario and the joined_existing edge case, which is valuable. However, without an output schema, it leaves return behavior undefined, and several parameters (goal, context_preview) remain unexplained. The tool is usable but not fully self-contained for an agent.

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 only 40% (context_type and idempotency_key have descriptions). The description adds meaning by stating context_type defaults to 'lesson', but it does not clarify the roles of goal, context_id, or context_preview. This is a partial, not full, compensation for the low schema coverage.

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 explicitly states its purpose: starting a new live session, and clearly identifies the actor (teacher/agent side) and the context (learner-side button retired). It distinguishes itself from sibling tools like live_session_complete/cancel/get by focusing on the 'start' behavior, including the edge case of joining an existing session.

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 clear when-to-use guidance: it is the main entry point for opening a class from the teacher/agent side, with the learner web button retired. It also outlines behavior when an active classroom already exists. It does not explicitly list alternatives, but the context strongly implies when this tool is appropriate.

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