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

Goes well past the annotations (readOnly=false, idempotent=true, destructive=false) by disclosing the claim ordering rule, the capacity cap ('at most a third of the runner slots, so prioritizing many runs cannot starve the rest'), repeat-call semantics, no-op behavior for non-queued runs, and the scope/admin requirements per level. This is exactly the extra context annotations cannot carry.

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 action and mechanism, then constraints, then permissions — a sensible ordering with no filler sentences. It is dense (multiple clauses per sentence) but every clause conveys a distinct rule the caller needs.

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?

No output schema exists, and the description covers return-relevant behavior at a high level ('a running or finished run is reported, not changed') without detailing the response shape or what a successful prioritize returns (level echo, lane position). For a mutation tool with auth gates this is close to sufficient, with only the return payload underspecified.

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 50% — `level` and `run_id` are documented in the schema, while `owner` and `repo` are bare. The description does enrich `level` by explaining the ordering (normal < high < critical) and that high/critical require site admin, but adds nothing about `owner`/`repo` or the leading-hex-prefix id form beyond what the schema already says.

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 ('Move a QUEUED workflow run into the priority lane') and explains the mechanism that distinguishes it from siblings: claims ahead of class order, highest level first, then oldest. An agent can tell immediately this is not cancel_workflow_run, get_workflow_run, or 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?

Clearly bounds the when: 'Only queued runs; a running or finished run is reported, not changed,' and notes that calling again on an already-prioritized queued run changes its level rather than erroring. Missing an explicit pointer to a sibling for the non-queued case, but the preconditions are unambiguous.

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