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

Beyond the annotations (destructiveHint, idempotentHint, non-read-only), the description discloses concrete behavior: private-by-default creation, a 302 /unauthorized response for non-owners, refusal for structurally authentication-gated apps, and a read-write token requirement. These are operationally decisive facts an agent could not infer from the annotation block.

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?

The core action and the public=false reverse case are front-loaded in the first sentence, and each subsequent sentence carries a distinct constraint (default privacy, sibling exclusions, refusals, auth). It is dense but no sentence is pure filler; the dashboard-pill analogy is the only soft clause.

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 three-parameter mutation with an output schema, the description covers what an agent needs: defaults, reversibility, response behavior for non-owners, auth requirements, and refusal conditions. Nothing material is left for the agent to guess before calling.

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 the baseline is 3, but the description adds meaning: it pins the default of public to true and frames it as a publish/unpublish switch, and reinforces job_id as the target commit. The project_id ownership constraint is left 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?

The description states a concrete verb and resource ('publish a commit... or take it back to owner-only with public=false') and explains the mechanism ('same as the dashboard's private/public pill'). It further separates the tool from update_settings and redeploy by naming what those do instead, so an agent can place it among siblings without opening schemas.

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 a clear triggering condition: commits ship private, and a link meant for someone else 'needs this first', with public=false as the reverse case. It also rules out two alternatives explicitly ('update_settings default_public only governs commits created later; redeploy does not change visibility'), though it does not contrast with the similarly named promote_commit/demote_commit siblings.

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