set_story_status

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

With no annotations, the description carries the behavioral burden and does well by disclosing that it acquires _plan_lock and only accepts pipeline-defined statuses. This tells the agent about locking side effects and invariants. It does not cover possible failures or permission requirements, but the key behavioral constraints are present.

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?

The description is front-loaded with the primary action and includes an example before adding lock and status constraints. The status list is long but necessary because the schema lacks enums. Minor indirectness ('for the same reason patch_story does') keeps it from being perfectly self-contained.

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?

The tool has an output schema, so return-value details are not required. The description gives enough context for a correct call: what the tool does, the exact allowed statuses, an example use case, and lock behavior. The only gaps are minor details about the plan/story parameters and failure conditions.

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 no enum metadata exists, but the description supplies the complete allowed status set, which is the critical parameter meaning. plan_name and story_key are left to their self-explanatory titles, and the description's story/plan context partially covers them. This is solid compensation for a low-coverage schema.

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 states a specific action ('Transition a story to an explicit status') and contrasts it with hand-editing the manifest JSON. The fixed status list and 'sanctioned status change' clarify exactly what this tool is for, making it distinguishable from related story tools by defining its scope rather than by name.

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 gives a concrete usage example ('resetting a parked story to interrupted so the scheduler retries it') and says the tool is the sanctioned path rather than inventing state. It does not explicitly name alternative sibling tools or state when not to use it, so it lacks full exclusion guidance.

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