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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the 'Read-only' sentence is redundant, but the description adds real behavioral context: the output shape changes depending on whether owner+repo are supplied, and it notes the result is the same `ciQueue` block the write tools return, which helps an agent correlate responses. It omits cost/latency or rate-limit traits, so not 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?

Almost every clause carries information, largely because there is no output schema and the return fields must be described somewhere. But it is delivered as one sprawling em-dash-laden sentence that mixes purpose, output fields, and guidance, so it is neither front-loaded nor scannable; the 'Ask before a burst of pushes' cue is easy to miss.

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, describing the returned blocks (ciQueue, explanation, executor, holdReason) is necessary and is done thoroughly; parameters are covered and the read-only nature is stated. The remaining gap is relational: it does not clarify how this differs from merjax_ci_health or why an agent would call this instead of merjax_ci_executor for the executor portion.

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% and both parameter descriptions are adequate, so the baseline is 3. The description earns an extra point by spelling out the semantic effect of supplying owner+repo (repository-scoped runs, share of CI work, per-class slot holds, and per-run wait explanations) rather than just restating the fields.

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 opening clause ('How full the shared CI queue is, and what to do about it') plus the enumeration of level, queued/running runs, slots and wait estimate makes the resource and the payload unambiguous. However, it never distinguishes itself from siblings like merjax_ci_health or merjax_ci_executor, and by folding an `executor` block into its own output it actively blurs the line with merjax_ci_executor.

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?

There is one concrete usage trigger, 'Ask before a burst of pushes', which is genuinely actionable. But it is buried mid-paragraph, there are no exclusions, and no alternative sibling is named for the overlapping health/executor questions an agent might have instead.

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