Skip to main content
Glama

ddflow_merge

Land an item's branch without ever switching a checkout's branch. With [flow].integration = 'pr' it pushes and opens (or updates) a pull request instead, releases your lease and parks the item in REVIEW — take the next item…

Instructions

Land an item's branch without ever switching a checkout's branch. With [flow].integration = 'pr' it pushes and opens (or updates) a pull request instead, releases your lease and parks the item in REVIEW — take the next item; ddflow_pr_sync completes it once a person merges it.

Input Schema

NameRequiredDescriptionDefault
idYesItem id.
keepNoKeep the worktree after merging, for inspection.
modelNoThe AUTHOR's model. In PR mode the item completes at `ddflow_pr_sync`, which needs it for reviewer independence.
queueNoEnqueue (ddflow_queue add) instead of landing.
branchNono_worktree items: the branch to land (default: the one checked out where this runs). Changes outside the item's globs come back as outside_globs.
messageNoMerge commit message.
as_agentNoSubagent name, this call only.
allow_dirtyNoMerge although the worktree is dirty; uncommitted changes are NOT included. Only once you know it is build output.
allow_emptyNoLand a branch with no commits ahead of its target (refused by default: usually the wrong tree; rebind with ddflow_update worktree).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed6 schema fields changedv0.2.7
    • changedInput schema / properties / allow_dirty / description
      Previous value: -"Merge although the worktree has uncommitted changes; they are NOT included. Pass it only once you have looked at what is dirty and decided it is build output."New value: +"Merge although the worktree is dirty; uncommitted changes are NOT included. Only once you know it is build output."
    • changedInput schema / properties / allow_empty / description
      Previous value: -"Land a branch with no commits ahead of its target. Refused by default: usually the item is bound to the wrong tree (rebind with ddflow_update worktree)."New value: +"Land a branch with no commits ahead of its target (refused by default: usually the wrong tree; rebind with ddflow_update worktree)."
    • changedInput schema / properties / as_agent / description
      Previous value: -"A subagent's own name, this call only."New value: +"Subagent name, this call only."
    • changedInput schema / properties / branch / description
      Previous value: -"For an item claimed with no_worktree: the branch to land (default: the branch checked out where this connection runs). Changes outside the item's globs come back as outside_globs."New value: +"no_worktree items: the branch to land (default: the one checked out where this runs). Changes outside the item's globs come back as outside_globs."
    • changedInput schema / properties / model / description
      Previous value: -"The AUTHOR's model. In PR mode the item completes later, at `ddflow_pr_sync`, and the reviewer-independence check needs it then."New value: +"The AUTHOR's model. In PR mode the item completes at `ddflow_pr_sync`, which needs it for reviewer independence."
    • addedInput schema / properties / queue
      Added value: +{
      +  "description": "Enqueue (ddflow_queue add) instead of landing.",
      +  "type": "boolean"
      +}
  2. Changed4 schema fields changedv0.1.12
    • changedInput schema / properties / allow_dirty / description
      Previous value: -"Merge although the worktree has uncommitted changes. They are NOT included — that is the point of the refusal. Only pass this once you have looked at what is dirty and decided it is build output."New value: +"Merge although the worktree has uncommitted changes; they are NOT included. Pass it only once you have looked at what is dirty and decided it is build output."
    • changedInput schema / properties / allow_empty / description
      Previous value: -"Land a branch with no commits ahead of its target. Refused by default: it would record the item merged with nothing landed -- usually the item is bound to the wrong tree (rebind with ddflow_update worktree)."New value: +"Land a branch with no commits ahead of its target. Refused by default: usually the item is bound to the wrong tree (rebind with ddflow_update worktree)."
    • changedInput schema / properties / as_agent / description
      Previous value: -"Subagent sharing the parent's connection: your own stable name, for this call only (see ddflow_identify)."New value: +"A subagent's own name, this call only."
    • changedInput schema / properties / branch / description
      Previous value: -"For an item claimed with no_worktree: the branch to land. Default: the branch checked out in the worktree this connection runs in. Paths the landing changes outside the item's globs come back as outside_globs."New value: +"For an item claimed with no_worktree: the branch to land (default: the branch checked out where this connection runs). Changes outside the item's globs come back as outside_globs."
  3. Changed4 schema fields changedv0.1.10
    • addedInput schema / properties / allow_empty
      Added value: +{
      +  "description": "Land a branch with no commits ahead of its target. Refused by default: it would record the item merged with nothing landed -- usually the item is bound to the wrong tree (rebind with ddflow_update worktree).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / as_agent
      Added value: +{
      +  "description": "Subagent sharing the parent's connection: your own stable name, for this call only (see ddflow_identify).",
      +  "type": "string"
      +}
    • addedInput schema / properties / branch
      Added value: +{
      +  "description": "For an item claimed with no_worktree: the branch to land. Default: the branch checked out in the worktree this connection runs in. Paths the landing changes outside the item's globs come back as outside_globs.",
      +  "type": "string"
      +}
    • addedInput schema / properties / model
      Added value: +{
      +  "description": "The AUTHOR's model. In PR mode the item completes later, at `ddflow_pr_sync`, and the reviewer-independence check needs it then.",
      +  "type": "string"
      +}
  4. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

With no annotations to lean on, the description carries the full burden and does substantial work: it discloses side effects (lease release, item parked in REVIEW), that uncommitted changes are NOT included with allow_dirty, that empty branches are refused by default with a rebind pointer, and that out-of-glob changes surface as outside_globs. It omits error/conflict behavior and confirmation of return values, keeping it short of a 5.

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 sentences, front-loaded with the core differentiator (no branch switching) followed by the conditional PR path. Dense but every clause carries information; the bracketed config reference and backticked tool names slightly raise parsing cost.

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

Completeness4/5

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

For a 9-parameter mutation tool with no annotations and no output schema, the description covers safety-relevant behavior (dirty worktrees, empty branches, lease handling, PR-mode state transition). What's missing is failure/conflict handling and what the call returns, a modest gap given the schema already enumerates the options.

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?

Schema description coverage is 100%, so every one of the 9 parameters is already documented in the schema, making 3 the baseline. The description adds only framing context (mode selection, the PR-mode handoff requiring the author's model) rather than new per-parameter semantics.

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?

States a specific verb and resource ('Land an item's branch') plus a differentiating constraint ('without ever switching a checkout's branch'), and names the PR-mode variant that hands off to ddflow_pr_sync. It is clearly distinct from sibling tools like ddflow_complete or ddflow_pr_sync, though 'land' is domain jargon that isn't defined inline.

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

Usage Guidelines4/5

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

Explicitly branches usage on [flow].integration: direct merge vs. PR mode that releases the lease and parks the item in REVIEW, and points to ddflow_pr_sync as the completion path. The queue parameter description also names ddflow_queue add as the alternative action. No exclusions for when NOT to merge are given, but the mode routing is strong.

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