Skip to main content
Glama

Invoke Human Tool

Send a handoff

send_handoff
Destructive

Create 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

NameRequiredDescriptionDefault
dueNoYYYY-MM-DD or an ISO timestamp.
htmlNoHTML body for type html. Scripts are removed. Named inputs become answer fields.
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
typeNoDefaults 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.
titleYes
fieldsNoStructured controls for type html.
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.
promptNoQuestion or request when not sending markdown or problems. For type html, this becomes a required text field.
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.
routingNoowner: 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.
documentNoGroup default is shared for a structured handoff. Pencil and HTML are stored as ballot with document_fallback unstructured.
markdownNo
problemsNo
questionNo
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. Each entry targets user_id, email, handle, group, team, or group_id. They must accept before they can read it.
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.
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.6/5.0
Behavior4/5

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

Annotations already declare destructiveHint, idempotentHint=false, and openWorldHint, and the description reinforces this with 'cannot be silently undone' and 'sending again creates a second handoff.' It also adds genuine extra context: the recipient fills on an Apple device, the result is a filled PDF, and the call does not block. It omits auth/permission requirements and full result semantics, but adds real value beyond the annotations.

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

Conciseness4/5

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

The description is short, front-loaded with the core action, and each sentence contributes: creation type, device context, outcome, irreversibility, non-blocking behavior, duplicate-send warning, and source guidance. Minor ordering could be tighter, but there is no padding.

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 24-parameter, nested-object creation tool with group, policy, routing, and mode semantics, the description is quite thin. The rich input schema compensates for most parameter detail, but the description does not explain major behavioral areas like group creation, policy completion rules, or the html/ui type variants, and there is no output schema to cover return values.

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

Parameters3/5

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

Schema description coverage is 75% across 24 parameters, so the schema carries most parameter meaning. The description adds only one concrete parameter pointer ('Pass source so the device can show which session sent it'), which is useful but minimal. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

The description states a specific verb ('Create') and resource ('one worksheet, form, approval, review, or sketch') and explains the overall workflow (Apple-device fill, PDF later). It does not distinguish this tool from close siblings such as send_html_handoff, send_ui_handoff, or delegate_handoff, so an agent cannot tell from the description alone which variant to pick.

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?

It gives implied usage context ('It does not wait' and the warning that re-sending creates a second handoff), which helps the agent treat this as a fire-and-forget create. However, it names no alternatives and gives no explicit when-to-use vs when-not-to-use guidance against delegate_handoff, share_handoff, or the HTML/UI variants.

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.