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

Even though annotations already indicate non-read-only behavior, the description goes well beyond them: it explains that archived tickets keep their status, disappear from lists and syncs, retain id/URL for citations, refuse edits until restored, cascade to the active subtree, and are never destroyed. This is dense, relevant behavioral context and does not contradict the 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 front-loaded with the core purpose and then adds dense, high-value behavioral caveats. Every sentence earns its place: status-vs-archive distinction, side effects, cascade behavior, restore semantics, and non-destructiveness are all necessary for correct invocation.

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 only two parameters, no output schema, and rich annotations plus this description, there is no meaningful selection or invocation gap. The description fully characterizes the operation's state changes, visibility effects, and constraints, so the agent can invoke it correctly without additional documentation.

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 0%, so the description carries the full burden for explaining parameters. It explains the two actions ('archive' and 'restore') and clarifies what happens to the ticket_id, but it does not explicitly map each parameter to its allowed usage. Still, meaning is strongly recoverable from the description.

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 opens with a specific verb and resource: 'Retire an owned ticket from the working set, or restore one.' It clearly distinguishes archiving from status changes, makes the toggle behavior explicit, and gives enough differentiation from related ticket tools like ticket_update.

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?

It explicitly instructs when to use the tool ('retire an owned ticket' or 'restore one') and gives a hard exclusion: never use status 'cancelled' to mean 'archived.' It also notes that no delete tool exists, which prevents misuse and clarifies the appropriate boundary of the operation.

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