Skip to main content
Glama

Invoke Human Tool

Send a structured form

send_ui_handoff
Destructive

Create 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

NameRequiredDescriptionDefault
uiNoHUI 0.1 document: { hui: "0.1", steps or children }.
dueNoYYYY-MM-DD or an ISO timestamp.
modeNosync waits for an answer. On a Tasks client that returns a task. async returns the handoff id. Default async. mode wins over await_answer.
tagsNo
titleYes
policyNoCompletion 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.
reasonNoWhy 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.
sourceNoOptional session context stored with the handoff and shown on the iPad.
lenientNoWhen true, unknown properties are warnings and are dropped. Defaults to false, which rejects them.
routingNoSame as send_handoff. A UI answer completes the handoff.
documentNoGroup default is shared for a structured handoff. Pencil and HTML are stored as ballot with document_fallback unstructured.
markdownNoHUI 1.0 markdown. Registry fences and ih:// links. Do not send this with ui. See https://invokehumantool.com/skills/invoke-human/references/language.md.
responsesNoWho 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_agentYesName of the agent sending the handoff.
recipientsNoPeople who should receive this handoff, besides the signed-in account. Same shape as send_handoff.
assignmentsNoShared documents only. { seat, blocks }.
await_answerNoLegacy 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_urlNoPublic https URL notified when the handoff is submitted. The body includes answers, summary_text, and answered_by.
instructionsNo
default_on_timeoutNoAnswers 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / markdown / description
      Previous value: -"HUI 1.0 markdown. Registry fences and ih:// links. Do not send this with ui. See docs/handoff-language.md."New value: +"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."
  2. Changed6 schema fields changed
    • addedInput schema / properties / assignments
      Added value: +{
      +  "description": "Shared documents only. { seat, blocks }.",
      +  "type": "array"
      +}
    • addedInput schema / properties / document
      Added value: +{
      +  "description": "Group default is shared for a structured handoff. Pencil and HTML are stored as ballot with document_fallback unstructured.",
      +  "enum": [
      +    "ballot",
      +    "shared"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / policy
      Added value: +{
      +  "description": "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.",
      +  "type": "object"
      +}
    • addedInput schema / properties / reason
      Added value: +{
      +  "description": "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.",
      +  "properties": {
      +    "code": {
      +      "type": "string"
      +    },
      +    "detail": {
      +      "type": "string"
      +    },
      +    "last_state_change": {
      +      "type": "string"
      +    },
      +    "spend": {
      +      "properties": {
      +        "amount": {
      +          "type": "number"
      +        },
      +        "unit": {
      +          "enum": [
      +            "usd",
      +            "tokens"
      +          ],
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "steps_taken": {
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "code"
      +  ],
      +  "type": "object"
      +}
    • changedInput schema / properties / responses / description
      Previous value: -"Who sees answers when routing is all. private, the default, shows each person only their own. shared shows every response live, attributed by name."New value: +"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."
    • changedInput schema / properties / responses / enum
      Previous value: -[
      -  "private",
      -  "shared"
      -]New value: +[
      +  "private",
      +  "shared",
      +  "revealed"
      +]
  3. Changed1 schema field changed
    • changedInput schema / properties / markdown / description
      Previous value: -"HUI 1.0 markdown. Registry fences and ih:// links. Do not send this with ui."New value: +"HUI 1.0 markdown. Registry fences and ih:// links. Do not send this with ui. See docs/handoff-language.md."
  4. Changed6 schema fields changed
    • changedInput schema / properties / await_answer / description
      Previous value: -"Set true to wait for the human's answer. When this client declares the MCP Tasks extension, the call returns a task and the client delivers the same JSON as get_handoff_result once they submit. Omit it, or pass false, to get the handoff id immediately and keep working. Clients that do not declare Tasks ignore this flag and return the handoff id, same as today."New value: +"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."
    • addedInput schema / properties / default_on_timeout
      Added value: +{
      +  "description": "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.",
      +  "type": "object"
      +}
    • addedInput schema / properties / markdown
      Added value: +{
      +  "description": "HUI 1.0 markdown. Registry fences and ih:// links. Do not send this with ui.",
      +  "type": "string"
      +}
    • addedInput schema / properties / mode
      Added value: +{
      +  "description": "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.",
      +  "enum": [
      +    "sync",
      +    "async"
      +  ],
      +  "type": "string"
      +}
    • addedInput schema / properties / responses
      Added value: +{
      +  "description": "Who sees answers when routing is all. private, the default, shows each person only their own. shared shows every response live, attributed by name.",
      +  "enum": [
      +    "private",
      +    "shared"
      +  ],
      +  "type": "string"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "title",
      -  "from_agent",
      -  "ui"
      -]New value: +[
      +  "title",
      +  "from_agent"
      +]
  5. Changed1 schema field changed
    • addedInput schema / properties / await_answer
      Added value: +{
      +  "description": "Set true to wait for the human's answer. When this client declares the MCP Tasks extension, the call returns a task and the client delivers the same JSON as get_handoff_result once they submit. Omit it, or pass false, to get the handoff id immediately and keep working. Clients that do not declare Tasks ignore this flag and return the handoff id, same as today.",
      +  "type": "boolean"
      +}
  6. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the annotations, the description discloses the important consequences: the send "cannot be silently undone," re-sending forks a second handoff, an agent key does not receive `answer_url`, and the return payload is answers keyed by field id plus `summary_text`. That is exactly the behavioral context an agent needs before attempting an irreversible send, and it is consistent with destructiveHint=true and idempotentHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is dense and useful, but it is delivered as one undifferentiated prose block, and "No HTML, CSS, or JavaScript" appears twice word-for-word. "Call validate_ui first" is also immediately softened to "call validate_ui before send_ui_handoff when you are unsure," which is redundant and slightly undermines the earlier instruction.

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 20-parameter, nested-schema, no-output-schema tool, the description covers the essential gaps: return shape, irreversibility, prerequisite validation, format constraints, and the two mutually exclusive body modes. It stops short of explaining recipients/assignment semantics for group sends or timeout defaults, but the schema descriptions carry most of that burden.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 85%, so the baseline is 3, but the description adds real meaning the schema lacks: the enumerated `kinds`, the id pattern `^[a-z][a-z0-9_]{0,40}$` for inputs, the `visibleIf`/`requiredIf` operator set, `options` binding to `{"$bind":"/pointer"}`, tone values, and the six-step cap. It does not compensate for the remaining uncovered parameters (`title`, `instructions`, `tags`) but the added specificity is substantive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Create one HUI 0.1 form or one HUI 1.0 markdown handoff" names the specific verb and the two artifacts it produces, and the two formats map directly onto the `ui` and `markdown` parameters. It also frames the delivery channel (the person answers via native controls or a signed link), which distinguishes it from the sibling `send_html_handoff` and `send_handoff` free-form variants.

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?

Explicit prerequisites are given: "Call validate_ui first" and "Call list_blocks for the live catalog," plus an exclusion ("Do not send this with ui"). What's missing is explicit routing between this tool and `send_handoff`/`send_html_handoff` — the description only says routing semantics are "Same as send_handoff" rather than stating when to pick which sender.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.