AI Design Blueprint

Request Operator Handoff

handoffs.operator

Authenticated: creates a support handoff record when an agent needs human review, account-specific escalation, or operator follow-up that cannot be resolved with the read-only doctrine tools. Persists a SupportHandoff row (reason, topic, page_url, agent_name, agent_platform, trace_summary, user_email) routed to the support inbox; user is contacted by the team. WHEN TO CALL: user explicitly asks for human help, hits a billing/access issue, or the agent has tried the doctrine tools and the user still needs a human. ALWAYS confirm with the user before firing: this creates a human-visible ticket. WHEN NOT TO CALL: proactively, silently, or to log debugging traces (use diagnostic logs instead); for partnerships/agency enquiries (use handoffs.partnership / handoffs.agency); for content questions answerable by principles.search / guides.search. BEHAVIOR: write-only, single insert, side-effecting (creates a ticket the team will see). Auth: Bearer (any plan). Data at rest in the UK. Response confirms ticket id + topic so the user can reference it.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`topic`	No	Topic category for routing (e.g. 'agent', 'billing', 'access', 'general').	agent
`locale`	No	Response locale for the handoff acknowledgment.	en
`reason`	Yes	Clear description of why a human operator review is needed.
`page_url`	No	URL of the page or context where the handoff was triggered.
`agent_name`	No	Name of the agent or client triggering the handoff.	mcp-client
`trace_summary`	No	Optional summary of the agent's recent actions or trace for operator context.
`agent_platform`	No	Platform or runtime the agent is running on (e.g. 'claude-code', 'cursor', 'copilot').

Output Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedMay 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "title": "request_operator_handoffDictOutput",
+  "type": "object"
+}

Changed1 schema field changedMay 9, 2026

changedOutput schema / (root)

Previous value: -{
-  "$defs": {
-    "ErrorBody": {
-      "description": "The body of `error_payload(code, message, details)` returns.",
-      "properties": {
-        "code": {
-          "title": "Code",
-          "type": "string"
-        },
-        "details": {
-          "additionalProperties": true,
-          "title": "Details",
-          "type": "object"
-        },
-        "message": {
-          "title": "Message",
-          "type": "string"
-        }
-      },
-      "title": "ErrorBody",
-      "type": "object"
-    }
-  },
-  "properties": {
-    "error": {
-      "$ref": "#/$defs/ErrorBody",
-      "default": null
-    },
-    "guidance": {
-      "default": null,
-      "title": "Guidance",
-      "type": "string"
-    },
-    "handoff_id": {
-      "default": null,
-      "title": "Handoff Id",
-      "type": "string"
-    },
-    "handoff_type": {
-      "default": null,
-      "title": "Handoff Type",
-      "type": "string"
-    },
-    "next_action_url": {
-      "default": null,
-      "title": "Next Action Url",
-      "type": "string"
-    },
-    "next_step": {
-      "anyOf": [
-        {
-          "additionalProperties": true,
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "title": "Next Step"
-    },
-    "status": {
-      "default": null,
-      "title": "Status",
-      "type": "string"
-    }
-  },
-  "title": "HandoffResponse",
-  "type": "object"
-}New value: +null

Changed1 schema field changedMay 8, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$defs": {
+    "ErrorBody": {
+      "description": "The body of `error_payload(code, message, details)` returns.",
+      "properties": {
+        "code": {
+          "title": "Code",
+          "type": "string"
+        },
+        "details": {
+          "additionalProperties": true,
+          "title": "Details",
+          "type": "object"
+        },
+        "message": {
+          "title": "Message",
+          "type": "string"
+        }
+      },
+      "title": "ErrorBody",
+      "type": "object"
+    }
+  },
+  "properties": {
+    "error": {
+      "$ref": "#/$defs/ErrorBody",
+      "default": null
+    },
+    "guidance": {
+      "default": null,
+      "title": "Guidance",
+      "type": "string"
+    },
+    "handoff_id": {
+      "default": null,
+      "title": "Handoff Id",
+      "type": "string"
+    },
+    "handoff_type": {
+      "default": null,
+      "title": "Handoff Type",
+      "type": "string"
+    },
+    "next_action_url": {
+      "default": null,
+      "title": "Next Action Url",
+      "type": "string"
+    },
+    "next_step": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Next Step"
+    },
+    "status": {
+      "default": null,
+      "title": "Status",
+      "type": "string"
+    }
+  },
+  "title": "HandoffResponse",
+  "type": "object"
+}

First observedMay 1, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Beyond the annotations, the description discloses that this is a write-only, single-insert, side-effecting operation that creates a human-visible ticket, requires Bearer auth, stores data at rest in the UK, and returns a confirmation with ticket id and topic. This significantly enriches the annotation signals and sets correct expectations for a handoff action.

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?

Although longer than average, the description is well-structured with explicit headers (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) and front-loads the core purpose and side-effect warning. Every sentence carries relevant routing, confirmation, or behavioral information with no filler.

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

Completeness5/5

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

For a side-effecting, human-visible ticket creation tool, the description covers the essential operational context: when to invoke, when not to, user confirmation requirement, auth, data residency, and response shape. Since the output schema exists and parameters are fully documented, nothing critical is missing for an agent to invoke this safely.

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 baseline is 3 and the description does not need to heavily compensate. The description enumerates several persisted fields (reason, topic, page_url, agent_name, agent_platform, trace_summary) but adds little semantic detail beyond what the schema already provides. It also mentions user_email, which is not actually a parameter in the schema, creating a minor mismatch.

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

Purpose5/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: it 'creates a support handoff record' when human review or operator follow-up is needed. It clearly names the scope (support handoffs) and distinguishes itself from siblings by saying partnership/agency enquiries use handoffs.partnership / handoffs.agency and content questions use principles.search / guides.search.

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

Usage Guidelines5/5

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

The description provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, including concrete trigger conditions ('user explicitly asks for human help, hits a billing/access issue, or the agent has tried the doctrine tools'). It also names alternative tools to use instead, so the agent has clear routing guidance.

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

All AI Design Blueprint 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?