Advocate

Request Callback

request_callback

DestructiveIdempotent

Submit a callback request on behalf of a user. Advocate attempts a notification through the business's configured lead routing channel (SMS/email); provider acceptance is not proof the business read it. A failed or pending result can require direct follow-up or a retry. Idempotent: re-using the same idempotency_key returns the original request.

Input Schema

Name	Required	Description
`slug`	Yes	Business slug identifier
`reason`	No	Why the user wants the callback
`urgency`	No	How time-sensitive (default: normal)
`agent_id`	No	Optional agent identifier
`contact_name`	No	End-user's name
`contact_email`	No	End-user's email
`contact_phone`	No	End-user's phone
`idempotency_key`	Yes	Idempotency key
`preferred_channel`	No	Channel the user prefers (default: any)

Output Schema

Name	Required	Description
`reason`	No	Present for a known routing or provider outcome: 'form_routing_configured', 'no_recipient_configured', 'sms_consent_missing', a shape-mismatch skip, a spend-cap denial, or a provider failure code
`status`	Yes	'notified': the configured notification provider accepted the request; this does not prove the business read it. 'failed': routing was not available or the provider reported a failure — see reason. 'pending': a web-form business (see form_url), or a replay while the original send is still in flight.
`form_url`	No	Present with reason 'form_routing_configured': the business's own contact form for the user to complete, or null where the business chose form routing without supplying one
`callback_id`	Yes
`status_token`	No	Pass to get_request_status to read the business's answer. For this caller only.
`delivered_via`	Yes	'sms' or 'email' when notified; null otherwise
`acknowledgment`	Yes	Customer-facing sentence to relay; null only on a replay caught while the original send is still in flight
`idempotent_replay`	No	Present and true when this idempotency_key already had a request; nothing was re-sent

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 5, 2026

addedOutput schema / properties / status_token

Added value: +{
+  "description": "Pass to get_request_status to read the business's answer. For this caller only.",
+  "type": "string"
+}

Changed11 schema fields changedOct 24, 2026

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 / acknowledgment / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / acknowledgment / 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 / status / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

addedOutput schema / properties / status / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed2 schema fields changedSep 5, 2026

changedOutput schema / properties / reason / description

Previous value: -"Present when nothing was delivered: 'form_routing_configured', 'no_recipient_configured', 'sms_consent_missing', a shape-mismatch skip, a spend-cap denial, or a provider failure code"New value: +"Present for a known routing or provider outcome: 'form_routing_configured', 'no_recipient_configured', 'sms_consent_missing', a shape-mismatch skip, a spend-cap denial, or a provider failure code"

changedOutput schema / properties / status / description

Previous value: -"'notified': the business received the request. 'failed': nothing was delivered — see reason. 'pending': a web-form business (see form_url), or a replay caught while the original send is still in flight."New value: +"'notified': the configured notification provider accepted the request; this does not prove the business read it. 'failed': routing was not available or the provider reported a failure — see reason. 'pending': a web-form business (see form_url), or a replay while the original send is still in flight."

Changed1 schema field changedSep 4, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "acknowledgment": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Customer-facing sentence to relay; null only on a replay caught while the original send is still in flight"
+    },
+    "callback_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"
+    },
+    "delivered_via": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "'sms' or 'email' when notified; null otherwise"
+    },
+    "form_url": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Present with reason 'form_routing_configured': the business's own contact form for the user to complete, or null where the business chose form routing without supplying one"
+    },
+    "idempotent_replay": {
+      "description": "Present and true when this idempotency_key already had a request; nothing was re-sent",
+      "type": "boolean"
+    },
+    "reason": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "Present when nothing was delivered: 'form_routing_configured', 'no_recipient_configured', 'sms_consent_missing', a shape-mismatch skip, a spend-cap denial, or a provider failure code"
+    },
+    "status": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "'notified': the business received the request. 'failed': nothing was delivered — see reason. 'pending': a web-form business (see form_url), or a replay caught while the original send is still in flight."
+    }
+  },
+  "required": [
+    "callback_id",
+    "status",
+    "delivered_via",
+    "acknowledgment"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedJul 17, 2026
- addedInput schema / properties / contact_email / format
```
Added value: +"email"
```
- addedInput schema / properties / contact_email / pattern
```
Added value: +"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
```

Changed12 schema fields changedJul 16, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedInput schema / properties / agent_id / description

Previous value: -"Optional caller-asserted agent identifier; recorded for attribution"New value: +"Optional agent identifier"

removedInput schema / properties / contact

Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "email": {
-      "description": "end-user's email — at least one of email/phone required",
-      "format": "email",
-      "type": "string"
-    },
-    "name": {
-      "description": "end-user's name",
-      "maxLength": 120,
-      "type": "string"
-    },
-    "phone": {
-      "description": "end-user's phone number — at least one of email/phone required",
-      "maxLength": 40,
-      "type": "string"
-    }
-  },
-  "type": "object"
-}

addedInput schema / properties / contact_email

Added value: +{
+  "description": "End-user's email",
+  "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 / idempotency_key / description

Previous value: -"Idempotency key — same key returns the same callback_request_id without dup-creating"New value: +"Idempotency key"

changedInput schema / properties / preferred_channel / description

Previous value: -"channel the user prefers to be contacted on (default: any)"New value: +"Channel the user prefers (default: any)"

changedInput schema / properties / reason / description

Previous value: -"Why the user wants the callback — passed verbatim to the business so they can prep"New value: +"Why the user wants the callback"

changedInput schema / properties / slug / description

Previous value: -"business slug"New value: +"Business slug identifier"

changedInput schema / properties / urgency / description

Previous value: -"how time-sensitive the request is (default: normal)"New value: +"How time-sensitive (default: normal)"

changedInput schema / required

Previous value: -[
-  "slug",
-  "contact",
-  "idempotency_key"
-]New value: +[
+  "slug",
+  "idempotency_key"
+]

Changed12 schema fields changedJul 12, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

changedInput schema / properties / agent_id / description

Previous value: -"Optional agent identifier"New value: +"Optional caller-asserted agent identifier; recorded for attribution"

addedInput schema / properties / contact

Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "email": {
+      "description": "end-user's email — at least one of email/phone required",
+      "format": "email",
+      "type": "string"
+    },
+    "name": {
+      "description": "end-user's name",
+      "maxLength": 120,
+      "type": "string"
+    },
+    "phone": {
+      "description": "end-user's phone number — at least one of email/phone required",
+      "maxLength": 40,
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

removedInput schema / properties / contact_email

Removed value: -{
-  "description": "End-user's email",
-  "type": "string"
-}

removedInput schema / properties / contact_name

Removed value: -{
-  "description": "End-user's name",
-  "maxLength": 120,
-  "type": "string"
-}

removedInput schema / properties / contact_phone

Removed value: -{
-  "description": "End-user's phone",
-  "maxLength": 40,
-  "type": "string"
-}

changedInput schema / properties / idempotency_key / description

Previous value: -"Idempotency key"New value: +"Idempotency key — same key returns the same callback_request_id without dup-creating"

changedInput schema / properties / preferred_channel / description

Previous value: -"Channel the user prefers (default: any)"New value: +"channel the user prefers to be contacted on (default: any)"

changedInput schema / properties / reason / description

Previous value: -"Why the user wants the callback"New value: +"Why the user wants the callback — passed verbatim to the business so they can prep"

changedInput schema / properties / slug / description

Previous value: -"Business slug identifier"New value: +"business slug"

changedInput schema / properties / urgency / description

Previous value: -"How time-sensitive (default: normal)"New value: +"how time-sensitive the request is (default: normal)"

changedInput schema / required

Previous value: -[
-  "slug",
-  "idempotency_key"
-]New value: +[
+  "slug",
+  "contact",
+  "idempotency_key"
+]

Changed12 schema fields changedJul 12, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedInput schema / properties / agent_id / description

Previous value: -"Optional caller-asserted agent identifier; recorded for attribution"New value: +"Optional agent identifier"

removedInput schema / properties / contact

Removed value: -{
-  "additionalProperties": false,
-  "properties": {
-    "email": {
-      "description": "end-user's email — at least one of email/phone required",
-      "format": "email",
-      "type": "string"
-    },
-    "name": {
-      "description": "end-user's name",
-      "maxLength": 120,
-      "type": "string"
-    },
-    "phone": {
-      "description": "end-user's phone number — at least one of email/phone required",
-      "maxLength": 40,
-      "type": "string"
-    }
-  },
-  "type": "object"
-}

addedInput schema / properties / contact_email

Added value: +{
+  "description": "End-user's email",
+  "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 / idempotency_key / description

Previous value: -"Idempotency key — same key returns the same callback_request_id without dup-creating"New value: +"Idempotency key"

changedInput schema / properties / preferred_channel / description

Previous value: -"channel the user prefers to be contacted on (default: any)"New value: +"Channel the user prefers (default: any)"

changedInput schema / properties / reason / description

Previous value: -"Why the user wants the callback — passed verbatim to the business so they can prep"New value: +"Why the user wants the callback"

changedInput schema / properties / slug / description

Previous value: -"business slug"New value: +"Business slug identifier"

changedInput schema / properties / urgency / description

Previous value: -"how time-sensitive the request is (default: normal)"New value: +"How time-sensitive (default: normal)"

changedInput schema / required

Previous value: -[
-  "slug",
-  "contact",
-  "idempotency_key"
-]New value: +[
+  "slug",
+  "idempotency_key"
+]

First observedMay 5, 2026

TDQS

A3.5/5.0

Behavior4/5

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

Annotations already declare idempotentHint=true, openWorldHint=true and destructiveHint=true, so the bar is lower, yet the description adds real context: notification goes through the business's lead routing channel, provider acceptance does not mean the business read it, and a failed or pending result may require retry or direct follow-up. It does not address what the destructiveHint implies (e.g., that a persistent request record is created) or any permission requirements.

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?

Four compact sentences with the action front-loaded and the caveats following in a sensible order. No filler, though the failure/retry sentence could be tighter.

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?

With a full input schema, complete parameter descriptions, and an output schema, the definition covers the key unknowns an agent needs: the idempotency guarantee and the fact that a success signal does not guarantee the business acted. Missing is any mention of prerequisites or what contact information is required for a useful callback.

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 100% across all 9 parameters, so the schema already carries the parameter burden and the baseline is 3. The description does add meaning for idempotency_key ('re-using the same idempotency_key returns the original request'), which is genuine value, but it says nothing about slug, urgency, preferred_channel, or contact field expectations.

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: 'Submit a callback request on behalf of a user,' which tells an agent exactly what the tool creates. It does not explicitly distinguish itself from near-neighbors like request_service or submit_quote_request, so the sibling differentiation is left implicit.

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

Usage Guidelines2/5

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

The description explains what happens after submission (routing channel, failed/pending handling) but never says when an agent should choose this tool over request_service, submit_quote_request, or get_request_status. There is no when-to-use or when-not-to-use guidance.

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

All Advocate tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?