Technical Guide

Tool Manifest Schema, Validation, and Runtime Checks for AI Agents

A tool manifest is a declarative definition of a tool's name, description, and expected input/output structure that an AI agent uses to decide how to call that tool. Manifests are typically validated structurally through JSON Schema before and during invocation, but most current implementations, including MCP, do not verify that a tool's actual runtime behavior matches what its manifest declares. That gap is one security teams must address through additional runtime checks and policy enforcement.

What a Tool Manifest Governs

Declared Identity

Tool name and description exposed to the agent during discovery.

Input Contract

JSON Schema defining required parameters, types, and formats.

Session Scope

Capabilities negotiated once at session initialization.

Runtime Gap

The unverified space between declared behavior and actual execution.


A tool manifest is a structured declaration of what a tool does and how it expects to be called. In the Model Context Protocol (MCP), a tool is represented as an object with a name, a description, and an inputSchema expressed in JSON Schema. This schema defines the parameters an agent must supply, their types, and which fields are required. Clients discover available tools through a listTools request, which returns each tool's manifest before any call is made. The manifest functions as a contract: the agent reads it to determine how to construct a valid call, and in principle the receiving system uses it to validate that the call conforms to what was declared. This structure is deliberately declarative rather than executable. The manifest describes shape and intent, not implementation. That separation is useful for interoperability, but it also means the manifest itself cannot guarantee that the underlying tool behaves as described.

How Manifest Validation Works Today

Validation in MCP is primarily structural. When an agent issues a callTool request, the arguments are checked against the tool's declared inputSchema, and the server is responsible for confirming that the shape of the request matches expectations. This catches malformed calls, missing required fields, or incorrect types. It does not confirm that the tool will produce output consistent with its description, nor does it verify that the tool's description accurately reflects its actual function.

Capability negotiation, which determines what tools and features are available, happens once during session initialization. Once negotiated, the set of available tools is generally treated as fixed for the remainder of that session. This is efficient, but it means that if a tool provider changes behavior or capabilities mid-session, there is no built-in mechanism in the base protocol to detect or react to that drift.

The Gap Between Declared and Actual Behavior

The central technical problem for security engineers is that schema validation confirms structure, not semantics. A tool manifest can declare that a function retrieves account status and expects a customer ID as input. JSON Schema validation will confirm that a caller supplied a string where a string was expected. It will not confirm that the function actually only retrieves account status, does not write data, or does not exceed the scope implied by its description.

Verifying that a tool's runtime behavior matches its declared manifest is not something current MCP documentation specifies in detail. This is an architectural gap that must be closed independently, typically through output validation, behavioral monitoring, or policy enforcement layered on top of schema checks rather than through the manifest format itself.

Why This Matters for Agent Security

OWASP's guidance on large language model applications identifies Excessive Agency as a top-tier risk, describing harm that results when an agent has more function-calling permission, scope, or autonomy than its task requires. An unvalidated or loosely enforced tool manifest is a direct contributor to this risk: if the manifest does not constrain scope precisely, or if that scope is not enforced at runtime, an agent can invoke tools in ways that exceed intended use.

OWASP also notes that insufficient validation of tool outputs can allow unverified or malicious data to propagate downstream, since agents often trust tool responses without independent verification. Recommended mitigations include limiting available tools and functions to the minimum necessary for the task, and validating both inputs and outputs against expected formats, not inputs alone.

Where Validation and Enforcement Should Live

Enforcement architecture for tool manifests generally needs to address three separate concerns:

  • Structural validation: confirms that inputs and outputs conform to the declared schema. This can happen client-side, server-side, or both; current MCP practice leans toward server-side responsibility for argument validation.
  • Authorization enforcement: confirms that the calling agent is permitted to invoke a given tool with a given scope. JSON Schema validation alone does not address this, since schema and permission are distinct concerns.
  • Behavioral verification: confirms that a tool's actual output is consistent with its declared function over time. This is the least standardized layer and typically requires monitoring or policy logic outside the manifest format itself.

Treating these as separate architectural components, rather than assuming schema validation covers all three, is necessary to close the gap between declared and actual tool behavior.

Governance and Audit Implications

NIST's AI Risk Management Framework treats traceability and documentation of AI system components as core governance functions, which extends naturally to tool manifests. A manifest is not only a technical schema; it is a governance artifact that documents what a tool is permitted and expected to do, and it should be reviewable and auditable on that basis.

This matters most in enterprises running multiple agent frameworks or integration standards, since there is no single cross-framework manifest standard. MCP is the most concretely documented example available, but other frameworks define tool or function-calling schemas differently, and validation rigor can vary between them. That inconsistency creates compliance ambiguity: a manifest validated strictly in one integration path may be enforced more loosely in another, undermining the assumption that declared tool behavior is uniformly checked across an agent's full toolset.

How Trussed AI Supports Manifest Governance

Trussed AI provides runtime governance for AI agents, with capabilities that include MCP security, agent permissions, least privilege enforcement, tool approval workflows, and audit logging. These capabilities apply directly to the gaps described above: enforcing least privilege at the point of tool invocation, requiring approval workflows before new or unrecognized tools are granted access, and maintaining audit logs of tool calls and validation outcomes. This runtime layer operates alongside manifest schema validation rather than replacing it, addressing the authorization and monitoring concerns that schema checks alone do not cover.


Manifest Validation Checklist for Security Engineers

  • Confirm whether validation covers both tool inputs and outputs, not inputs alone.
  • Determine how the platform handles manifest or capability changes during a long-running session.
  • Verify that tool permissions and scope are explicit in the manifest rather than implied by description text.
  • Establish logging for manifest validation failures to support audit and incident review.
  • Identify whether structural schema validation is treated as sufficient, or whether separate behavioral checks exist.
  • Confirm consistent validation logic across all agent frameworks in use, since inconsistent enforcement is a named risk.

Close the Gap Between Declared and Enforced Tool Behavior

Schema validation confirms structure. Runtime governance confirms that tool calls stay within approved scope and are auditable after the fact.

Explore Runtime Governance