update_issue

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool mutates an existing issue but gives no additional context: no mention of partial update semantics, persistence/irreversibility, required permissions, or response behavior. It also does not note that unspecified fields remain unchanged, which is a key behavioral trait for an update operation. The only implied behavior is that it modifies the issue, which is already evident from the tool name.

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 states the purpose and lists key fields, followed by three succinct, high-signal examples. Every element earns its place; there is no fluff or repetition of schema details. The structure is easy to parse quickly, making it ideal for AI consumption.

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 6 parameters, 1 required, and no output schema, the description sufficiently covers the core usage but has minor gaps. It does not mention that only provided fields are updated (partial update), nor does it describe the return value or error behavior. However, the schema supplies parameter details, and the examples provide enough context for typical use cases. The sibling tools like get_issue and create_issue are implicitly differentiated by 'existing issue', so overall it is reasonably complete for a tool of this complexity.

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 input schema covers all parameters with 100% description coverage, so the baseline is 3. The tool description adds value through its examples: 'Update issue ENG-123 to high priority' maps to priority and issueId, 'Assign issue ENG-456 to me' illustrates the special assigneeId value 'me', and 'Change the description of issue ENG-789' demonstrates description usage. These examples reinforce parameter semantics beyond the schema definitions, earning a 4.

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 uses a specific verb ('Update') and resource ('existing issue in Linear'), and enumerates the modifiable fields (title, description, assignee, priority, workflow state). This clearly distinguishes it from siblings like create_issue, search_issues, and get_issue, as it specifically targets existing issues. The examples provide concrete usage patterns, making the purpose unmistakable.

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 states 'existing issue', implying it should be used for modifications, not creation. It lists the fields that can be updated, which signals when to use this tool. However, it does not explicitly mention alternatives (e.g., use create_issue for new issues) or exclusions, leaving some guidance implied rather than explicit. The examples show common scenarios but no direct comparison to sibling tools.

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