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). UK/EU residency. 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

TDQS

A4.9/5.0

Behavior5/5

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

Goes beyond the annotations by disclosing side effects ('write-only, single insert, side-effecting'), the requirement to confirm with the user before firing, auth specifics (Bearer token, any plan), residency (UK/EU), and response content (ticket id + topic). Also notes the record is routed to the support inbox and that the user is contacted. No contradiction with annotations.

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?

The description is long but well-structured with CAPS-labeled sections (WHEN TO CALL, WHEN NOT TO CALL, BEHAVIOR) that are easy to parse. Every sentence provides actionable information, with no redundant wording.

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?

Given the tool's complexity (7 params, annotations, output schema), the description covers invocation rationale, exclusions, side effects, auth requirements, user confirmation, and response details. It is comprehensive enough for an agent to confidently decide when and how to invoke it.

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 baseline is 3. The description adds meaning by listing the persisted SupportHandoff fields (reason, topic, page_url, agent_name, agent_platform, trace_summary, user_email) and explaining routing, which helps the agent understand how parameters map to the record. One minor issue: user_email is mentioned but not present in the schema, causing slight ambiguity.

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 clearly states it 'creates a support handoff record' for specific scenarios (human review, escalation, operator follow-up) that cannot be resolved via read-only doctrine tools. It also explicitly names sibling tools to distinguish from them in the WHEN NOT TO CALL section.

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?

Provides explicit WHEN TO CALL and WHEN NOT TO CALL sections, listing triggers (user request, billing/access issues, doctrine tools failing) and exclusions (proactive/silent use, logging traces, partnerships/agency, content questions). Each exclusion names the correct alternative tool, giving clear decision 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

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose within its domain: the validators are differentiated by lens (architect/design/spec), content tools are split by entity (principles/clusters/guides/examples/assets) with list/get/search variants, and even the me.* and handoffs.* tools have non-overlapping functions. The only near-overlap (architect.validate vs architect.validate_consensus) is explicitly disambiguated by the consensus variant's description.

Naming Consistency4/5

Tool names consistently use a domain prefix (architect., principles., me., etc.) and snake_case throughout. While most are action-oriented (validate, list, get, search, add, await, report, summarize), some me.* and handoffs.* names are noun phrases (me.learning_path, handoffs.agency) that don't signal the action as clearly, creating minor deviation from a pure verb_noun or action pattern.

Tool Count3/5

At 29 tools, the set is heavy but justified by the server's broad multi-domain scope (doctrine, validation, learning, support, and team analytics). Each tool has a distinct role, but the number exceeds the typical well-scoped range, and some content types (e.g., examples) could have been consolidated without losing function.

Completeness4/5

The server covers its apparent domains thoroughly: doctrine content has list/get/search for most entity types, validation covers architecture/design/spec with consensus and certification, and user learning/support have appropriate tools. Minor gaps exist—e.g., examples have no list-all endpoint, and session management is web-only—but none are blocking for core workflows.

Resources

Need Help?