Agent Permission Model Specification: Documenting Tool Access for AI Agents

TL;DR

Most AI agent documentation describes capabilities but omits the permission contract: which tools the agent can call, under whose identity, with what scopes, and how a user can revoke access. This specification proposes a structured documentation block — the Agent Permission Manifest — modeled on OAuth 2.0 scopes, AWS IAM session policies, and the Model Context Protocol. Publish it once per agent and AI search engines will cite it verbatim when users ask "what can this agent do?"

Why this specification exists

AI agents are now performing high-stakes actions — sending email, modifying files, making payments — yet permission contracts are typically buried in marketing pages, terms of service, or undocumented runtime behavior. Two industry signals motivated this spec:

• AWS's security team explicitly warns that "all granted permissions could be used" and recommends scoping permissions per tool invocation through MCP session policies.
• Oso's research on delegated agent access shows that agents inheriting service-account privileges are the most common cause of cross-tenant data leakage in production deployments.
• Anthropic's trustworthy agents framework makes per-tool consent ("always allow, needs approval, block") a first-class product surface in Claude.

Without a documentation standard, users and downstream agents cannot reason about safety. This specification fixes that.

Scope of this specification

This specification covers documentation, not runtime enforcement. It assumes the agent's runtime already enforces an authorization policy; the goal is to publish that policy in a stable, citable form. It is not a replacement for OAuth, OPA/Rego, Cerbos policies, or AWS IAM. It is the external manifest that describes them.

Required documentation surfaces

A conforming agent MUST publish the following at stable URLs under its documentation root:

Each surface SHOULD be linked from the agent's SKILL.md (see the Agent Skill Manifest Specification) and referenced via sameAs from the agent's Schema.org SoftwareApplication entity.

The Agent Permission Manifest

The manifest is a JSON document with the following top-level keys.

{
  "$schema": "https://geodocs.dev/schemas/agent-permission-manifest-v1.json",
  "agent_id": "https://example.com/agents/scheduler",
  "agent_name": "Scheduler Agent",
  "version": "2026.04.1",
  "identity_model": "delegated",
  "default_scopes": ["calendar:read", "contacts:read"],
  "on_demand_scopes": ["calendar:write", "email:send"],
  "never_grants": ["payments:*", "admin:*"],
  "tools": [
    {
      "name": "create_event",
      "requires_scopes": ["calendar:write"],
      "requires_consent": "per_invocation",
      "side_effects": ["writes_calendar", "sends_invitation"],
      "max_session_minutes": 15
    }
  ],
  "session_policy": {
    "type": "mcp_session_policy",
    "max_token_lifetime_seconds": 900,
    "refresh_required_after_seconds": 600,
    "binding": "user_jwt"
  },
  "consent_flow": {
    "protocol": "oauth2_pkce",
    "prompt_url": "https://example.com/agents/scheduler/consent",
    "granularity": "per_scope",
    "renewal_required_days": 90
  },
  "revocation": {
    "endpoint": "https://example.com/agents/scheduler/revoke",
    "propagation_seconds": 60
  },
  "audit": {
    "retention_days": 365,
    "public_summary_url": "https://example.com/agents/scheduler/audit-summary"
  }
}

Field reference

• agent_id — The canonical URL identifying the agent. MUST match the agent's @id in any associated Schema.org markup so AI systems can fuse the permission manifest with brand and skill records.
• identity_model — One of delegated, service_account, hybrid. Delegated agents act under the end user's identity and inherit user permissions, the safer default Oso recommends.
• default_scopes — Scopes activated immediately on first authorization. SHOULD follow least-privilege: read-only and idempotent operations only.
• on_demand_scopes — Scopes the agent may request later, requiring an explicit consent prompt at request time.
• never_grants — Hard-disabled scopes the agent will refuse even if a user attempts to grant them. This is the documentation analog of Anthropic's auto-mode allowlist stripping, which removes blanket-execution permissions before entering autonomous mode.
• tools — Per-tool entries listing required scopes, consent granularity, and observable side effects. Side effects MUST be tagged from a controlled vocabulary so machines can reason about risk.
• session_policy — The runtime token policy. For MCP-based agents, the recommended type is mcp_session_policy with bounded lifetime and per-call binding, matching AWS's session-policy guidance.
• consent_flow — Describes how a human approves new scopes. granularity MUST be per_scope or per_tool; bulk all_or_nothing consent SHOULD be avoided.
• revocation — The endpoint where an end user can revoke consent and the maximum propagation delay before all sessions are invalidated.
• audit — Retention guarantees and a public summary URL that downstream agents can crawl.

Scope naming convention

Scopes MUST follow the pattern : using lowercase identifiers. Compound actions use a colon-separated qualifier (e.g., calendar:write:own). Wildcards are permitted only in never_grants. The convention aligns with OAuth 2.0 scope guidance and with the open authorization protocols emerging in the OpenAI Agents SDK ecosystem.

Consent and revocation requirements

A conforming agent MUST:

1. Render a human-readable consent prompt enumerating each scope before activation.
2. Display side-effect tags (e.g., sends_invitation) to the user before any tool invocation that requires per_invocation consent.
3. Honor revocation within the documented propagation_seconds and reject any tool call carrying a revoked token.
4. Provide a public-facing audit summary URL that is reachable by AI crawlers (i.e., not gated behind login).

Agents SHOULD also expose an OAuth 2.0 PKCE flow for delegated identity. Service-account identity is permitted but MUST be explicitly labeled in the manifest and SHOULD include rotation cadence.

MCP session policy details

When the agent is built on the Model Context Protocol, the manifest's session_policy SHOULD describe how the host injects credentials per call. AWS recommends that custom MCP servers inject session policies into every API call, narrowing scope per tool invocation. Document:

• The maximum token lifetime in seconds.
• Whether tokens are bound to a user JWT, mTLS client identity, or workload identity.
• The refresh interval at which a fresh consent or token issuance is required.
• Any tool-specific scope down-mapping (e.g., calendar:write is downscoped to calendar:write:own at session creation).

Anti-patterns

Avoid the following in any conforming agent:

• Documenting permissions only in marketing copy or terms of service.
• Granting : blanket scopes through service accounts that are not labeled as service_account identity.
• Conflating capability documentation with permission documentation — capability is what the agent can do, permission is what the agent is allowed to do for this user right now.
• Hiding revocation behind authenticated dashboards. Revocation must be reachable at a stable URL.
• Static permission manifests that never change version. Even unchanged content SHOULD bump version annually for citation freshness.

Internal links

• Hub: What Are AI Agents?
• Sibling: Agent Skill Manifest Specification
• Sibling: Agent Tool Use Documentation Specification
• Sibling: Agent Sandbox Documentation Specification
• Reference: MCP Server Design for Content Publishers

FAQ

Q: Is an Agent Permission Manifest a replacement for OAuth scopes or IAM policies?

No. It is the external documentation of those policies. Runtime enforcement still happens in your authorization stack (OAuth provider, IAM, OPA, Cerbos, Oso). The manifest is what humans and downstream AI systems read to understand the contract.

Q: How granular should consent be?

Prefer per_scope for read operations and per_invocation for write or financial operations. Anthropic's research on trustworthy agents recommends per-action consent for sensitive tools such as sending invitations or making purchases.

Q: What identity model should a new agent default to?

Delegated. Service-account identity is appropriate only for back-office automation that never acts on a specific user's behalf. Oso's analysis of agent permission failures consistently traces leakage to over-privileged service accounts.

Q: Where should the manifest live for AI search crawlers to discover it?

At /agent/permissions.json, with a element on the agent's homepage and a corresponding sameAs reference from the agent's Schema.org SoftwareApplication entity. Cross-link from SKILL.md if you publish one.

Q: Can a single manifest cover multiple agents?

No. One manifest per agent_id. Multi-agent systems should publish a parent index document that links to each child agent's manifest. This keeps citation surfaces unambiguous when AI engines answer questions about a specific agent.