Create a GitHub pull request

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

Annotations only declare the safety/idempotency profile; the description adds substantial behavior beyond them: exhaustive pre-flight checks before creation, guaranteed return even on later failures with an errors map keyed by step (create, attachments, metadata, read, head_sha, project, fields.<Name>), the wait for GitHub's closing-issue link, fork unsupported, and gh 2.99 requirement for attachments. This is far more than the annotations provide and directly affects how an agent should parse results.

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 purpose is front-loaded well in the first clause, and nearly every sentence carries operational detail. However, it is delivered as a single dense run-on block covering creation, failure handling, issue linking, board resolution, field typing, auth, and attachments with no grouping, which makes it hard for an agent to locate the relevant rule.

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 15-parameter, nested-object mutation tool, the description covers failure semantics, auth scoping, precondition checks, defaulting rules, and attachment constraints; an output schema exists so return-shape explanation is rightly omitted. Nothing an agent needs to invoke this correctly appears to be missing.

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 real semantics not in the schema: project resolution order (owner boards, then repo-linked, then org, then viewer; never guessed), case-insensitive field matching, date format YYYY-MM-DD, iteration @current as the UTC iteration containing today, and which field types are settable. That goes meaningfully beyond the schema's terse field descriptions.

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 ('Open a pull request from a pushed branch... into another branch') and immediately enumerates scope (draft, labels, assignees, reviewers, milestone, closes, project board). Combined with the sibling list (github_pr_read, github_pr_edit, github_pr_merge, etc.), an agent can tell this is the create operation without opening the schema.

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?

Gives explicit context for when to use this versus alternatives: 'a column that mirrors an issue field is set with the issue tools' issue_fields, not here' and 'GitHub's own (...) are set on the issue, and github_issue_edit sets assignees, labels and milestone'. It also names the prerequisite (token with project scope, gh auth refresh -s project) and the fork exclusion. The routing to siblings is slightly muddled across references, keeping it below a 5.

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