# Capabilities and Contracts

A capability is an operation that another participant can discover and invoke.
It can represent a tool, workflow, agent behavior, channel operation, human
task, or readable resource.

The capability contract is what makes the operation safe to automate. It tells
a caller and runtime not only what JSON the operation accepts, but what the
operation may change and how it behaves under failure.

## Capability versus API Endpoint

An API endpoint answers, "Where do I send this request?" A capability answers a
larger set of questions:

- What business operation does this perform?
- What input and output are valid?
- Does it read, write, delete, send a message, move money, or change identity?
- Is retry safe, and is an idempotency key required?
- Can it stream or be cancelled?
- What data classification applies?
- Is approval required?
- Can the operation be planned, committed, or compensated?

A connector may call several provider endpoints to implement one AIP
capability. Conversely, one provider endpoint may produce several capabilities
with different policy contracts.

## What a Manifest Publishes

Every capability has these core fields:

| Field | Purpose |
|---|---|
| `id` | Stable identifier used by actions |
| `name` | Short operation name for people and clients |
| `kind` | `agent`, `tool`, `workflow`, `channel`, `resource`, or `human_task` |
| `input_schema` | JSON Schema for accepted input |
| `output_schema` | Optional JSON Schema for structured output |
| `description` | Clear statement of the operation and its limits |
| `risk` | `low`, `medium`, `high`, or `critical` |
| `stability` | `stable`, `experimental`, or `deprecated` |
| `bindings` | Profile-specific projections, such as an MCP tool name |
| `contract` | Enterprise execution and governance semantics |

Capability ids are deployment-stable strings. Use a namespace that identifies
the owner and operation, for example `cap:billing:refund` or
`cap:calendar:booking:create`.

## The Capability Contract

The contract is one object with the following sections.

### Side effects

`side_effects` states what a caller must assume even if the operation name is
ambiguous. Values include `read`, `write`, `delete`, `send_message`,
`financial`, `identity`, `medical`, `legal`, `external_network`, and
`code_execution`.

Declare every applicable effect. A refund normally has both `write` and
`financial`; sending a support reply has `send_message` and often
`external_network`.

### Idempotency

The idempotency contract defines:

- whether a key is `required`, `optional`, or `unsupported`;
- whether a duplicate returns the original result, is rejected, or is accepted
  only when the input hash still matches;
- whether uniqueness is scoped to the action, capability, principal, tenant,
  or external account;
- how long a reservation is retained.

This declaration prevents a generic retry loop from repeating a payment or
message send that the provider cannot deduplicate.

### Execution

The execution contract publishes support for synchronous, asynchronous,
streaming, cancellation, and retry behavior. `retry_safety` is separate from
`supports_retry`: a provider may expose a retry operation while still requiring
an idempotency key before it is safe to use.

### Data

The data contract declares sensitivity, possible PII, redaction requirements,
residency limits, and retention. These values let policy reject a cross-region
delegation or prevent sensitive input from entering logs.

### Credentials

The credential policy declares accepted issuers and required scopes. It carries
references and lifecycle metadata, never raw tokens or client secrets.

### Approval

The approval policy can require a principal, trusted role, group, tenant
policy, external approval system, quorum, or a composed rule. It also captures
TTL, evidence, separation of duties, and policy version.

### Service level

SLA fields help the runtime select sync or async execution, set deadlines, and
detect excessive queue delay. They are operational expectations, not a promise
that a failed provider will become available.

### Transaction and compensation

The transaction contract advertises support for `dry_run`, `plan`, `commit`,
`compensate`, and related modes. The compensation contract identifies whether a
reversal is supported, best effort, unnecessary, or impossible.

## Minimal Does Not Mean a Different Protocol

A read-only MCP tool may be projected into AIP with a conservative contract:
`read`, unknown data sensitivity, and only the execution behavior actually
observed. A native enterprise connector can publish all sections. Both use the
same `Capability` type and action lifecycle.

The runtime must never invent stronger guarantees than a provider declares. If
retry safety, compensation, or data sensitivity is unknown, policy should use
the conservative interpretation.

## Authoring Checklist

Before publishing a capability, verify that:

- input and output schemas reject unknown or malformed fields as intended;
- every real side effect is declared;
- idempotency behavior matches the downstream provider;
- streaming and cancellation are advertised only when implemented end to end;
- approval policy is evaluated from trusted identity data;
- transaction modes map to real provider semantics;
- errors are normalized without losing provider correlation ids;
- sensitive values are excluded from manifests, logs, receipts, and callbacks.

See [Approvals and Policy](approvals-and-policy.md) and
[Transactions and Compensation](transactions-and-compensation.md) for the
governed execution flows.