Send a handoff
send_handoffCreate one worksheet, form, approval, review, or sketch for the signed-in person. They write or draw on an Apple device. You get a filled PDF later. This sends something to a person and cannot be silently undone. It does not wait, and sending again creates a second handoff. Pass source so the device can show which session sent it.
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": {
"title": "<title>",
"from_agent": "<from_agent>"
},
"name": "send_handoff"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| due | No | YYYY-MM-DD or an ISO timestamp. | |
| html | No | HTML body for type html. Scripts are removed. Named inputs become answer fields. | |
| mode | No | sync waits for an answer. On a Tasks client that returns a task. async returns the handoff id. Default async. mode wins over await_answer. | |
| tags | No | ||
| type | No | Defaults to worksheet. Use html, or send_html_handoff, for tap and type answers. Use ui, or send_ui_handoff, for a HUI 0.1 document. | |
| title | Yes | ||
| fields | No | Structured controls for type html. | |
| policy | No | Completion rule. kind is owner, any, all, quorum, or majority. ordered, claim enforcement, schedule, and on_unreachable escalate are phase 2: sending them returns 400 not_in_phase_1. on_unreachable is cancel, the default, or default. quorum needs n. An approval quorum with no accept means decision approve when that block exists. Omitting policy, document, assignments, and seat role is not a group create. | |
| prompt | No | Question or request when not sending markdown or problems. For type html, this becomes a required text field. | |
| reason | No | Why this agent is asking a human. code is one of no_progress, looping, blocked, needs_decision, low_confidence, ambiguous, step_limit, spend_limit, time_limit, missing_access, missing_tool, out_of_scope, needs_approval, unexpected_result. Do not send group. After your own step or spend threshold with no state change, send no_progress and include steps_taken, spend, and last_state_change when you have them. See docs/spec/escalation.md. | |
| source | No | Optional session context stored with the handoff and shown on the iPad. | |
| routing | No | owner: the sending account answers. first: the first recipient to submit wins. all: every answerer must submit. Defaults to first when a recipient can answer, otherwise owner. | |
| document | No | Group default is shared for a structured handoff. Pencil and HTML are stored as ballot with document_fallback unstructured. | |
| markdown | No | ||
| problems | No | ||
| question | No | ||
| responses | No | Who sees structured answers. A create that omits policy, document, assignments, and seat role stays private, and each person keeps their own answer. A group create defaults to shared, so co-recipients see structured answers live. private and revealed are opt-in. revealed shows bodies and tallies after the policy is satisfied. Submitted ink stays with the sender. | |
| from_agent | Yes | Name of the agent sending the handoff. | |
| recipients | No | People who should receive this handoff, besides the signed-in account. Each entry targets user_id, email, handle, group, team, or group_id. They must accept before they can read it. | |
| assignments | No | Shared documents only. { seat, blocks }. | |
| await_answer | No | Legacy alias for mode sync. mode wins when both are set. When this client declares the MCP Tasks extension, true returns a task and the client delivers the same JSON as get_handoff_result once they submit. Omit it to get the handoff id immediately. Clients that do not declare Tasks ignore this flag. | |
| callback_url | No | Public https URL notified when the handoff is submitted. | |
| instructions | No | ||
| default_on_timeout | No | Answers to record when due passes and the person has not tapped. The receipt says the system answered. A pay, send, delete, publish, or sign step is not defaulted. |