Skip to main content
Glama

AdvocateMCP

by com.advocatemcp
OverviewDiscussionsAdmin

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

TableJSON Schema
NameRequiredDescriptionDefault
slugYesBusiness slug identifier
reasonNoWhy the user wants the callback
urgencyNoHow time-sensitive (default: normal)
agent_idNoOptional agent identifier
contact_nameNoEnd-user's name
contact_emailNoEnd-user's email
contact_phoneNoEnd-user's phone
idempotency_keyYesIdempotency key
preferred_channelNoChannel the user prefers (default: any)

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
reasonNoPresent 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
statusYes'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_urlNoPresent 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_idYes
delivered_viaYes'sms' or 'email' when notified; null otherwise
acknowledgmentYesCustomer-facing sentence to relay; null only on a replay caught while the original send is still in flight
idempotent_replayNoPresent and true when this idempotency_key already had a request; nothing was re-sent

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • 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."
  2. Changed1 schema field changed
    • 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"
+}
  3. Changed2 schema fields changed
    • 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,}$"
  4. Changed12 schema fields changed
    • 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"
+]
  5. Changed12 schema fields changed
    • 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"
+]
  6. Changed12 schema fields changed
    • 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"
+]
  7. First observed

TDQS

B3.2/5.0
Behavior1/5

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

The annotations declare destructiveHint=true, but the description says 'Submit a callback request' and emphasizes idempotency, indicating a non-destructive create operation. This is a direct annotation contradiction. The description does disclose delivery-not-guaranteed and follow-up needs, but the contradiction forces the lowest score.

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 with no fluff: purpose, delivery caveat, and idempotency behavior are each covered. The information is front-loaded and every sentence earns its place.

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 9-parameter state-changing tool, the description covers purpose, external delivery behavior, failure handling, and idempotency, which is solid given the output schema and full parameter schema coverage. The main gap is the lack of alternative-tool routing, and the destructiveHint contradiction adds confusion.

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%, so the schema fully documents each parameter; the description adds value by explaining idempotency_key behavior and the SMS/email channel context. This matches the baseline of 3 where 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 and resource ('Submit a callback request') and adds useful context (on behalf of a user, via lead routing). It is clearly distinct from siblings like request_service or submit_quote_request, though it does not explicitly name or contrast those alternatives.

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?

The description implies when to use the tool (when a user wants a callback) and provides post-use guidance about failed or pending notification results requiring follow-up or retry. However, it does not explicitly state when to choose this tool over alternatives or provide exclusion criteria.

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

All AdvocateMCP toolsInspect
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