Send a structured form
send_ui_handoffCreate one HUI 0.1 form or one HUI 1.0 markdown handoff. The person answers with native controls or the signed link. No HTML, CSS, or JavaScript. Call validate_ui first. HUI 0.1 is a JSON document. No HTML, CSS, or JavaScript. kinds: markdown, heading, callout, text, number, choice, multichoice, approval, rating, slider, toggle, date, time, section, group, disclosure, columns. inputs need id matching ^[a-z][a-z0-9_]{0,40}$. visibleIf and requiredIf use == != < > in && || ! plus field ids, strings, numbers, true, false, null, and lists. options may be an array of {value, label} or {"$bind":"/pointer"} into data. Do not send colors, fonts, or pixel sizes. tone is default, accent, or warning. emphasis is true or false. A flat children array is allowed. steps is the other layout, at most 6. Call validate_ui before send_ui_handoff when you are unsure. HUI 1.0 markdown follows https://invokehumantool.com/skills/invoke-human/references/language.md. Call list_blocks for the live catalog. The result is answers keyed by field id, plus summary_text. This sends something to a person and cannot be silently undone. Sending again creates a second handoff. An agent key does not receive answer_url.
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_ui_handoff"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ui | No | HUI 0.1 document: { hui: "0.1", steps or children }. | |
| due | No | YYYY-MM-DD or an ISO timestamp. | |
| 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 | ||
| title | Yes | ||
| 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. | |
| 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. | |
| lenient | No | When true, unknown properties are warnings and are dropped. Defaults to false, which rejects them. | |
| routing | No | Same as send_handoff. A UI answer completes the handoff. | |
| document | No | Group default is shared for a structured handoff. Pencil and HTML are stored as ballot with document_fallback unstructured. | |
| markdown | No | HUI 1.0 markdown. Registry fences and ih:// links. Do not send this with ui. See https://invokehumantool.com/skills/invoke-human/references/language.md. | |
| 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. Same shape as send_handoff. | |
| 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. The body includes answers, summary_text, and answered_by. | |
| 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. |