Skip to main content
Glama

Initiate Handoff

initiate_handoff
DestructiveIdempotent

Begin a handoff from the agent to either a human operator (SMS/email via lead_routing_json) or another agent (signed continuation URL). In human mode the notification body is composed by the server from the contact and reason fields — callers supply those fields, not the message text. Idempotent: re-using the same idempotency_key returns the original handoff.

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": {
      "slug": "<slug>",
      "mode": "<mode>",
      "idempotency_key": "<idempotency_key>"
    },
    "name": "initiate_handoff"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeYesHandoff mode: human (SMS/email) or agent (continuation URL)
slugYesBusiness slug identifier
reasonNoWhy the user wants to reach a human
messageNoDeprecated alias for `reason`. The notification body is composed by the server from the fields above; this value is delivered as the reason line, not as the message itself. Supplying both is an error.
purposeNoPurpose description for agent-mode continuation
urgencyNoHow time-sensitive (default: normal)
agent_idNoOptional agent identifier, 1 to 128 printable ASCII characters. In agent mode it binds replays of this handoff to you, and an id outside that range is refused (invalid_agent_id); in human mode such an id is not recorded.
contact_nameNoEnd-user's name
contact_emailNoEnd-user's email
contact_phoneNoEnd-user's phone
reservation_idNoOptional link to a prior reservation
idempotency_keyYesUnique key for idempotent handoff

Output Schema

NameRequiredDescriptionDefault
modeYesThe handoff's mode, and which of the fields below are present. Normally the mode you asked for — but an idempotent replay returns the STORED handoff's mode, which differs when an idempotency_key is reused with a different mode than the call that created it.
reasonNohuman mode, not delivered: 'form_routing_configured', 'no_recipient_configured', 'sms_consent_missing', a shape-mismatch skip, a spend-cap denial, or a provider failure code
statusNohuman mode replay while the original send is still in flight: 'pending'
channelNohuman mode, skipped before sending: the channel that would have been used ('sms' or 'email'), or 'form' when the business only takes leads through a web form
form_urlNohuman mode, channel 'form': the business's own contact form for the user to complete
deliveredNohuman mode: present only as false, when nothing was sent — see reason
ticket_idNohuman mode, delivered: the provider's message id, or the handoff_id when the provider issues none
expires_atNoagent mode: Unix seconds when continuation_url stops working (one hour)
handoff_idYes
delivered_viaNohuman mode: 'sms' or 'email' — the channel the notification went to
handshake_tokenNoagent mode: the bare token carried inside continuation_url
continuation_urlNoagent mode: signed URL the next agent redeems exactly once at /a2a/continue
idempotent_replayNoPresent and true when this idempotency_key already had a handoff; nothing was re-sent and no token was re-minted
continuation_expiredNoagent mode replay: true when the stored continuation has already expired; it is never re-minted — start a new handoff

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / agent_id / description
      Previous value: -"Optional agent identifier"New value: +"Optional agent identifier, 1 to 128 printable ASCII characters. In agent mode it binds replays of this handoff to you, and an id outside that range is refused (invalid_agent_id); in human mode such an id is not recorded."
  2. Changed11 schema fields changed
    • changedInput schema / properties / contact_email / pattern
      Previous value: -"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"New value: +"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    • removedOutput schema / properties / channel / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / channel / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / delivered_via / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / delivered_via / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / form_url / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / form_url / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / reason / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / reason / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / ticket_id / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / ticket_id / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": false,
      +  "properties": {
      +    "channel": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "human mode, skipped before sending: the channel that would have been used ('sms' or 'email'), or 'form' when the business only takes leads through a web form"
      +    },
      +    "continuation_expired": {
      +      "description": "agent mode replay: true when the stored continuation has already expired; it is never re-minted — start a new handoff",
      +      "type": "boolean"
      +    },
      +    "continuation_url": {
      +      "description": "agent mode: signed URL the next agent redeems exactly once at /a2a/continue",
      +      "type": "string"
      +    },
      +    "delivered": {
      +      "description": "human mode: present only as false, when nothing was sent — see reason",
      +      "type": "boolean"
      +    },
      +    "delivered_via": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "human mode: 'sms' or 'email' — the channel the notification went to"
      +    },
      +    "expires_at": {
      +      "description": "agent mode: Unix seconds when continuation_url stops working (one hour)",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "form_url": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "human mode, channel 'form': the business's own contact form for the user to complete"
      +    },
      +    "handoff_id": {
      +      "format": "uuid",
      +      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
      +      "type": "string"
      +    },
      +    "handshake_token": {
      +      "description": "agent mode: the bare token carried inside continuation_url",
      +      "type": "string"
      +    },
      +    "idempotent_replay": {
      +      "description": "Present and true when this idempotency_key already had a handoff; nothing was re-sent and no token was re-minted",
      +      "type": "boolean"
      +    },
      +    "mode": {
      +      "description": "The handoff's mode, and which of the fields below are present. Normally the mode you asked for — but an idempotent replay returns the STORED handoff's mode, which differs when an idempotency_key is reused with a different mode than the call that created it.",
      +      "enum": [
      +        "human",
      +        "agent"
      +      ],
      +      "type": "string"
      +    },
      +    "reason": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "human mode, not delivered: 'form_routing_configured', 'no_recipient_configured', 'sms_consent_missing', a shape-mismatch skip, a spend-cap denial, or a provider failure code"
      +    },
      +    "status": {
      +      "description": "human mode replay while the original send is still in flight: 'pending'",
      +      "type": "string"
      +    },
      +    "ticket_id": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "description": "human mode, delivered: the provider's message id, or the handoff_id when the provider issues none"
      +    }
      +  },
      +  "required": [
      +    "mode",
      +    "handoff_id"
      +  ],
      +  "type": "object"
      +}
  4. Changed7 schema fields changed
    • addedInput schema / properties / contact_email
      Added value: +{
      +  "description": "End-user's email",
      +  "format": "email",
      +  "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
      +  "type": "string"
      +}
    • addedInput schema / properties / contact_name
      Added value: +{
      +  "description": "End-user's name",
      +  "maxLength": 120,
      +  "type": "string"
      +}
    • addedInput schema / properties / contact_phone
      Added value: +{
      +  "description": "End-user's phone",
      +  "maxLength": 40,
      +  "type": "string"
      +}
    • changedInput schema / properties / message / description
      Previous value: -"Message body for human-mode notification"New value: +"Deprecated alias for `reason`. The notification body is composed by the server from the fields above; this value is delivered as the reason line, not as the message itself. Supplying both is an error."
    • addedInput schema / properties / message / maxLength
      Added value: +800
    • addedInput schema / properties / reason
      Added value: +{
      +  "description": "Why the user wants to reach a human",
      +  "maxLength": 800,
      +  "type": "string"
      +}
    • addedInput schema / properties / urgency
      Added value: +{
      +  "description": "How time-sensitive (default: normal)",
      +  "enum": [
      +    "low",
      +    "normal",
      +    "high",
      +    "emergency"
      +  ],
      +  "type": "string"
      +}
  5. Changed10 schema fields changed
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / agent_id
      Added value: +{
      +  "description": "Optional agent identifier",
      +  "type": "string"
      +}
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "Unique key for idempotent handoff",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / message
      Added value: +{
      +  "description": "Message body for human-mode notification",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / mode / description
      Added value: +"Handoff mode: human (SMS/email) or agent (continuation URL)"
    • removedInput schema / properties / payload
      Removed value: -{
      -  "additionalProperties": {},
      -  "type": "object"
      -}
    • addedInput schema / properties / purpose
      Added value: +{
      +  "description": "Purpose description for agent-mode continuation",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / reservation_id / description
      Added value: +"Optional link to a prior reservation"
    • addedInput schema / properties / slug / description
      Added value: +"Business slug identifier"
    • changedInput schema / required
      Previous value: -[
      -  "slug",
      -  "mode",
      -  "payload"
      -]New value: +[
      +  "slug",
      +  "mode",
      +  "idempotency_key"
      +]
  6. Changed10 schema fields changed
    • addedInput schema / additionalProperties
      Added value: +false
    • removedInput schema / properties / agent_id
      Removed value: -{
      -  "description": "Optional agent identifier",
      -  "type": "string"
      -}
    • removedInput schema / properties / idempotency_key
      Removed value: -{
      -  "description": "Unique key for idempotent handoff",
      -  "minLength": 1,
      -  "type": "string"
      -}
    • removedInput schema / properties / message
      Removed value: -{
      -  "description": "Message body for human-mode notification",
      -  "minLength": 1,
      -  "type": "string"
      -}
    • removedInput schema / properties / mode / description
      Removed value: -"Handoff mode: human (SMS/email) or agent (continuation URL)"
    • addedInput schema / properties / payload
      Added value: +{
      +  "additionalProperties": {},
      +  "type": "object"
      +}
    • removedInput schema / properties / purpose
      Removed value: -{
      -  "description": "Purpose description for agent-mode continuation",
      -  "minLength": 1,
      -  "type": "string"
      -}
    • removedInput schema / properties / reservation_id / description
      Removed value: -"Optional link to a prior reservation"
    • removedInput schema / properties / slug / description
      Removed value: -"Business slug identifier"
    • changedInput schema / required
      Previous value: -[
      -  "slug",
      -  "mode",
      -  "idempotency_key"
      -]New value: +[
      +  "slug",
      +  "mode",
      +  "payload"
      +]
  7. Changed10 schema fields changed
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / agent_id
      Added value: +{
      +  "description": "Optional agent identifier",
      +  "type": "string"
      +}
    • addedInput schema / properties / idempotency_key
      Added value: +{
      +  "description": "Unique key for idempotent handoff",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / message
      Added value: +{
      +  "description": "Message body for human-mode notification",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / mode / description
      Added value: +"Handoff mode: human (SMS/email) or agent (continuation URL)"
    • removedInput schema / properties / payload
      Removed value: -{
      -  "additionalProperties": {},
      -  "type": "object"
      -}
    • addedInput schema / properties / purpose
      Added value: +{
      +  "description": "Purpose description for agent-mode continuation",
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / reservation_id / description
      Added value: +"Optional link to a prior reservation"
    • addedInput schema / properties / slug / description
      Added value: +"Business slug identifier"
    • changedInput schema / required
      Previous value: -[
      -  "slug",
      -  "mode",
      -  "payload"
      -]New value: +[
      +  "slug",
      +  "mode",
      +  "idempotency_key"
      +]
  8. First observed

TDQS

A3.9/5.0
Behavior3/5

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

The annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine context the annotations do not: that the server composes the notification body from contact and reason, and that replaying the same idempotency_key returns the original handoff rather than creating a duplicate. It does not explain what the destructive flag means in practice (e.g. whether an outbound SMS/email is irrevocably sent, or any rate limits), leaving the highest-risk aspect unaddressed.

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?

Three sentences, each doing distinct work: mode selection, the caller's field contract, and idempotency. The most decision-relevant fact (which modes exist) is front-loaded and there is no redundant framing.

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 12-parameter, mutating, externally-visible tool with an output schema and full annotation coverage, the description covers the essential decision points: which mode, what the caller must supply, and replay behavior. Gaps remain around when to prefer a sibling tool and around the consequences of the destructive flag, but the schema and output schema carry the remaining field-level detail.

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 100%, so a baseline of 3 is the floor. The description earns above that by explaining how the fields are consumed rather than what they are: contact and reason are inputs to a server-composed body, and the caller must not supply message text. That clarifies the reason/message relationship in a way the schema's field-level notes only partially do.

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 opens with a specific verb and resource ('Begin a handoff from the agent') and splits the resource into two concrete modes (human via SMS/email, agent via signed continuation URL). This is far more than a restatement of the name. It stops short of a 5 because it never distinguishes itself from siblings such as request_callback or get_payment_handoff_url, which an agent could plausibly confuse with this one.

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?

It gives clear situational context: use human mode to reach an operator, agent mode to hand off to another agent, and it spells out the caller contract for human mode (supply contact and reason, not message text). What is missing is any exclusion or alternative routing — nothing says when to prefer this over request_callback or how to resume via get_payment_handoff_url.

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.

Resources