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

Annotations already declare a non-destructive, non-idempotent, non-open-world write, so the bar is lower; the description still adds genuine context beyond them — server-stamped API-key UUID provenance that callers cannot spoof or supply, session/workflow ids being opaque metadata links only, and the constraint that new epics cannot be created already done. It stops short of describing side effects such as notifications or the returned object.

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?

Four dense sentences, purpose front-loaded, and each sentence carries non-redundant information — scope, subticket option, enum meanings, provenance, and the epic/status constraint. No filler, though the enum re-listing is somewhat close to restating the schema.

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 16-parameter mutation tool with no output schema and only 25% schema coverage, the description covers semantics, provenance, and one creation constraint but leaves roughly half the parameters unexplained and says nothing about the response. Adequate but with clear gaps.

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 description coverage is only 25%, so the description must carry the load, and it usefully explains parent_id (subticket linkage), the effort and action_type enums, and the session-id semantics. But of 16 parameters many remain undocumented in both schema and description (labels, assignee, priority, order_index, external_ref, effort_points, acceptance_criteria), so it only partially compensates.

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 and resource ("Create a ticket on the caller's board") plus the subticket variant via parent_id, so the agent knows exactly what operation this is. It does not name or differentiate itself from close siblings like ticket_batch_create, ticket_scenario_create, or project_create, so it stops short of a 5.

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?

Usage is implied: this is the single-ticket create, contrasted implicitly with the batch sibling, and the description tells the caller to "recommend" effort and action_type. However, it gives no explicit when-to-use/when-not conditions and never names an alternative tool, so guidance stays at the implied level.

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