update_epic

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

Annotations already indicate that the tool is a write operation (readOnlyHint=false) and is idempotent and non-destructive. The description confirms this with 'Update an epic' and adds the WRITE_ENABLED prerequisite, which is consistent. However, it does not elaborate on what happens during the update (e.g., partial vs full replace, error handling, or side effects). Given the annotation coverage, the description adds limited behavioral context beyond confirming the operation type.

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 a single, front-loaded sentence that communicates the essential purpose and a key condition without any wasted words. Every element serves a purpose: the action verb, the target resource, and the prerequisite. It is optimally concise for an agent to quickly parse and understand.

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?

Given that the tool has a complete parameter schema and annotations covering behavioral aspects, the description is adequate but not comprehensive. It does not explain the return value (there is no output schema) or the effect of the 'fields' parameter (e.g., whether it performs a partial update or full replacement). For a mutating tool without an output schema, a brief note about the update behavior would improve completeness. The current description is minimally sufficient.

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 parameter schema provides descriptions for both sys_id and fields, achieving 100% coverage. The description does not add any additional meaning beyond what the schema already contains—it merely names the parameters implicitly. Since the schema already does the heavy lifting, a score of 3 is appropriate; the description adds no extra semantic value.

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 explicitly states 'Update an epic', which is a clear verb+resource combination. It also includes the prerequisite condition 'requires WRITE_ENABLED=true', which helps the agent understand the access context and distinguishes this tool from read-only ones like get_epic or list_epics. Among many sibling update tools, the specific resource 'epic' is unambiguously identified.

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 provides a clear prerequisite (WRITE_ENABLED=true) but does not indicate when to avoid using this tool or suggest alternatives. For example, it does not contrast with create_epic for new epics or update_record for non-epic records. The usage guidance is minimal, relying on the agent to infer context from the tool name and sibling list.

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