Home/Blog/How per-request metadata is simplifying secure, scalable tool handoffs
How per-request metadata is simplifying secure, scalable tool handoffs
October 10, 2026

Secure agent-to-tool delegation breaks down when identity, tenant, locale, approval state, and routing decisions are buried in prompts or copied through bespoke workflow glue. Per-request metadata simplifies secure, scalable tool handoffs by delivering the narrow context a tool server needs at call time without exposing that context to the model.
For platform engineers and teams running MCP-connected specialists, that changes the design center. Instead of asking an agent to faithfully repeat who the user is and what they may access, the control plane can attach request context, validate credentials at the tool boundary, preserve handoff state, and create an auditable record of what happened. The result is not automatic security; it is a clearer separation between model reasoning, orchestration, and enforcement.
Per-request metadata creates a safer boundary for tool handoffs
A tool handoff is more than selecting the next agent. It is a transfer of operational responsibility: one specialist or tool now needs enough context to perform work correctly, while receiving no more authority or data than the task requires. That is difficult when the only shared channel is conversation text.
Per-request metadata provides a separate channel for call-time context. OpenAI’s plugin reference describes _meta values that are sent on tool calls, including locale, coarse user location, session, subject, and organization identifiers. Because these values do not need to be placed into the model’s context, they can support tool behavior without turning sensitive operational attributes into prompt material.
Direct answer: Per-request metadata makes tool handoffs simpler because the orchestration layer can send validated, minimal context with each call, while the receiving server authorizes the request from credentials rather than from model-generated text. This supports tenant-safe routing, personalization, auditing, and resumable delegation without broadly exposing identity or state.
This distinction matters in practical workflows. A support specialist may decide that a billing system should retrieve an invoice, or a coding specialist may need a private MCP server to inspect a repository. The model can determine that a tool is relevant, but it should not be the source of truth for the caller’s account, organization, or permissions. The tool server must derive those decisions from validated credentials and enforce them for the specific request.
Model-visible context
helps an agent reason about the task and communicate with the user.
Per-request metadata
supplies scoped operational context such as session, subject, organization, locale, or coarse location.
Validated credentials
establish what the caller is allowed to do; they are the basis for server-side authorization.
Run state
preserves where a workflow paused, which specialist owns the next turn, and which approvals remain pending.
Keeping these layers distinct reduces a common failure mode: treating a prompt instruction, a model-produced identifier, or a UI-provided location as proof of authorization. OpenAI explicitly warns that servers must enforce authorization on every request and must not rely on model behavior. Its documentation also notes that userAgent and userLocation are hints, not authorization signals.
Why prompt-based context does not scale securely
Passing context in a prompt is attractive because it is immediate. A developer can tell an agent, “This user belongs to organization X,” then ask it to call a tool. But that approach makes important execution context dependent on natural-language instructions, model interpretation, and often a growing transcript.
It also blurs trust boundaries. If a downstream tool accepts a tenant ID or role from model output, the server has allowed untrusted output to influence an access-control decision. A careful prompt may reduce mistakes, but it cannot replace a server-side check against credentials and policy.
What goes wrong when identity travels as text
Tenant confusion:
A stale or incorrectly summarized organization identifier can send a request to the wrong account boundary.
Privilege drift:
An agent may retain or repeat permissions from an earlier step even when a later call should be more narrowly scoped.
History bloat:
Repeating routing and identity details across specialist prompts consumes context and creates more places for sensitive information to appear.
Weak auditability:
It becomes harder to distinguish what a user requested, what the model inferred, what credentials permitted, and what tool activity actually occurred.
Brittle handoffs:
Every application ends up rebuilding conventions for carrying session state, approval status, and specialist ownership.
Per-request metadata does not mean every useful value is security-sensitive. Locale can help a tool format dates, and coarse location can help tailor a location-aware experience. Yet these fields need an explicit classification: helpful hints may influence presentation or routing, while only validated identity and policy evaluation can grant access.
This is especially important in decentralized agent architectures. Broader agent guidance describes decentralization as a pattern in which one agent can directly hand off control to another rather than returning every decision through a central orchestrator. That can improve specialization and reduce unnecessary routing, but direct delegation needs a dependable way to transport minimal context. Per-request metadata supplies that context without asking each agent to reconstruct identity from prose.
Use per-request metadata for identity-aware, multi-tenant routing
Multi-account systems need correlation and routing without mixing identities. OpenAI’s plugin documentation identifies three relevant fields: _meta["openai/subject"] for rate limiting and identification, _meta["openai/session"] for correlating calls within the same conversation, and _meta["openai/organization"] for associating an organization context. The documentation describes session and organization identifiers as anonymized context for correlation and multi-account routing.
These identifiers should not become a substitute for authentication. Their value is that they give the receiving system stable context to associate calls, choose the appropriate tenant-aware execution path, apply operational controls, and log events consistently. The server still resolves a profile from validated credentials and scopes every tool call to those credentials, as official MCP server guidance recommends.
A practical call-time decision sequence
Receive the tool call and credentials.
Terminate or validate the relevant authentication mechanism at the trusted server boundary.
Resolve the caller profile from those credentials.
Determine the authorized subject, tenant or organization membership, roles, and applicable policy from trusted systems.
Read metadata as contextual input.
Use session, organization, locale, and other supplied fields to correlate, personalize, or select an execution path. Reject or safely handle inconsistency with the validated profile.
Apply authorization for this exact operation.
Check the resource, requested action, tenant boundary, approval requirement, and any network or environment policy.
Execute with the least privilege available.
Scope downstream access to the current call rather than granting a broad, persistent capability merely because a handoff occurred.
Record the decision and outcome.
Preserve the request correlation, authorization outcome, tool activity, and result in an audit trail appropriate to the environment.
Consider an operations workflow that begins with a triage agent and transfers to an account specialist. The triage agent can select the specialist because the issue concerns an organization-level setting. At call time, the harness supplies session and organization context, while the account tool validates credentials and resolves whether the caller may view or change that setting. The tool should not trust a sentence stating that the caller is an administrator.
This pattern is useful even when a single product currently serves one customer account. Building explicit request context early prevents identity assumptions from becoming hidden architecture. It also makes later expansion to multiple organizations, delegated administrators, or specialized tools more manageable.
Design secure tool handoffs around validated credentials, not metadata alone
Metadata is powerful precisely because it is narrow and available at the point of execution. It is not a permission grant. The security model remains least privilege, boundary preservation, and authorization on every request.
OpenAI’s security-focused guidance repeatedly emphasizes preventing access beyond authorized rights and avoiding reliance on untrusted model output for access decisions. The plugin reference is equally clear that location and user-agent values are hints only. Treating every metadata field as trustworthy would recreate the same problem that prompt-based authorization creates, just in a different transport.
Separate fields by the decision they may influence
A useful design review asks not only, “What metadata do we need?” but also, “What is this field allowed to change?” That question forces a distinction between a field used for observability and one used to approve access.
Authorization inputs:
validated credentials, server-resolved identity, resource policy, and required approval state. These can determine whether the tool performs an action.
Routing inputs:
organization context, tool capability, environment selection, and run state. These can select a compliant route but should remain subject to policy checks.
Personalization inputs:
locale and coarse location. These can adapt formatting or regional behavior where appropriate.
Observability inputs:
session and correlation identifiers. These can connect events across a workflow and support debugging, rate limiting, and audit review.
There are trade-offs. Adding more metadata can make a handoff convenient, but every field increases the surface that must be documented, protected, retained appropriately, and reviewed. OpenAI’s work on secure MCP tunnels highlights that a tunnel provider becomes part of the security review and metadata surface. A smaller, per-request context channel is generally easier to inspect and secure than broad, persistent exposure, but “small” must be designed deliberately.
For that reason, do not use metadata as an unbounded side channel for full chat histories, raw secrets, or broad user profiles. Carry the minimum needed for the immediate call. When the specialist needs data, prefer controlled retrieval or permissioned access rather than copying the data into every agent context.
Make specialist delegation stateful without copying the whole conversation
Secure routing is only half of a workable handoff. A specialist must know enough to continue the job, and the system must know what happens after that specialist finishes or pauses. OpenAI positions handoffs as a first-class orchestration primitive: a specialist agent takes over a branch of work. In more advanced designs, handoffs can carry structured metadata or filtered history.
Filtered history is an important alternative to indiscriminately forwarding a full transcript. A specialist may need the current objective, decisions already made, and selected artifacts, but not every earlier turn. Structured handoff metadata can represent the task and constraints directly; filtered history can provide the conversational evidence needed to complete it. The correct balance depends on the task, but neither should be confused with authorization context.
Use three separate payloads in a handoff
Teams often get better results when they define each payload explicitly:
Task payload:
the problem to solve, expected output, current constraints, and any non-sensitive facts the specialist needs to reason effectively.
Execution context:
per-request metadata
and validated credential context available to the tool server or harness for routing, policy, and correlation.
State payload:
the workflow snapshot, pending approvals, ownership information, and resumable execution details.
The Agents SDK’s result and state surfaces support this model. lastAgent or last_agent indicates the specialist that should own the next turn, while interruptions and state preserve pending approvals and a resumable snapshot. That reduces the need for custom glue code that tries to infer which agent should resume and whether a previous tool call is waiting on a human decision.
For example, a remediation agent may identify a production change that requires approval. Rather than forcing a new coordinator to rebuild the previous workflow from text, the system can retain the interrupted state, the approval requirement, and the current specialist ownership. When approval arrives, the appropriate agent can resume from the recorded state under fresh, per-request authorization checks.
This is also where per-run customization becomes valuable. Recent agent documentation shows richer run-level surfaces such as sandbox session source, client options, and fresh inputs. Making run context explicit lets a platform distinguish what belongs to a particular execution from what belongs in long-lived agent configuration.
Bring data to the sandbox instead of expanding model context
Many handoffs need access to files, source code, internal documents, or operational systems. The tempting response is to put more data into the model context so every specialist can see it. That may make the first implementation easier, but it increases exposure and makes context management slower and harder to govern.
The Agents SDK evolution emphasizes bringing data to the sandbox rather than forcing everything into context. Mounts, file permissions, and per-run customization support a more contained approach: make needed material available to the execution environment under explicit controls, rather than replicating it through prompts or handoff messages.
This approach complements per-request metadata. Metadata tells the execution layer who or what the call is associated with and how it should be correlated. Permissions and mounts constrain what the sandbox or tool can access. The specialist can work with relevant resources without receiving a generalized data dump.
Choose the smallest context path that solves the task
Use a concise task summary when the next agent only needs a clear objective.
Use filtered history when prior discussion materially affects the specialist’s reasoning.
Use structured handoff metadata when the system needs reliable, machine-readable task constraints.
Use a mounted or permissioned resource when the specialist needs to inspect source material or files.
Use a tool call with validated credentials when the needed information belongs behind an application or enterprise boundary.
There is no guarantee that less context always means better outcomes. A specialist can fail when it lacks the key decision, artifact, or constraint from the previous stage. The discipline is to pass only what is necessary through each channel and to make the reason for each channel explicit. That gives teams a concrete way to debug failures: was the task incomplete, was the data inaccessible, was the route wrong, or was the action unauthorized?
Centralize control-plane responsibilities while allowing flexible routing
At scale, the critical question is not whether every handoff passes through one agent. It is whether important execution responsibilities are implemented consistently. OpenAI describes the harness as owning tool routing, handoffs, approvals, tracing, recovery, and run state. That model centralizes the control plane around the model-driven workflow without requiring every business action to be encoded in a single application-specific coordinator.
A control plane can enforce common conventions across specialist agents and MCP tools: request correlation, credential validation boundaries, approval handling, tracing, retry behavior, state persistence, and recovery. Individual agents can still directly hand off to other specialists when decentralization is appropriate, but they do so within a shared operational framework.
What should be standardized across every handoff
A stable schema and ownership rules for
per-request metadata
.
A clear credential-validation point for each tool server.
A policy that every tool call is scoped to validated credentials.
Consistent approval and interruption handling for consequential actions.
Trace identifiers that connect the user request, agent decision, tool call, and result.
Recovery behavior for incomplete runs, including which specialist owns the next turn.
Standardization should not mean a monolithic agent or a universal prompt. Specialist agents remain useful because they can operate with focused instructions, tools, and task boundaries. The control plane supplies consistency around them; per-request metadata gives each transition the context needed to operate safely within those boundaries.
OpenAI’s announcement of newer agent tooling describes handoffs as intelligently transferring control between agents and presents the Agents SDK as a way to simplify multi-agent workflows. Later launch notes about subagent support describe workflows involving implementation, independent review, remediation, and browser validation. These are examples of why durable state, controlled context, and consistent routing become operational requirements rather than optional framework features.
Build auditability and approvals into the handoff path
A secure workflow must be explainable after the fact, especially when a tool can modify systems, access private environments, or trigger external activity. Per-request metadata makes it easier to attach correlation context to the exact call that produced an effect. It does not replace logs, but it makes logs more useful because events can be joined to a session, subject, organization context, and run.
OpenAI’s safe-Codex writeup illustrates the value of recording the original request, tool activity, approval decisions, tool results, and network-policy outcomes. That sequence provides a practical auditing model for delegated execution: capture intent, enforcement, execution, and outcome rather than logging only the final response.
Record the original task and handoff decision.
Preserve what work was requested and why a specialist or tool was selected.
Record the authorization and policy result.
Capture that the server evaluated the call against validated credentials and applicable controls.
Record approvals and interruptions.
Make pending decisions and their eventual resolution visible in the run record.
Record tool activity and results.
Include the effect of the call and relevant network-policy outcomes where those policies apply.
Link events through run and request correlation.
Use session and organization context appropriately to investigate behavior without relying on a free-form transcript alone.
Private MCP connectivity sharpens this requirement. OpenAI’s guidance on private MCP servers describes an outbound-only Secure MCP Tunnel that connects private environments without making tools public. This can reduce exposure while preserving functionality, but it does not remove the need for authorization, scoping, or audit controls inside the private environment. Keeping routing and authorization local to the server side pairs naturally with per-request metadata.
Adopt per-request metadata with an incremental implementation plan
Most teams do not need to redesign every agent workflow at once. Start with the handoffs that cross the strongest boundaries: production operations, tenant-specific data, private MCP servers, code execution, or any action requiring approval. These are the paths where the gap between model intent and server enforcement is most consequential.
First, map the current handoff contract
List what currently passes from one agent or application step to another. Separate instructions, conversation history, user identifiers, organization information, credentials, approval records, and resource references. If an authorization-relevant value exists only in prompt text or model output, move its enforcement to a trusted server-side lookup.
Then, define a minimal metadata schema
Include only fields that serve an operational purpose at call time. Document each field’s source, whether it is a hint or trusted context, where it is visible, how it is retained, and which decision it may influence. Use the available subject, session, and organization identifiers for identification and correlation in line with their documented purposes; do not overload them with permissions.
Finally, exercise the difficult paths
Test tenant switching, stale sessions, denied actions, interrupted runs, approval resumption, specialist-to-specialist delegation, and private tool connectivity. Verify that each tool server resolves profiles from validated credentials, scopes calls to those credentials, and rejects attempts to expand access through prompt or metadata manipulation. Trace the workflow end to end so operators can see both the agent decision and the enforcement decision.
The practical takeaway is straightforward: make context explicit, keep it minimal, and enforce access where the action occurs. Per-request metadata gives agent platforms a clean call-time channel for routing and correlation; structured handoffs and resumable state make delegation durable; validated credentials and least-privilege controls keep the model from becoming the security boundary.
As multi-agent workflows add more specialists, private tools, approvals, and organization boundaries, bespoke handoff glue becomes harder to trust and operate. A shared control plane that combines per-request metadata, scoped tool calls, stateful recovery, and auditable execution provides a more reliable foundation for secure, scalable tool handoffs.