dm_plan_run

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

No annotations are supplied, so the description carries the full burden, and it does disclose the decision vocabulary (inject/downgrade/none) and the dual outcome shape (prompt_addendum vs would_have), which hints at a dry-run/trial behavior. It says nothing about side effects, whether state is persisted, auth requirements, or how the recommendation is applied, which are the gaps that matter for a planning tool.

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?

Two compact sentences, purpose front-loaded, no filler. The brace notation is dense and reads like a schema fragment, but every token carries information and nothing is wasted.

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 the return sentence is bonus rather than mandatory, and the payload key inventory partially compensates for 0% schema coverage. Against a 10-field nested payload and 25 same-family siblings, however, the absence of selection guidance and field meaning leaves real ambiguity.

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 0% and the single parameter is an untyped free-form object, so the description is the only documentation of the payload. It enumerates ten inner keys and marks three as required (workflow*, input*, context*) versus optional via brackets, which is substantial added meaning. It stops short of explaining what each field accepts or what values pilot_mode/run_model take.

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?

"Plan one-turn work" names a verb and a loose scope, and the return sentence (recommendation of inject/downgrade/none plus prompt_addendum or would_have) makes the intent slightly more concrete. But it never distinguishes itself from near-identical siblings such as dm_plan_result, do_plan_run, or do_plan_result, so an agent cannot tell which planner to pick from the description alone.

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?

The description contains no when-to-use guidance at all: no conditions, no exclusions, no mention of the obviously overlapping siblings. An agent must infer usage entirely from the name and the payload key list.

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