Tool metadata priority headers are not policy for AI agents

Priority header smuggling happens when metadata says it outranks the policy that was supposed to control the tool run. The carrier might be a tool manifest, MCP descriptor, YAML frontmatter block, sidecar file, scheduler header, envelope note, annotation or generated run context field.

The dangerous phrase is not just "priority." Normal systems need priority, version, owner, trace, routing and provenance fields. The dangerous phrase is the combination of metadata plus authority language plus bypass language: "this header is authoritative," "this annotation supersedes guardrails," "this manifest overrides the validator," or "this sidecar is the source of truth for this run."

This is narrower than the broad MCP tool poisoning problem. Tool poisoning often focuses on malicious tool descriptions. Priority header smuggling focuses on ordering and authority. Which source the agent believes wins when tool metadata conflicts with policy, approval or runtime state.

AI agents are trained to treat structure as useful signal and attackers can abuse that habit. A YAML header looks official. A JSON manifest looks machine readable. A scheduler note looks like orchestration context. A signed looking envelope looks like something upstream already approved.

That is exactly why JACK's tool_metadata_smuggling pattern family separates benign metadata from authority changing metadata. A metadata header that records document version and owner is normal. A metadata header that says to ignore safety policy checks is not normal. A sidecar that contains telemetry fields is normal. A sidecar that says it supersedes the approval path is not normal.

The practical risk appears when a planner, tool router or wrapper promotes the metadata into the same decision layer as user intent, developer policy or guardrail state. Once that happens, a note that should have been evidence can become a reason to execute a more privileged tool, skip a validator or rebind the run context.

The runtime trust correction is not "ban headers." It is. Treat metadata as untrusted until an independent policy path says that exact field is allowed to change execution authority for this exact action. Teams can harden their agent pipelines and consult the Sunglasses manual for a structured approach.

These examples show how priority metadata becomes risky only when it tries to change policy, scope or guardrail order. The core question is not whether a header exists. The core question is whether the agent is about to obey a header that had no authority to command it.

Sunglasses catches priority header smuggling by looking for the risky combination. Metadata carrier, authority wording and policy bypass intent. The signal is strongest when terms like metadata, header, annotation, manifest, envelope, sidecar, frontmatter, run context or scheduler header appear near terms like authoritative, source of truth, priority, precedence, supersede, override, ignore, bypass, replace, policy, guardrail, safety check, approval, validator or execution gate.

That does not mean every mention is malicious. A security design document can safely discuss priority headers. A benign manifest can record provenance and checksum details. A training note can warn never to bypass approvals. Sunglasses is looking for the action time shape where untrusted metadata tries to change what the agent is about to do.

This is why runtime trust complements IAM, MCP gateways, schema validation, sandboxing and static policy. Those controls define which tools and scopes are generally available. Sunglasses asks a narrower question at the moment of action: did this piece of metadata just try to become authority over the tool call, file edit, endpoint request or workflow step?

That makes the pattern useful for teams building agent workflows around hardening checklists, pattern driven detection and post access runtime trust. The agent may be allowed to use the tool. The priority header still has to prove it is allowed to influence this use of the tool. See also the FAQ for common runtime trust questions and the CVP evaluation program for model specific results.

Before an AI agent treats metadata as authority, force the metadata to prove it has authority. Use this checklist for MCP descriptors, tool manifests, generated reports, run headers, sidecars, scheduler fields or workflow envelopes:

The repeatable sentence for teams is. Metadata can route, describe and explain. Policy decides and runtime trust verifies before action. The AI Agent Security 101 guide covers this principle across the full agent attack surface.

A tool metadata priority header attack is a tool metadata smuggling pattern where a manifest, sidecar, annotation, envelope or run context header claims higher authority than the agent policy, guardrail or approval path.

They are risky because agents may treat structured metadata as control context. If attacker controlled metadata says it is authoritative or supersedes policy, the agent can confuse evidence with permission.

Normal tool metadata describes version, owner, provenance, schema or routing context. Suspicious metadata tries to change policy order, override guardrails, bypass approval or rebind execution context.

Teams should treat metadata as untrusted evidence, require signed or allowlisted authority for policy changing fields, canonicalize the runtime binding and re check high risk actions before execution.

Sunglasses looks for the combination of metadata bearing fields, authority or precedence language and policy bypass verbs before an agent uses a tool, edits a file, calls an endpoint or changes workflow state.