handoff_to_teammate: Send a Structured Handoff to a Teammate

Full reference for the handoff_to_teammate MCP tool — parameters, artifact types, output fields, idempotency behavior, and natural language examples.

handoff_to_teammate is the tool your agent calls to initiate a cross-developer handoff. It packages a summary, optional structured artifacts, and an intent declaration into a single A2A message/send request, creates a new thread on the relay, and returns a thread_id you can track. The MCP server generates a UUIDv4 idempotency key before posting, so retrying on a transient error never creates a duplicate thread.

Natural language examples

“Send a handoff to frank@acme. I’ve refactored the /users endpoint — it now returns paginated responses. Attach the diff and the updated OpenAPI contract.”

“Ask carol@acme whether the new /search endpoint needs to support cursor-based pagination. Include the current implementation as a file reference.”

“Inform bob@acme that the CI pipeline now requires pnpm run typecheck before merge. No artifacts needed.”

Input parameters

to · string · required

Teammate handle in name@team format — for example, frank@acme. Must match a registered agent on the relay. Validated against the pattern ^[A-Za-z0-9._-]+@[A-Za-z0-9._-]+$.

intent · string · required

Declares the sender’s purpose for this handoff. Accepted values:

• "inform" — sharing context with no response expected
• "ask_question" — expecting a reply; pair with the question field
• "propose_action" — requesting the receiver’s agent take a concrete action (v0.1.5; requires proposed_action)

summary · string · required

A 1–2 paragraph human-readable summary of what you are handing off. This is stored as the thread’s top-level summary and shown as a preview in the receiver’s inbox. Minimum 1 character.

artifacts · Artifact[]

An optional array of structured payloads attached to the handoff. Five artifact types are supported — see Artifact types below. Defaults to an empty array if omitted.

question · string

The initial question to include when intent is "ask_question". Stored in the thread metadata alongside the summary.

proposed_action · object

Required when intent is "propose_action" (v0.1.5); must be omitted for all other intents. Describes the concrete action you are requesting the receiver’s agent take.

Show proposed_action fields

description · string · required

Human-readable summary of what the action does.

target_files · string[] · required

Paths the receiver’s agent will be expected to touch.

rationale · string · required

Why this change is needed. Wrapped with L1 provenance before the receiver’s agent sees it.

suggested_diff · string

Optional unified diff. If omitted, the receiver’s agent is expected to draft one from scratch using draft_proposed_action.

metadata · object

Freeform key-value pairs forwarded to the relay as handoffs.metadata. Useful for tagging handoffs with sprint IDs, ticket references, or other context your tooling consumes. The MCP server automatically merges in the client_idempotency_key and question fields — you do not need to add them.

Artifact types

Artifacts let you attach structured payloads beyond the plain-text summary. The type discriminator determines the shape of each artifact object.

file_diff

{
  "type": "file_diff",
  "path": "src/api/users.ts",
  "diff": "@@ -10,7 +10,12 @@\n- return users;\n+ return { items: users, next_cursor: cursor };"
}

Type	Required fields	Optional fields
file_diff	path, diff	—
file_ref	path	git_sha, lines
test_command	command	cwd
api_contract	—	schema_url, inline
link	url	title

Output fields

thread_id · string · required

The relay-assigned UUID for the new handoff thread. Use this ID in subsequent calls to view_thread, send_message, and complete_handoff.

status · string · required

Always "pending" on creation. Transitions to "accepted" when the receiver calls accept_handoff and "completed" when they call complete_handoff.

recipient · string · required

The handle of the teammate the handoff was sent to — echoed from the to input.

created_at · string · required

ISO 8601 timestamp of when the thread was created on the relay.

inbox_url · string · required

Deep link to the thread in the relay’s inbox UI. Sourced from the relay response; falls back to a path-relative URL if the relay does not return one.

Example output

{
  "thread_id": "01HXYZ4ABCDE7FGHJK8LMNPQR",
  "status": "pending",
  "recipient": "frank@acme",
  "created_at": "2026-05-01T09:14:32Z",
  "inbox_url": "https://relay.acme.dev/inbox/01HXYZ4ABCDE7FGHJK8LMNPQR"
}

Behavior and error handling

1. Input validation. The MCP server runs the input through the zod schema before touching the network. If intent is "propose_action" and proposed_action is absent, validation fails immediately with a clear error. If proposed_action is set for any other intent, validation also fails.
2. Idempotency key generation. A UUIDv4 is generated client-side and included in the relay request as metadata.client_idempotency_key. If the same tool call is retried (for example, after a transient 5xx), the relay recognizes the key and returns the original result without creating a duplicate thread.
3. Relay request. The MCP server posts a message/send JSON-RPC call to the relay with task_id: null (creates a new thread), the intent, the artifacts array, and the optional proposed_action.
4. Error propagation. On a 4xx relay error (for example, -32004 recipient_not_found or -32013 teammate_blocked), the MCP server raises an MCP tool error with the relay’s error message. The agent sees the error inline and can adjust — for example, calling list_teammates to find the correct handle.

The "propose_action" intent and the proposed_action field are v0.1.5 features. In v0.1, only "inform" and "ask_question" are accepted. Sending "propose_action" against a v0.1 relay returns -32012 invalid_intent_payload.