Skip to main content
Glama

refresh_or_sync_pr

Destructive

Refresh a pull request's queue state or sync its branch with the base branch to diagnose and resolve blocked or outdated PRs.

Instructions

refresh: re-evaluate a PR's queue state. sync: update the PR branch with its base branch.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "number": "<number>",
      "action": "<action>"
    },
    "name": "refresh_or_sync_pr"
  }
}

Input Schema

NameRequiredDescriptionDefault
orgNoGitHub org. Optional if repo is 'org/name'.
repoNoGitHub repo name or 'org/name'.
actionYes
numberYesPull request number.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

B3.1/5.0
Behavior2/5

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

Annotations already disclose destructiveHint=true, readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the description needs to add the 'what gets changed/destroyed' context and does not. It never says whether sync rewrites history, force-updates, or conflicts with local commits, nor whether refresh has side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight, parallel clauses with the action keyword front-loaded, so the agent can parse it at a glance. The terseness is efficient, though it leaves the definition thin overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a destructive, non-idempotent mutation tool with no output schema and no description of what either action returns or changes. For a write operation with a destructive hint, the agent cannot tell what happens to PR branch commits or queue history from the definition alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The action enum has no per-value description in the schema, so the description does add the mapping of refresh vs. sync that the schema alone lacks. However, it adds nothing for org, repo, or number, which the schema already documents, leaving a modest lift over roughly 75% schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb for each of the two supported operations (re-evaluate queue state vs. update branch from base), which is clearer than the name alone. It does not differentiate this tool from siblings like queue_pr or dequeue_pr, which also mutate PR queue state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explaining what refresh and sync do implicitly tells the agent which mode to pick, but there is no explicit when-to-use guidance, no prerequisites (e.g., PR must already be queued), and no routing to alternatives such as get_pr_status for read-only checks.

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