publish_merge_request

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

No annotations are provided, so the description carries the full burden. It discloses that the platform is auto-detected from the git remote and that auth tokens come from specific env vars, which is useful behavioral context. However, it doesn't disclose side effects (opening a PR is externally visible/mutating), error behavior when tokens are missing, or what happens when base differs from current branch.

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 three sentences, each earning its place: what it does, how platform detection works, and auth requirements. It's front-loaded with the primary purpose. No redundant text.

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 tool with 5 parameters, full schema coverage, and no output schema, the description covers the essentials reasonably well. However, it lacks guidance on behavior when auth fails, what the function returns (PR/MR URL?), and how the base default is determined, which could trip up an agent. The prepare_merge_request sibling suggests a pairing workflow that isn't explicitly connected.

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 100%, so the structured schema already documents all 5 parameters (cwd, base, body, draft, title). The description adds the context that title and body are the content being published, but doesn't add format/content guidance beyond what the schema provides. Baseline 3 is appropriate given full schema coverage.

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 clearly states the action (publish a PR/MR), the resource (title and body), and distinguishes between GitHub and GitLab terminology. It doesn't explicitly contrast with sibling tools like prepare_merge_request, but the verb 'publish' versus 'prepare' offers implicit differentiation. The platform auto-detection detail adds useful specificity.

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 notes that platform is auto-detected and auth tokens come from env vars, which conveys prerequisites but not explicit when-to-use or when-not-to-use guidance. It doesn't explain when to prefer this over prepare_merge_request, though 'publish' vs 'prepare' implies a workflow ordering. No explicit alternatives are named.

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