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

Annotations only say this is a non-read-only, non-destructive, closed-world call; the description supplies the real behavioral context: no portal account or token is needed, the call can return interaction_mode_question to prompt the user, and the text result carries a Session section with thread_id and interview_handle that must be copied into later tools. That is material state-handoff information an agent could not infer from the annotations.

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?

Purpose is front-loaded in the first sentence and the operational rules follow in a logical order. There is some redundancy — 'Do not choose an interaction mode on the user's behalf' and the closing 'Preserve an explicitly selected mode without asking the user to choose again' restate the same rule — and the clause 'unless the user already named Review each step' is grammatically truncated, slightly slowing parsing.

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 need not be explained, and the description still covers the important dynamic parts: the conditional question turn, the handle propagation, and mode persistence. The one soft spot is that the conditional trigger is described only loosely ('If interaction_mode_question is returned'), and the truncated mode-selection clause leaves a small ambiguity for a first-time caller.

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% and the enum is documented inline, so the schema already carries the definition. The description still adds decision semantics the schema lacks: omit it by default, set it only when the user explicitly named a mode, and never infer auto_complete from a request for speed.

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?

Names a specific verb and outcome set: start a guided session to estimate app development cost, scope an MVP, and generate a software PRD. That is clearly distinct from the siblings (get_estimate_status, send_turn, submit_prd), and the follow-on reference to send_turn reinforces where this tool sits in the flow.

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 the default invocation (no arguments), the two exceptions that justify passing interaction_mode, and a hard when-not: do not pick a mode on the user's behalf, since wanting an estimate or a fast answer is not auto_complete. It also scripts the interaction_mode_question branch, including which option is the default and that the agent must wait before send_turn.

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