Skip to main content
Glama

Invoke Human Tool

Send a tap-or-type form

send_html_handoff
Destructive

Create one HTML handoff the person answers by tapping or typing, on an Apple device or in a browser. Pass html, fields, or both. Scripts are removed. fields are text, choice, checkbox, rating, approval, or file. The result is JSON answers, not handwriting. 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_html_handoff"
  }
}

Input Schema

NameRequiredDescriptionDefault
dueNoYYYY-MM-DD or an ISO timestamp.
htmlNoHTML body. Script, iframes, and event handlers are removed. Inputs with a name are returned as answers.
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
fieldsNo
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.
promptNoAdds a required text field named response when you do not define that field yourself.
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.
routingNoSame as send_handoff. routing all waits until every answerer submits. The signed link is not a vote for routing all.
documentNoGroup default is shared for a structured handoff. Pencil and HTML are stored as ballot with document_fallback unstructured.
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 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. 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"
      +]
  2. Changed4 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 / 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"
      +}
  3. 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"
      +}
  4. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Goes beyond the annotations (destructiveHint=true, openWorldHint=true) with concrete consequences: 'cannot be silently undone,' 'Sending again creates a second handoff,' and 'An agent key does not receive answer_url' — that last point is a real access caveat an agent would otherwise miss. It also clarifies the return is 'JSON answers, not handwriting,' which disambiguates against the ink-based sibling.

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

Conciseness5/5

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

Short, front-loaded sentences with no filler; the core action, input options, sanitization rule, return shape, and irreversibility caveat each get one sentence. Nothing is repeated from structured fields verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 20-parameter tool with nested objects and no output schema, the description covers recipient-facing behavior but says nothing about what the call returns in the normal case (handoff id, answer_url, delivery channel) or about recipients/permission semantics. The rich schema and annotations carry most of the load, so this is adequate but not complete.

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 80%, so baseline is 3, but the description adds meaning the schema doesn't: neither html nor fields is required, yet 'Pass html, fields, or both' tells the agent at least one must be supplied, and the field-type enumeration is surfaced up front. It does not explain the mode/await_answer interplay or policy phases, leaving those to the schema.

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

Purpose4/5

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

States a specific verb and resource — 'Create one HTML handoff' — plus what the recipient does with it ('answers by tapping or typing') and where it runs (Apple device or browser). It does not distinguish itself from the close siblings send_handoff and send_ui_handoff, which an agent must disambiguate on its own.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Pass html, fields, or both' implies the two authoring modes, and 'Scripts are removed' sets a boundary on content. But there is no explicit statement of when to choose this over send_ui_handoff or send_handoff, and no exclusions — usage is inferable rather than stated.

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.