> For the complete documentation index, see [llms.txt](https://wiki.4thtech.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.4thtech.io/developers/technical/mcp-tools.md).

# MCP tools

> **Status: Current for v0.5.10.** 16 tools, pinned by a committed tool-surface snapshot (`apps/cli/test/fixtures/tool-surface.json`). The tool names and inputs did not change in 0.5.10. This page lists the tool surface from D-53 and D-55 and [06 MCP server](https://github.com/4thtech/agentlink/blob/v0.5.16/specs/06-mcp-server.md). Names and schemas may change before 1.0.0.

**Package:** `@4thtech-io/agentlink`, subcommand `agentlink mcp` (stdio). The self-hosted cloud agent exposes the same tools over streamable HTTP with OAuth.

## Design rules

* **Same tools everywhere**: local and cloud expose identical names, schemas and annotations.
* **Status-driven results**: every tool returns `status` (`ok`, `submitted`, `pending_approval`, `needs_setup`, `needs_credits`, `not_found`, `rejected`, `error`), a one-sentence summary and, when not `ok`, a `nextStep`.
* **No dangerous tools**: no tool changes policies, exports keys, adds storage credentials, decides approvals or reads arbitrary files.
* **Untrusted inbound content** is always wrapped in an `<untrusted_content>` block.
* **Idempotency**: mutating tools accept an optional `clientRequestId`.
* **Approvals**: a tool that can return `pending_approval` accepts `approvalId`; an approved ID lets the identical action proceed once. For terms, one approval covers the acceptance and its Accepted receipt, bound to the exact terms, contact, conversation and expiry, and is void if the terms change.
* **Terms**: offers, counters, acceptances and rejections go only through `agentlink_propose_terms` and `agentlink_respond_to_terms`, with typed terms fields.

## Tools

| Tool                          | Read-only             | Approval policy                                                               | Since                                                           |
| ----------------------------- | --------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `agentlink_status`            | yes                   | —                                                                             | v0.1.0 (credits and prices since v0.2.0)                        |
| `agentlink_create_invite`     | no                    | —                                                                             | v0.1.0                                                          |
| `agentlink_accept_invite`     | no                    | `contacts.acceptInvites`                                                      | v0.1.0                                                          |
| `agentlink_list_contacts`     | yes                   | —                                                                             | v0.1.0                                                          |
| `agentlink_send`              | no                    | `proofs.*` with `notarize`                                                    | v0.1.0 (`path` and `notarize` since v0.2.0; `file` since 0.5.5) |
| `agentlink_propose_terms`     | no                    | `commitments.accept` and `proofs.*` with `notarize` (firm offer)              | v0.1.0 (`notarize` and firm offers since v0.2.0)                |
| `agentlink_respond_to_terms`  | no                    | `commitments.accept` (one approval per agreement); `proofs.*` with `notarize` | v0.1.0 (`notarize` and recorded accepts since v0.2.0)           |
| `agentlink_inbox`             | no (marks items read) | —                                                                             | v0.1.0                                                          |
| `agentlink_get_approval`      | yes                   | —                                                                             | v0.1.0                                                          |
| `agentlink_fetch_file`        | no (saves a file)     | —                                                                             | v0.2.0                                                          |
| `agentlink_notarize`          | no                    | `proofs.*`                                                                    | v0.2.0                                                          |
| `agentlink_acknowledge`       | no                    | `commitments.accept` (records without terms)                                  | v0.2.0                                                          |
| `agentlink_get_proof`         | yes                   | —                                                                             | v0.2.0                                                          |
| `agentlink_export_proof_pack` | no (writes a file)    | `proofs.allowKeyDisclosure`                                                   | v0.2.0                                                          |
| `agentlink_verify_proof_pack` | yes                   | —                                                                             | v0.2.0                                                          |
| `agentlink_tidy`              | yes (counts only)     | In the app: the owner approves the exact list with Touch ID                   | 0.5.4                                                           |

## File tools

* **`agentlink_send` with `path`** (06 §2.2, §2.3): `path` is the full path of one file (`~/` allowed; 1 to 4096 characters, no control character). `text`, `body` or `path` is required; `text` and `body` exclude each other. Before the core is called, the path is resolved with realpath and must be strictly inside a `files.allowedFolders` entry (04 §4); the file is not opened. Results: `needs_setup` with `NO_ALLOWED_FOLDER` or `OUTSIDE_ALLOWED_FOLDER` (also for a link that points outside); `rejected` `PATH_NOT_ALLOWED` (relative, `.` or `..`, hidden, protected, not a regular file); `not_found` `FILE_NOT_FOUND`; `needs_setup` `NEEDS_OWN_STORAGE` (above the drop's size or weekly limit, or `files.storage: own` with none set up); `rejected` `FILE_TOO_LARGE`, `PAYLOAD_TOO_LARGE`, `POLICY_DENIED`; `error` `STORAGE_UNAVAILABLE`, `STORAGE_FAILED`, `FILE_CHANGED`, `FILES_UNAVAILABLE`. On `ok`, `file` is `{name, size, plaintextSha256, delivery: inline | drop | own, expiresAt}`: never a link, a locator or a key.
* **`agentlink_fetch_file`** (06 §2.3): `{envelopeId, fileIndex? = 0}` (0 to 15). On `ok`: `{savedTo, name, size, integrity: "verified", kind, untrusted?: {content}}`; `name` and the last segment of `savedTo` are the sender's sanitised text, so the text result shows the name only inside the untrusted block. `kind` (`markdown | text | code | json | patch | image | other`) is derived from the name only, never from the sender's MIME type. Since 0.5.1, a text-kind file of at most 64 KB (valid UTF-8, no NUL, matching the payload's plaintext hash and size) also returns its text as `untrusted.content` and in a second untrusted block; larger or binary files return the path only. Refusals: `not_found`; `rejected` `FILE_TOO_LARGE`, `INTEGRITY_FAILED`, `LINK_EXPIRED`, `URL_REFUSED`, `POLICY_DENIED`; `error` `INBOX_UNAVAILABLE`, `DOWNLOAD_FAILED`, `FILES_UNAVAILABLE`. Annotations: not read-only (it writes a file), not idempotent (a file moved or changed since it was saved is saved again under a new name), open world.
* **`agentlink_inbox` files** (since 0.5.1): each file carries `kind` (derived from the name, as above) and, once the file is saved (automatically, by Save in the app or by `agentlink_fetch_file`), `savedTo`. The file line inside the block reads `File 0: plan.md (Markdown, 97 bytes)`; the sender's stated types stay under `untrusted.fileTypes`.
* **`agentlink_send` with `file: {name, content}`** (since 0.5.5, FILES-AI-1; 06 §2.3 "Send by content"): a small text file the AI wrote, saved into the user's Send folder first. `.md`, `.markdown`, `.txt` or `.json` up to 8 MiB; at most one of `path` and `file`. Refusals (nothing sent, nothing kept): `FILE_NAME`, `FILE_TYPE`, `FILE_NOT_TEXT`, `FILE_TOO_LARGE`, `FILE_NAME_TAKEN`, `SEND_FOLDER_UNAVAILABLE`, `FILE_BUDGET` (50 files and 64 MiB per ID per rolling 24 hours), `needs_setup` `NO_ALLOWED_FOLDER`, `POLICY_DENIED`. `file.name` in the result is the saved name. Details: [Files](https://wiki.4thtech.io/protocols/occ-v2/protocol/files.md#send-by-content-since-055-d-152).
* **`agentlink_send` with `path`** labels the file's type from its extension (fixed table, since 0.5.1).
* **`agentlink_status`**: `storage.mode` is where files above about 12 KB go under the current rules (`drop` or `own`).

## Received files and `agentlink_fetch_file` (since 0.4.6, D-142)

Files from contacts you keep are now saved automatically by the agent itself, without any tool call (see [Files](https://wiki.4thtech.io/protocols/occ-v2/protocol/files.md#automatic-saving-since-046)). `agentlink_fetch_file` still works with the same input, output and statuses and is your request, so the automatic-saving limits, the off switch and "Ask before saving" do not hold it back. It shares one lock per file with automatic saving and with Save in the app. When the file was already saved and the saved copy still hashes to the expected SHA-256 and size, it answers `{savedTo, name, size, integrity: "verified"}` from that copy without downloading again and without writing a second copy. If the copy was moved, deleted or changed, it downloads again under a new name while the link is valid.

## Naming a contact (since 0.5.1)

A tool that takes a contact (`to`) resolves it on your computer from the name the user said, an invite alias or an ID, and never guesses.

* **`error`** **`AMBIGUOUS_CONTACT`**: two or more contacts match. `candidates` lists each one with `id`, `name`, `label`, `nameSource`, `ownerFingerprint`, `shortId` and `connectedAt`, so same-named contacts can be told apart. The summary lists every option by those details and never by name alone. `nextStep` says to ask the user which one, to call again with its `id`, and that the owner can rename one on People in the AgentLink app (not in a terminal).
* **`error`** **`CONTACT_RENAMED`**: no contact has that name now, but one used to. The summary names the contact's current name; `candidates` carries its `id`. A previous name never acts: ask the user, then call again with the `id`.
* **`error`** **`CONTACT_BLOCKED`**: the owner blocked this contact. The text is fixed ("The owner blocked this contact, so nothing was done."), with no name and no candidates. Only the user can unblock, on People in the AgentLink app.

Removed and revoked contacts stay `not_found`. No tool renames, blocks, unblocks or removes a contact (I-4).

## Delivery (since 0.5.1)

`agentlink_send` returns `delivery` right after the first publish: `sent` once the relays accepted the message, `queued` while it waits for them (the summary then says it is not sent yet, for example when this computer can't reach the message network; the app sends it by itself when the network is back) and `not_delivered` when it was given up. The same holds when a proof is added with the message. A repeat with the same `clientRequestId` reads the state again.

## Paused agents (since 0.4.6, D-143 (5))

While the owner has paused an agent in the app, the tools that send or fetch (`agentlink_send`, `agentlink_acknowledge`, `agentlink_propose_terms`, `agentlink_respond_to_terms`, `agentlink_notarize`, `agentlink_create_invite`, `agentlink_accept_invite`, `agentlink_fetch_file`) return `rejected` with `code: "AGENT_PAUSED"` and the fixed `nextStep` "This AgentLink ID is paused. The owner can resume it in the AgentLink app." The call is refused before any effect, is not queued and is not kept under its `clientRequestId`, so the same call works after Resume. The read tools (`agentlink_status`, `agentlink_inbox`, `agentlink_list_contacts`, `agentlink_get_approval`, `agentlink_get_proof`, `agentlink_export_proof_pack`, `agentlink_verify_proof_pack`) answer from what the store holds with no relay fetch, and `agentlink_status` adds the same fixed line. No tool, argument, result field or annotation was added, and no tool or command pauses or resumes an agent (I-4). Pause is one click in the app with no Touch ID; Resume needs Touch ID and signs `agent.resume`.

## Proof tools

Proofs run on test networks only. They need the 4thTech proof submitter and test credits to be running; until then a proof stays `submitted` and is sent again later. The network is chosen automatically (D-40); no default input asks for one.

* **`agentlink_notarize`** (06 §2.4): `{envelopeId, requestReceipt?, approvalId?, clientRequestId?}` for a message this agent sent. The proof network is picked automatically. Only `agentlink mcp --advanced` adds `chain?`, an override (a supported network's key) used only when the user asks; an unknown one is `rejected` `UNSUPPORTED_CHAIN`. On the default surface a `chain` argument is refused with `INVALID_ARGUMENT` (M1-36h). Results (a ProofStatus: `recordId`, `fee {token, amount, usd}`, `receipts`, and the proof network only as `advanced.chain`): `ok`; `submitted`; `needs_credits` with `agentAddress` and `topUpUrl` (the deposit page, `https://pay.agentlink.4thtech.io/`; the link carries nothing else); `pending_approval` (policy `proofs.*`); `error` `USE_TERMS_TOOLS` for an `offer`, `accept` or `reject` (nothing is recorded), `RECORD_FAILED`, `RECORD_CONFLICT`, `CHAIN_UNAVAILABLE`, `PROOFS_UNAVAILABLE`, `NETWORK`; `not_found` `ENVELOPE_NOT_FOUND`; `rejected` `NOT_NOTARIZABLE`, `POLICY_DENIED`, `CARD_EXPIRED`, `UNSUPPORTED_CHAIN`, `APPROVAL_INVALID`, `POLICY_CHANGED`, and since 0.5.11 `SPEND_CEILING`, `CONTACT_WAITING_OWNER`, `FILE_CHANGED`.
* **`notarize` on `agentlink_send`** (06 §2.2): the message is sent, then recorded under the same `proofs.*` policy as `agentlink_notarize`. The result adds `proof` (a ProofStatus); a proof that is pending, submitted or short of credits gives the result its status, and a failed proof gives `error` with `proof.status: "error"` and a fixed code, with the send fields kept; the summary always says the message was sent. A `pending_approval` is finished with `agentlink_notarize` and the `envelopeId`; a repeat of `agentlink_send` with `approvalId` must carry the first call's `clientRequestId` (otherwise `INVALID_ARGUMENT`, nothing sent).
* **`notarize` on `agentlink_propose_terms` and `agentlink_respond_to_terms`** (06 §2.2a): accepted by the schema and passed to the core, which does not record offers or answers yet: `error` `NOTARIZE_UNAVAILABLE`, nothing sent or signed. Firm offers and recorded accepts come with v0.2.0.
* **`agentlink_acknowledge`** (06 §2.4): `{envelopeId, type: opened | accepted | rejected, approvalId?, clientRequestId?}` on a message a contact recorded. `opened` only when the user asked to open it. Results: `ok` `{recordId, receipt}`; `submitted` (signed, not on record yet); `pending_approval` (`commitments.accept` for accepted or rejected); `error` `USE_RESPOND_TO_TERMS` for a record with terms (nothing signed); `not_found` `NOT_RECORDED`, `ENVELOPE_NOT_FOUND`; `rejected` `RECEIPT_CONFLICT`, `POLICY_DENIED`, `APPROVAL_INVALID`.
* **`agentlink_get_proof`** (06 §2.4): exactly one of `envelopeId` and `recordId`. Read-only. A ProofStatus by the stored state: `ok`, `submitted`, `needs_credits`, `error`, or `not_found`.
* **`agentlink_export_proof_pack`** (06 §2.4, 07 §8): exactly one of `envelopeId` and `recordId`, plus `includeContentKey?` (default false; needs the owner's approval, `proofs.allowKeyDisclosure`) `includeRecipient?` (default false) and `includeDeviceReceipt?` (default false: adds the contact's automatic device receipt, which also discloses the recipient, since 0.5.10, D-156). Writes a new file into `proofs.exportFolder` (`~/AgentLink/Proofs` by default); nothing is written before the approval. On `ok`: `{savedTo, recordId}`, never the pack or a key. Refusals: `not_found` `NOT_RECORDED`, `ENVELOPE_NOT_FOUND`; `error` `RECORD_UNAVAILABLE` (a record a contact made), `EXPORT_FOLDER_UNAVAILABLE`; `rejected` `POLICY_DENIED`, `APPROVAL_INVALID`.
* **`agentlink_verify_proof_pack`** (06 §2.4, D-87): exactly one of `path` and `json`. `path` must be strictly inside `proofs.exportFolder` or `files.inboxFolder` (a relative path is below the proofs folder): a path outside both is refused before the disk is touched; then realpath, no hidden or protected files, no links, a regular file of at most 256 KiB. Refusals are `rejected` `PATH_NOT_ALLOWED`, `PACK_TOO_LARGE`, `PACK_INVALID`, with no path or content echoed. On `ok`: `{valid, verdict: verified | record_only | failed, advanced: {chain}, recordId, signer, signerName?, signerLabel?, timestamp, envelopeHash, receipts, contentVerified}`. `signerName` follows the contact-name rule: the contact's alias or restricted name, otherwise "Contact" with the short ID tag. `record_only` is never shown as a full pass (D-95). Disclosed content appears only inside the untrusted block. `error` `NETWORK` when the public record does not answer.
* **`agentlink_status`**: `credits` `[{usd, advanced: {chain, token, amount}}]` (network and token names only under `advanced`, D-40), `prices` `[{action: "notarize", usd, protocolUsd, integratorUsd, payFrom: "credits"}]` (the AgentLink part and the app part shown separately, G-43), `agentAddress` and `topUpUrl`. Read within about 3 seconds; left out when no network answers.

## Free up space: `agentlink_tidy` (since 0.5.4, RET-7, D-148)

`agentlink_tidy({olderThanDays: 30 | 90 | 365, kinds: "files" | "messages_and_files", contact?})` lets the AI **propose** a cleanup when the user asks to free up space. It never deletes anything:

* It counts what that filter would remove on this computer now (nothing is written or deleted) and always answers `pending_approval` with `proposal: {olderThanDays, kinds, messages: {count, bytes}, files: {count, bytes}, kept}`.
* The `url` opens the app's Settings › Storage with the same filter (`/settings/storage?tidy=files|both&days=…[&contact=0x…]`). The app shows the exact counts, and the delete runs only after the owner's Touch ID (or master code) and a 10-second Undo.
* Its `approvalId` names the proposal only: the tool takes no `approvalId`, there is nothing to call again, and `agentlink_get_approval` answers `not_found` for it.
* The filter is the only input: never message IDs or text from a message. A message asking the AI to "tidy everything" can at most produce a proposal the owner sees with its exact counts. No tool changes how long AgentLink keeps history; that is the owner's setting in Settings › Storage (`history.*`, owner-signed).

## Limits and waiting contacts (since 0.5.11, D-156)

No tool, argument or annotation was added; these are new results. None of them offers an approval, and no tool changes a limit or keeps a contact (I-4).

| Code                                 | Tools                                                                                       | Fields                                                                                                      | When                                                                                                                                                                                                                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BUDGET_BROKEN` (`rejected`)         | `agentlink_notarize`, `notarize` on `agentlink_send` and the terms tools                    | none                                                                                                        | The spending record cannot be read, so an approval could not let the proof through. Refused up front, no approval is requested, nothing is signed or charged; `nextStep` tells the AI to tell the user to save the limits again in Settings › Rules                                                                |
| `SPEND_CEILING` (`rejected`)         | `agentlink_notarize`, `notarize` on `agentlink_send` and the terms tools                    | `ceiling` (`per_action` or `daily`), `limitUsd`                                                             | A proof above `proofs.hardMaxPerActionUSD` or the rolling 24-hour `hardDailyUSD`. The summary names the limit ("This proof would cost more than your limit ($0.50 per proof), so nothing was recorded."); `nextStep` tells the AI to tell the user to change it in Settings › Rules and not to ask for an approval |
| `SEND_LIMIT` (`rejected`)            | `agentlink_send`                                                                            | `limit` (`messages_contact`, `messages_day`, `files_contact`, `files_day`, `file_mb_day`), `max`, `retryAt` | An `outgoing` cap is reached. Nothing is stored or sent, and the refusal is not kept under the `clientRequestId`. `nextStep`: try again after `retryAt`, or tell the user they can change it in Settings › Rules                                                                                                   |
| `INVITE_LIMIT` (`rejected`)          | `agentlink_create_invite`; `agentlink_accept_invite` when it runs without an owner approval | none                                                                                                        | Over `contacts.aiInvites` (3 open, 5 in any 24 hours by default; 0 turns AI invites off). AI invites expire after `expiryHours` (24)                                                                                                                                                                               |
| `CONTACT_WAITING_OWNER` (`rejected`) | `agentlink_send`, the terms tools, `agentlink_notarize`, `agentlink_acknowledge`            | none                                                                                                        | The contact paired through an AI-made invite and the owner has not pressed Keep. Fixed text, never the contact's name                                                                                                                                                                                              |

`agentlink_list_contacts` marks such a contact with `waitingForOwner: true` (absent otherwise). Its messages still arrive in `agentlink_inbox`.

An approved proof for a message with files is refused with `FILE_CHANGED` when a file's hash or size differs from what the owner saw on the card (SEC-CARD-FULLTEXT); nothing is signed or charged.

## Received acknowledgements (since 0.5.10, D-156)

The AgentLink app sends a signed "received" acknowledgement by itself, for each message it processed from a contact you keep. This is free, off-chain and needs no tool call. Nothing changed in the tool surface:

* No tool sends, turns off or changes it. The owner decides with the switch "Tell contacts when your AI receives a message" (Settings › Rules; policy `receipts.sendReceived`, on when absent; a per-contact setting is planned). See [Policies](https://wiki.4thtech.io/developers/technical/policies.md).
* `agentlink_acknowledge` is unchanged. It is still for `opened`, `accepted` and `rejected` records, and `delivered` on request.
* On-chain DELIVERED receipts stay opt-in (`receipts.autoDelivered`, default off).
* On the sender's side, a message shows as delivered only after such an acknowledgement or an on-chain DELIVERED receipt. See [Privacy of proofs](https://wiki.4thtech.io/protocols/occ-v2/protocol/privacy.md).

## Reading further

* [Policies](https://wiki.4thtech.io/developers/technical/policies.md), [Files](https://wiki.4thtech.io/protocols/occ-v2/protocol/files.md), [Records, receipts and proof packs](https://wiki.4thtech.io/protocols/occ-v2/protocol/proof.md)
* Source of truth: [06 MCP server](https://github.com/4thtech/agentlink/blob/v0.5.16/specs/06-mcp-server.md)
