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

Annotations only cover the safety profile (readOnly=false, idempotent=false, destructive=false); the description layers substantial operational context on top: the live_project_ambiguous error code and its live_projects payload, automatic creation of 'Your First Live Project', RTMP falling to 'stopped' when no free transcoder within ~15 seconds, and the fact that no stream_key is returned. That is exactly the side-effect and failure-mode detail annotations cannot express.

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?

Front-loaded with the action, then usage routing, then edge cases — a sensible ordering. It is dense and nearly every sentence carries a non-obvious fact, though the RTMP transcoder paragraph and the repeated instruction to call start_live_stream before publishing overlap slightly and could be tightened.

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?

An output schema exists, so return values needn't be enumerated, yet the description adds the one thing an agent would get wrong — that stream_key is absent and get_live_stream_key must be called for OBS/ffmpeg. Combined with the ambiguity error path and the auto-created project naming instruction, an agent has everything needed for a correct call and follow-up.

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% so the baseline is 3, but the description adds conditional logic for two parameters: omit ls_project_id when the owner has exactly one project (and what happens when they have several), and pass input_format when the user names rtmp/webrtc/srt. It says nothing about output_format, stream_timeout, or playback_domain, leaving a third of the parameters to the schema alone.

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?

Opening sentence gives a specific verb and resource ('Create a live stream') scoped to 'the selected live project'. It immediately separates itself from siblings by naming update_live_stream, start_live_stream, and get_live_stream_key in the routing rules, so an agent can place it without opening any 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?

Explicitly states when to call ('when the user asks to start streaming'), when NOT to call ('When they name a stream that already exists, do not create another one — call update_live_stream'), and the dependency ordering with start_live_stream before ingest or publish. This is a full when/when-not/alternatives mapping rare in tool descriptions.

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