mcp: restore operational guidance dropped in #723

#723's revision pass cut four substantive strings along with the
negative anchors. those strings address real, audit-observed failure
modes and the positive examples don't carry them.

restored:
- push_branch: "if the response reports a timeout, the underlying
  push may have actually succeeded — verify with git log
  origin/<branch> before retrying" (was on the tool description)
- create_pull_request_review commit_id .describe(): "must be the FULL
  40-character SHA — abbreviated SHAs are rejected by GitHub with 422"
- create_pull_request_review comments[].line .describe(): "must sit
  inside a `@@` hunk... dropped entries are reported under
  droppedComments in the response"
- create_pull_request_review comments[].start_line .describe(): "both
  start_line and line must sit inside the same @@ hunk"

also: get_commit_info example used a 31-character SHA (non-standard
truncation). swapped to a 7-char short form, which is what git
log --oneline emits and what agents see in practice. note that this
tool accepts either full or abbreviated, unlike create_pull_request_review
which requires full.
This commit is contained in:
Colin McDonnell
2026-05-13 22:49:06 +00:00
committed by pullfrog[bot]
parent b8ac42e875
commit b9f0938405
3 changed files with 8 additions and 5 deletions
+2 -1
View File
@@ -222,7 +222,8 @@ export function PushBranchTool(ctx: ToolContext) {
"If specifying branchName, use the LOCAL branch name (e.g., 'pr-1'), not the remote branch name. " +
"The correct remote and remote branch are determined automatically from branch config set by checkout_pr. " +
"Requires a clean working tree. Runs the repository prepush hook (if configured) before the network push — hook failure means tests/lint or similar in that script failed, not necessarily a Pullfrog timeout. " +
"Never force push unless explicitly requested. Pushes to the default branch are blocked in restricted mode.",
"Never force push unless explicitly requested. Pushes to the default branch are blocked in restricted mode. " +
"If the response reports a timeout, the underlying push may have actually succeeded — verify with `git log origin/<branch>` (or this tool with command 'log') before retrying, otherwise you'll push a duplicate.",
parameters: PushBranch,
execute: execute(async ({ branchName, force }) => {
// permission check