# land_group > Release: 0.11.0 · Last changed: 2026-11-09 · Source: https://github.com/KeiaiLab/SwarmOps/blob/stable/docs/reference/mcp-tools/land-group.md Lands changes (1 to 32, each a head with an optional base and idempotency\_key) in order onto target, main by default, as one operation: each merged onto what the clean ones before it make, as land\_check plans them, the clean ones a chain of landed changesets with one move of target. A conflicting change is reported (items\[\].report) and passed over; with none clean it is E\_NOTHING\_TO\_LAND, each outcome in details.items. Give each change an idempotency\_key to make a retry safe. ```yaml title: "land_group" description: "Land a group." since: "0.11.0" mutates: true identity_required: true cli_command: "swarmops land-group" envelope_op: "land_group" request_type: "LandGroupReq" annotations: {"destructiveHint":false,"idempotentHint":true,"openWorldHint":false,"readOnlyHint":false} max_result_chars: null ``` ## Input schema `arguments` is a `LandGroupReq`: `swarmops schema LandGroupReq` prints the type. A field the type does not know is ignored. | Field | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `changes` | array of object | yes | | The changes, in the order they land: 1 to 32 (`E_INVALID_ARG` for none, `E_TOO_LARGE` past 32), each key once. | | `max_attempts` | integer | no | `8` | How many times the group plans and publishes at most before `E_CAS_RETRY_EXHAUSTED`: 1 to 32. | | `max_conflict_bytes` | integer | no | `32768` | The most bytes of hunk text each conflicting change's report carries, as a land's. | | `target` | string | no | `"main"` | The ref the changes land on: `main` or `release/`, which must exist. | ### JSON Schema As `tools/list` gives it: each `$ref` replaced by its definition, so that it stands alone. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "`land_group` (CLI `land-group`): lands `changes`, in order, onto `target` as one operation:\neach change merged onto what the clean ones before it make, as\n`land_check` plans them, the clean ones recorded as a chain of landed changesets, each on the\none before, with one move of `target` to the last. A conflicting change is reported and\npassed over; a replayed one, or one with nothing to land, lands nothing. A group with no\nclean change is `E_NOTHING_TO_LAND`, each change's outcome in `details.items`. A target that\nmoves after the plan makes the group plan again, up to `max_attempts`.", "properties": { "changes": { "description": "The changes, in the order they land: 1 to 32 (`E_INVALID_ARG` for none, `E_TOO_LARGE`\npast 32), each key once.", "items": { "description": "One change of a `land_check`: as `land` takes it.", "properties": { "base": { "anyOf": [ { "description": "A revision as the caller wrote it, for the store to resolve: a ref name (`main`,\n`release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits, or a\nref's earlier value: `@{N}` the value it held N moves before its current one (`@{0}`\nis the current value), `@{at=}` the value set by its newest move\nrecorded at or before that instant (the writer's clock, moves read in journal order);\noptionally followed by `~N` for the N-th first-parent ancestor.", "type": "string" }, { "type": "null" } ], "description": "Where the change starts, as a land's `base`. When omitted, the merge base of `head` and\nthe target's head, along first parents." }, "head": { "description": "The change's head. A revision as the caller wrote it, for the store to resolve: a ref name (`main`,\n`release/1.2`), a full 64-hex changeset id or a unique prefix of at least 12 hex digits, or a\nref's earlier value: `@{N}` the value it held N moves before its current one (`@{0}`\nis the current value), `@{at=}` the value set by its newest move\nrecorded at or before that instant (the writer's clock, moves read in journal order);\noptionally followed by `~N` for the N-th first-parent ancestor.", "type": "string" }, "idempotency_key": { "description": "The change's land key, as a land's: one the target holds a land of is `replayed`.", "type": [ "string", "null" ] }, "message": { "description": "The landed changeset's message, as a land's; a check does not use it.", "type": [ "string", "null" ] } }, "required": [ "head" ], "type": "object" }, "type": "array" }, "max_attempts": { "default": 8, "description": "How many times the group plans and publishes at most before `E_CAS_RETRY_EXHAUSTED`:\n1 to 32.", "format": "uint32", "minimum": 0, "type": "integer" }, "max_conflict_bytes": { "default": 32768, "description": "The most bytes of hunk text each conflicting change's report carries, as a land's.", "format": "uint64", "minimum": 0, "type": "integer" }, "target": { "default": "main", "description": "The ref the changes land on: `main` or `release/`, which must exist.", "type": "string" } }, "required": [ "changes" ], "title": "LandGroupReq", "type": "object" } ``` ## Annotations It adds a changeset onto a ref's head and moves the ref to it, keeping all the ref held. Run again with the same arguments, it finds its change on the ref and adds nothing: `replayed` with an `idempotency_key`, `E_NOTHING_TO_LAND` without. | Annotation | Value | Meaning | | --- | --- | --- | | `destructiveHint` | `false` | True: a tool that changes the store may overwrite or delete what is there, not only add to it. | | `idempotentHint` | `true` | True: calling it again with the same arguments changes nothing more. | | `openWorldHint` | `false` | True: it reaches beyond a closed set of things. Every tool here stays inside the store. | | `readOnlyHint` | `false` | True: the tool does not change its environment, the store. | Its entry in `tools/list` carries no `_meta`. ## CLI command [`swarmops land-group`](../commands/land-group.md) runs the same operation and prints the same envelope. ## Examples ### MCP ```json { "id": 44, "jsonrpc": "2.0", "method": "tools/call", "params": { "arguments": { "changes": [ { "head": "[one]", "idempotency_key": "group-1" }, { "head": "[two]", "idempotency_key": "group-2" } ] }, "name": "land_group" } } ``` ```json { "id": 44, "jsonrpc": "2.0", "result": { "content": [ { "text": "{\"api\":1,\"meta\":{\"auth\":\"trust\",\"elapsed_ms\":\"[elapsed_ms]\",\"repo\":\"[tmp]/store\",\"resolved\":{\"[one]\":\"[one]\",\"[two]\":\"[two]\",\"main\":\"[reverted]\"}},\"ok\":true,\"op\":\"land_group\",\"result\":{\"attempts\":1,\"head\":\"[grouped]\",\"items\":[{\"head\":\"[one]\",\"landed\":\"[id19]\",\"outcome\":\"clean\"},{\"head\":\"[two]\",\"landed\":\"[grouped]\",\"outcome\":\"clean\"}],\"op\":17,\"rebased_onto\":\"[reverted]\",\"target\":\"main\"}}", "type": "text" } ], "isError": false, "structuredContent": { "api": 1, "meta": { "auth": "trust", "elapsed_ms": "[elapsed_ms]", "repo": "[tmp]/store", "resolved": { "[one]": "[one]", "[two]": "[two]", "main": "[reverted]" } }, "ok": true, "op": "land_group", "result": { "attempts": 1, "head": "[grouped]", "items": [ { "head": "[one]", "landed": "[id19]", "outcome": "clean" }, { "head": "[two]", "landed": "[grouped]", "outcome": "clean" } ], "op": 17, "rebased_onto": "[reverted]", "target": "main" } } } } ``` The server ran as `swarmops mcp --repo [tmp]/store --as agent/worker-17`, after `initialize`. Recorded by the MCP tests. A name in square brackets, such as `[tmp]` or `[c1]`, stands for what differs from run to run: the test's temporary directory, an id, a time, the version. ## Return information A tool result: the envelope, whose `op` is `land_group`, as `structuredContent` and again as the text of its one `content` block. `isError` is true exactly when the envelope's `ok` is false. On success the envelope's `result` is what [`swarmops land-group`](../commands/land-group.md#return-information) returns. ## Errors A failed call is a tool result with `isError: true`; the envelope's `error.code` is one of the [error codes](../errors.md). - [`E_INVALID_ARG`](../errors.md#e_invalid_arg): arguments that do not fit `LandGroupReq`, a field named twice among them included, or that break one of the server's own rules. - [`E_IDENTITY_REQUIRED`](../errors.md#e_identity_required): the server runs with no identity. - [`E_NOT_A_REPO`](../errors.md#e_not_a_repo): the server's store is not there; the server serves on. - [`E_INTERNAL`](../errors.md#e_internal): the operation panicked, a bug. Then the errors of the operation, as [`swarmops land-group`](../commands/land-group.md#errors) lists them. ## See also - [`swarmops land-group`](../commands/land-group.md) - [MCP tools](README.md) - [MCP integration](../../develop/mcp.md) - [Error codes](../errors.md)