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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses the post-creation state machine ('enters triage and the dispatcher assigns it to the best matching agent') and the dedup contract: the board keys on problem class + root-cause object so a previously-seen fault lands as a recurrence rather than a duplicate, and 'the result tells you which happened'. That is substantive behavioral context an agent cannot get from structured fields.

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?

Purpose, kinds and triage behavior are front-loaded, but the closing paragraph is a dense run-on that restates the dedup mechanism already spelled out in the condition schema description ('Same class, same object, open ticket = recurrence'), and the scan/audit trailing sentence is an afterthought. Functional but with clear redundancy.

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 nine-parameter creation tool with no output schema, the description covers creation semantics, dispatch, dedup keying, and the archived-cluster constraint, and signals what the result conveys. It does not describe the shape of the returned ticket or what an ambiguous/dedup-ed result looks like in detail, but nothing critical to invoking it correctly is missing.

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 already 100%, so the baseline is 3; the description earns above that by explaining how parameters interact for dedup (condition + resource_kind/name keys on the object's root cause, a pod resolving to its Deployment/DaemonSet/CronJob, otherwise on the cluster) and that cluster_id defaults to the session cluster. It still leaves cluster_id/resource_namespace edge behavior mostly to the schema.

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?

Opens with a specific verb and resource ('File a new ticket on the AI work board') and enumerates the concrete categories it accepts (gap, chore, incident, request). This is clearly distinguishable from the large family of sibling ticket_* and create_support_ticket tools, which it never risks being confused with.

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 gives real selection guidance: what each kind means, when condition/resource_* fields are required ('required for kind incident and insight'), and an explicit exclusion with a fallback ('Tickets cannot target an archived cluster - file board-level (no cluster_id) work instead'). It stops short of naming sibling alternatives (e.g. when to use create_support_ticket instead), so 4 rather than 5.

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