linear_update_status

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

With no annotations provided, the description carries the full burden of disclosing behavior. It only says 'Updates the status' and vaguely references the scheduler, but does not explain side effects, validation rules, permissions, or what happens after the update. This is a significant gap for a mutation tool.

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, using two short sentences with no redundant content. It front-loads the core purpose. The second sentence adds useful context, though it could be phrased more clearly.

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 simple update tool with only two parameters, the description gives enough to understand the basic operation. However, the lack of output schema and annotations, combined with vague scheduler behavior, leaves gaps around return values and side effects. The description is adequate but not thorough.

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 two parameters with 0% description coverage, and the description does not mention them at all. While the status enum is self-explanatory, ticket_id's meaning and format are not clarified, leaving the description to compensate for the schema gap but failing to do so.

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 action ('Updates the status of a Linear ticket') and adds context about the scheduler picking up manually Done tickets. It is specific about the resource and verb, though it does not explicitly distinguish it from sibling linear_escalate, which might also change 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?

The second sentence implies a specific use case (letting the scheduler pick up a manually Done ticket), providing some contextual guidance. However, it does not explicitly state when to avoid this tool or name alternatives like linear_escalate, leaving the usage boundaries somewhat implicit.

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