patch_story

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

Despite having no annotations, the description discloses important behavioral details: it acquires the _plan_lock for atomicity, it can only modify the listed fields, and it is safe with respect to the scheduler's tick. This is more than adequate given the lack of 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?

The description is concise and well-structured. It starts with the core purpose, then explains the key behavioral details (locking, allowed fields, exclusion). Every sentence adds value, and the format is scannable.

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 is moderately complex (nested object fields, required parameters) and has an output schema, so the description doesn't need to explain return values. It covers the most critical context: what fields can be edited, why locking matters, and which alternative to use for status changes. The only gap is a bit more detail on parameter syntax, but it's mostly complete.

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?

The schema has no description coverage (0%), so the description must carry the burden for parameter semantics. It does mention the 'fields' parameter by listing the allowed fields, but it does not explain the format of plan_name or story_key, or what the fields object should look like beyond the field names. This is partial compensation, but could be more explicit.

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 clearly states the tool's purpose: 'Edit a story's plan-authored fields' and lists the specific fields it can edit. It distinguishes itself from other tools by emphasizing that it edits fields without hand-editing the manifest JSON and that status transitions are handled elsewhere.

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 explicitly provides usage guidance: it says when to use this tool (for editing specific fields) and when not to use it (for status transitions, which go through set_story_status). It also warns against hand-editing the manifest JSON, effectively telling the agent to use this tool instead.

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