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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the closing "Read-only." earns little. The description does add genuine context beyond annotations: the response is "the same `ciQueue` block the write tools return," which tells the agent the shape is consistent across tools, and it discloses that owner+repo is what unlocks the per-repo view.

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?

Front-loaded with the core answer (how full the queue is) and then the optional per-repo extension, which is the right ordering. It is a dense em-dash sentence, but each clause carries distinct content — level, counts, slots, ETA, per-repo fields, recommendation — so little is wasted.

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?

With no output schema, the description correctly carries the return-value burden and enumerates the fields an agent will get back. Combined with the pre-push usage trigger and the owner+repo semantics, an agent has enough to invoke and interpret it; only the absence of explicit alternatives keeps it from a 5.

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 100%, so baseline is 3, but the description adds meaning: owner+repo must be supplied together, and supplying them yields that repo's queued/running runs, its share of CI work, slots it may hold while others wait, and a recommendation. That is more than the schema's terse "Optional, with owner."

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 resource and scope: the shared CI queue's fill level plus per-repo breakdown. It enumerates the exact outputs (level ok/busy/saturated, runs queued/running, runner slots, ETA), which lets an agent distinguish it from generic run-listing siblings like gluecron_list_workflow_runs.

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?

Gives an explicit trigger: "Ask before a burst of pushes." That is real when-to-use guidance rather than a restatement of purpose. It stops short of naming an alternative tool or a when-not-to-use condition, so it falls one step below the top.

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