Set pull request auto-complete

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state that 'Policy bypass is always false', which is a useful behavioral constraint. However, it doesn't disclose the mutation's side effects (e.g., whether enabling auto-complete immediately triggers a merge when policies pass, whether disabling cancels pending auto-complete, or whether the confirm parameter is a safety mechanism). The description is too thin to fully inform an agent about the operation's behavior.

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 description is very short and front-loaded: the first sentence states the action and resource, and the second sentence adds a key behavioral constraint. Every word earns its place. However, it is arguably too terse given the complexity of the tool (9 parameters, mutation), so it doesn't fully earn a 5.

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?

Given the tool's complexity (9 parameters, 4 required, mutation, no output schema, no annotations), the description is incomplete. An agent needs to know what 'auto-complete' means in this context, what the 'confirm' flag is for, how merge strategy and other options interact, and what happens after the mutation. The description only covers the enable/disable toggle and the policy-bypass constraint, leaving significant gaps.

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 description coverage is only 11%, so the description must compensate for the undocumented parameters. The description only clarifies the 'enabled' parameter (enable or disable) and the 'policy bypass' concept, but it doesn't explain the meaning of 'confirm', 'mergeStrategy', 'deleteSourceBranch', 'mergeCommitMessage', 'transitionWorkItems', or 'project'. With 9 parameters and only 11% coverage, the description fails to add meaning beyond the schema for most parameters.

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 specific verb ('Enable or disable') and resource ('policy-respecting PR auto-complete'), which clearly distinguishes it from sibling tools like complete_pull_request or update_pull_request. It could be slightly more explicit about the 'auto-complete' concept, but the core purpose is clear.

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?

The description does not provide any guidance on when to use this tool versus alternatives like complete_pull_request or update_pull_request. It also doesn't mention prerequisites (e.g., the PR must be in a certain state) or when auto-complete is appropriate. The only hint is the phrase 'policy-respecting', which implies a distinction from bypassing policies, but no explicit when/when-not guidance is given.

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