Update Quarantine

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

Annotations only say readOnly=false and destructive=false; the description adds real behavioral context beyond that — partial-update semantics, the concurrency guarantee that concurrent edits are not clobbered, and the non-null assignee invariant. It does not mention required permissions or what happens if the quarantine has already been released, which keeps it short of a 5.

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?

Three short sentences, front-loaded with the mutation scope, then the patch rule, then the one hard constraint. No filler and nothing buried.

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 7-parameter mutation with thin annotations and no output schema, the description covers the semantics an agent most needs: which fields are mutable, that updates are partial, and the assignee invariant. Missing only failure/precondition context (released quarantines, invalid issue_key) and permission requirements.

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 86%, so the baseline is 3, but the description adds meaning the schema lacks: 'ends_in_days, counted from today' clarifies the otherwise bare integer, and grouping issue_key/issue_url as the linked ticket clarifies their relationship. It does not repeat schema detail such as the 90-day cap or 'me' for assignee.

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?

States a specific verb (Change) and resource (an active quarantine) and enumerates the mutable fields, so an agent can tell it apart from get_quarantine and release_quarantine by the word 'change' plus the field list. It never names a sibling explicitly, so routing to release_quarantine instead is left to inference.

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 establishes patch semantics ('Only the fields you pass change') and an invariant ('A quarantine always has an assignee'), which is genuinely useful guidance. But it never states when to prefer this over release_quarantine or quarantine_tests, nor any precondition such as the quarantine needing to be active at call time.

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