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

With no annotations, the description carries real weight: it discloses that only the final terminal result is returned, that per-step events arrive as MCP progress notifications, and critically that this only happens when the client supports them. That conditional is exactly the kind of behavioral caveat an agent needs before choosing this over the plain sibling. It doesn't address mutation scope or the approval/resume loop (left to the schema).

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 tight sentences: differentiation first, return/progress behavior second, usage guidance last. Nothing is repeated from the schema and no sentence is filler.

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 complex 15-parameter mutation tool with no annotations and no output schema, the description covers the key unknowns an agent faces: what comes back (terminal result only), how progress is surfaced, and its client-support dependency. The approval/resume flow and scene-mutation effects are only in the parameter descriptions, so a little context is missing at the top level.

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 100% across all 15 parameters, including long explanations for prompt, requirePlanApproval, workingMemory, and editedPlan, so the schema does the heavy lifting. The description itself adds no parameter semantics beyond what the schema already states. Baseline 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 defines the tool by explicit contrast with a named sibling ('Same as autonomous_edit but consumes the SSE event stream'), so the agent knows this is the streaming variant of the editing tool and what differs. It never states the editing verb/resource directly, relying on the reader knowing autonomous_edit, which keeps it short of a self-contained 5.

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?

'Use for long-running briefs where users expect live progress' gives a concrete selection condition, and the 'same as X but...' framing implicitly routes everything else to autonomous_edit. It stops short of naming the alternative and exclusion explicitly, so it's a strong 4 rather than a 5.

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