create_pull_request

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

With no annotations, the description must bear the full burden of behavioral disclosure. It mentions it is a write operation ('Create') and describes the return format, but lacks context on what happens on errors, whether the PR is immediately visible, or any side effects like triggering CI. This is a significant gap for a mutation tool.

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 concise and well-structured: it starts with a clear one-liner purpose, then lists parameters, returns, and an example. It front-loads the essential info and avoids unnecessary prose. The example is compact and illustrative.

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?

Despite having an output schema, the description provides some return context ('Normalized write-result mapping with identifier, state, and URL fields') and an example. However, it doesn't explain how the required provider and repo parameters are resolved (e.g., aliases, defaults), or any validation rules. For a tool with 7 parameters and no enum hints, more contextual guidance would improve completeness.

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 0%, so the description must compensate. It lists each parameter with a brief role (e.g., 'Source branch name'), but doesn't add additional meaning like allowed values for provider, repo format, or constraints like 'provider must be one of...' The description makes the parameters understandable but leaves room for deeper semantics.

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 ('Create'), resource ('pull request from one branch into another'), and the key parameters (source_branch, target_branch). It clearly distinguishes this from sibling tools like 'update_pull_request' or 'merge_pull_request' by specifying it creates a new PR.

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 explains the tool's function but does not provide explicit guidance on when to use it versus alternatives. It doesn't mention prerequisites like branch existence or permissions, and doesn't contrast with 'update_pull_request' or 'close_pull_request'.

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