plan_edit

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

With no annotations, the description carries the full burden, and it does disclose two important traits: no credits are spent and a render_quote (in whole credits) is returned. However, it never says whether the planned Edit node is persisted on the board, whether re-planning overwrites prior plans, or what permissions/board state are required — significant gaps for what appears to be a mutating planning call.

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 sentences, each doing distinct work: scope + capability list, cost behavior, then the required workflow. Front-loaded with the action and no filler or restated title.

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?

There is no output schema, and the description compensates partially by naming the render_quote return and its unit. For a six-parameter tool with a nested freeform ops array, though, the definition leaves the caller without enough to construct a valid ops payload or understand board_id/voice_id, so it is only adequate relative to the tool's 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 coverage is 50%, and the description usefully explains that output_seconds and ratios are what drive the render_quote, which goes beyond the schema. But the most complex parameter, `ops`, is a freeform array with only an `op` string required and no shape documented anywhere; the parenthetical list hints at op kinds but gives no structure, and board_id/voice_id remain completely unexplained.

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 names a specific verb and resource ("Plan an Edit node") and enumerates what that node can express (join, trim, text, captions, duck music, effects), which makes the tool's scope concrete. It also states the payoff — a render_quote — but does not explicitly contrast itself with siblings like quote_video or run_quote, leaving that distinction to inference.

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 situational guidance: this is the no-credit planning step, and the returned price must be shown to the user before they approve the render in the app. That establishes a workflow position. What's missing is an explicit when-not or a named alternative for callers who want to skip planning and go straight to quoting or rendering.

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