> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# v3 Concepts

> Accounts, tool discovery, nouns, verbs, Pages, and safety in the v3 agent contract.

## One connection, account-resolved tools

v2 chooses a persona through the URL. v3 connects to one URL and resolves its
catalog from the active account. A person who can administer an organisation,
sell from a Seller Account, and buy through multiple Buyer accounts can move
between them without registering multiple MCP servers.

The active account is durable session context. Always begin with `get_status`,
and call it again after `switch_account`.

## Orientation is always available

`get_status` returns:

* the active account and account kind;
* readiness and transaction state when available;
* blockers and typed next actions;
* ready buyer destinations where applicable; and
* a bounded list of reachable accounts that says when it is truncated.

`get_status` and `switch_account` remain available outside the preview cohort.
This is a navigation exception, not access to unenrolled account data.

## Nouns and verbs

v3 uses a small verb vocabulary over account-owned nouns:

| Verb          | Contract                                                                                 |
| ------------- | ---------------------------------------------------------------------------------------- |
| `search`      | List or search one supported `kind`, with kind-specific filters and pagination           |
| `get`         | Read one object by ID, or a singleton kind without an ID, with optional `include` detail |
| `save_<noun>` | Create or update one noun through a noun-specific schema                                 |
| Domain action | Perform work that is not a state declaration, such as `request_proposals`                |
| `open_page`   | Hand interactive, sensitive, or human-authorized work to an MCP App Page                 |

Reads can share a safe envelope. Writes cannot: each `save_<noun>` has its own
schema so a model does not choose an operation name and then guess the body.

## Tool discovery is part of the contract

The catalog may differ by:

* account kind;
* enrollment;
* permissions;
* feature rollout; and
* MCP App support in the host.

Treat `tools/list` as the source of truth for names and JSON Schemas in the
active account. The [tool catalog](/v2/setup/v3/tool-reference) explains the
stable families and intended workflows; it does not replace runtime discovery.

When an account switch changes the catalog, v3 emits
`notifications/tools/list_changed`. If a client misses the notification, a
wrong-account call returns a typed error that names the required account kind
and an eligible `switch_account` call.

## Tasks, Pages, and model visibility

Some work should not be represented as model-authored fields. OAuth grants,
credentials, payout destinations, legal acceptance, and certain review actions
belong in a human-facing Page.

* A model-facing tool may return a Page as the next action.
* `open_page` opens a named Page with bounded focus parameters.
* Resource-bound MCP App tools may be present on the wire but hidden from model
  context by their visibility metadata.

Do not bypass a Page by placing credentials, bank details, or authorization
decisions in another tool's free text.

## Declarative writes

A `save_<noun>` call states the desired noun state. Responses distinguish:

* `created` or `updated` — a write occurred;
* `unchanged` — the current state already matched;
* `pending_approval` — a governed change was proposed, not committed; and
* an error or partial-write result — the response explains what did and did not
  persist.

Send patches, not reconstructed whole objects, unless a schema explicitly asks
for replacement. Preserve returned identifiers exactly. Qualified product and
proposal IDs encode seller routing and must not be shortened or rebuilt.

## Concurrency and idempotency

These mechanisms answer different questions:

* `expectedRevision` prevents overwriting a newer object state. Re-read after a
  `REVISION_CONFLICT` and decide whether the intended change still applies.
* `idempotencyKey` deduplicates one logical attempt where the tool promises it.
  Reusing a key for different intent is an error; inventing a new key for every
  retry can duplicate work.
* `correlationId`, where offered, is a tracing handle and is not necessarily an
  idempotency key.

Use the exact semantics in each tool's runtime schema and workflow guide.

## Includes keep diagnostics attached to the object

Health, sync history, and capability evidence are facts about a resource, so
they are generally requested through `get.include`:

```json theme={null}
{
  "kind": "inventory_source",
  "id": "SOURCE_ID",
  "include": ["diagnostics"]
}
```

Successful facts remain available when another requested include cannot be
resolved. A response marks unsupported or partial detail instead of presenting
it as an empty result.

## Pagination and completeness

Pass the returned opaque `nextCursor` back to the same query while `hasMore` is
true. Do not edit, reuse across kinds, or interpret a cursor. A partial response
must say what was not reached; an empty `items` array alone is not evidence that
the underlying system contained no results.