duddy_plan_status

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

With no annotations, the description carries the full disclosure burden. It usefully reveals domain-specific behavioral facts — the state values 'approved'/'applying' and the cursor field indicating step position — which an agent cannot get from structured data. However, it doesn't state the return shape, whether state can be other values (e.g., aborted, done), or what to do when the gate fails.

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 with the purpose front-loaded and the operational guidance immediately following. Nothing is redundant, though the gating conditions could be formatted more scannably.

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 one-parameter read tool with no output schema, the description supplies the essential operational context: what it reports and the preconditions to check before proceeding. The main omission is the possible set of state values and failure handling, which matters given this tool acts as a gate for duddy_apply_step.

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 0% and the single parameter plan_id is undocumented in both schema and description; the description only implies it refers to the plan being inspected. The parameter name is largely self-explanatory, so the gap is modest rather than severe.

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 gives a specific verb and resource ("查某个计划的状态与进度" – check a plan's status and progress), which is clearly distinguishable from the mutation siblings like duddy_apply_step and duddy_abort_plan. It doesn't explicitly contrast itself with duddy_run_status, the closest sibling, leaving a small ambiguity about plan status vs. run status.

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?

Usage is stated concretely: check before executing each step, and verify that state is 'approved' or 'applying' and that cursor points to the intended step. That is a real when-to-use gate rather than vague advice. It stops short of naming alternatives (e.g., duddy_precheck_plan, duddy_run_status) or stating when-not to call it.

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