Tool reference

Every one of the server's 221 tools, grouped by task, with its arguments, its answer, what it changes and who may call it. For developers writing a client or checking what an AI app or agent can do with a token.

Reading an entry

Each tool is listed under its name, which is also its anchor (/docs/mcp/tools/#instructions_publish). Under it:

Field What it says
Effect read: nothing anyone could later observe changes. write: it adds something, or changes what the product can restore. destructive: it deletes, overwrites or revokes what can't be restored, changes what other people or agents receive or may access, or raises what can be spent. Every tool that asks to confirm is one. The four MCP hints come from it
Idempotent Sending the same call again has no further effect. Every read is
Asks to confirm The tool uses the confirm contract, always or in the cases its description names: such a call answers needs_confirmation and changes nothing, and is made again with confirmToken once the person agreed. See Contracts
Who can call it People and agents; people only (no agent credential); instruction.md's staff; instruction.md's own apps; or instruction.md's own services. The last three are not callable by customers
Needs org:admin Listed only to a token that carries the scope org:admin. See What a token is shown
AI app scope When a person limited the AI app they connected, the scope its token needs for the tool to be listed
Plan The plans whose organizations may call it, when every call is gated: elsewhere the call answers limit_reached. A tool gated in some calls only (one argument, or a change that makes more agents) says so in its description, and a list that answers available: false on a plan without the feature has no badge
Rate limit The bucket its calls count against (Rate limits)
Arguments Its input schema's properties. Every input schema allows no other property (additionalProperties: false)
Answer The fields of a successful answer's structuredContent; those marked "always" are in every success. Any other field may come too. An error answer has error instead (Errors)

Of the 221 tools, 74 are reads, 80 writes and 67 destructive; 39 use the confirm contract, and 103 declare an output schema, which the gateway holds every successful answer to.

Not callable by customers

25 tools are listed here but can't be called with a customer's token:

  • instruction.md's own apps (13): tools the editor and the site call, such as the draft's live sync, presence and the support desk. They are listed only to instruction.md's first-party clients.
  • instruction.md's staff (4): app reviews and who staff are. They are refused to anyone who isn't staff.
  • instruction.md's own services (8): billing reconciliation, usage counting, cleanup. They are listed only to the platform's service accounts.

Each such entry says so under Who can call it.

Find and read

Who you are, which tools you have, and finding and reading instructions. Start every session with session_bootstrap.

session_bootstrap

See who you are and what you can do. Who you act for and what you can do here; call it first. Returns you, your organizations and their workspaces (your role in each, its plan, and an organization's addresses on the site), which server this is, the toolsets your token reaches (what your tool list holds), the skills to load first (skill:// addresses), your unread notifications, and what to do next. Changes nothing. For a tool your list doesn't show, use capabilities_search.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Loaded up front in Claude Code

No arguments.

Answer: server (object, always), me (object, always), orgs (object[], always), toolsets (string[], always), skills (string[], always), extension (object), unread (integer), instructions (string), next (string[], always).

Find a tool. Search this server's tools, resources, prompts and skills by what you want to do, in your own words ("share with my team", "roll back a release"). Returns the best matches, each with its kind, name, title, one-line use and toolset: of the tools, only those your token can call. Changes nothing. For who you are and which toolsets you have, use session_bootstrap.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Loaded up front in Claude Code
ArgumentTypeRequiredDescription
querystringyesWhat you want to do, in words.
limitintegerAt most this many matches (default 10, max 50).

Answer: matches (object[], always).

instructions_list

List instructions. List the instructions you can see, by organization, owner, workspace, project, folder, visibility, kind, tag, words in them (query), your favorites, shared with you, recently opened, or the trash; sorted by updated, title, created or relevance. Returns a page of summaries (20 by default; nextCursor for the next): id, owner/name, title, your role, the latest version's number and the draft's revision; detail full for all instructions_get has. Changes nothing. For finding them by meaning, not by their words, use instructions_search. For one in full, with its draft's text, use instructions_get.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Loaded up front in Claude Code. Opens the MCP App ui://instruction.md/browse
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
ownerstringAn organization's slug (the owner in owner/name).
workspaceIdstringThe workspace (ws_…).
projectIdstringA project (prj_…).
folderIdstringA folder (fld_…), or root for what is in no folder.
visibility"private" | "internal" | "public"Only this visibility.
kind"instruction" | "template"Only this kind (default instruction; templates_list lists the templates).
tagstringOnly with this tag.
querystringWords to search for: names, titles, descriptions, tags and published text.
favoritesbooleanOnly your favorites.
sharedWithMebooleanOnly the ones shared with you from elsewhere.
recentbooleanOnly the ones you opened recently, newest first.
deletedbooleanThe trash instead.
includeArchivedbooleanInclude archived ones (default true).
sort"updated" | "title" | "created" | "relevance"The order (default relevance with a query, else updated).
limitintegerAt most this many (default 20, max 200).
cursorstringThe nextCursor of the previous page.
detail"summary" | "full"How much of each item: summary (default) — id, owner, name, title, description, visibility, your role, latest.number, draft {revision, changed, pendingSuggestions}; full — all it has.

Answer: items (object[], always), nextCursor (string | null).

Find instructions by meaning. Search instructions by meaning: those about what you describe, even when they share no words with it, most similar first, each with its score and up to three of its best passages, which are what to quote when you write from what exists. Lists only what you may read, 10 by default. Changes nothing. For matching words, or filtering by where instructions are, use instructions_list.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-search
ArgumentTypeRequiredDescription
querystringyesWhat you are looking for, in your own words.
orgIdstringOnly this organization's.
workspaceIdstringOnly this workspace's.
limitintegerAt most this many instructions (default 10, max 50).
detail"summary" | "full"How much of each item: summary (default) — each instruction's summary as instructions_list has it, with its score and best passages; full — all it has.

Answer: query (string), items (object[], always).

instructions_get

Get an instruction. Get one instruction: its summary, your permission and role, what you may do (can), its refs and latest version, and its draft's state: its revision (what an edit sends as expectedRevision), pending suggestions and open threads; and its addresses on the site (web). With include ["draft"], the draft's text too (draft.text), if you may read the draft; over 100,000 characters, a link to instruction://{id}/draft instead. Records it among your recent ones; changes nothing else. For a released version's text, use instructions_versions_read. For finding instructions, use instructions_list.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Loaded up front in Claude Code. Opens the MCP App ui://instruction.md/draft. Answers of up to 150,000 characters stay in Claude Code's conversation
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
include"draft"[]What to add to the answer.

Answer: id (string, always), uri (string), owner (string, always), name (string, always), title (string), description (string), visibility (string), kind (string), orgId (string), workspaceId (string), workspaceName (string), projectId (string), projectName (string), folderId (string), folderName (string), tags (string[]), revision (integer), defaultRef (string), latest (object), draft (object), archived (boolean), deleted (boolean), trashId (string), favorite (boolean), permission (string), role (string), createdAt (string), updatedAt (string), origin (object), sourcePath (string), web (object), refs (object[], always), versions (integer), pendingProposals (integer), consumers (integer), can (object, always), links (string[]).

instructions_meta

Get an instruction's public facts. Use, from an app, for the public-safe facts of an instruction: owner, name, title, latest version, refs (instructions_get gives them with your role). Changes nothing.

  • Effect: read, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.

pages_get

Get a page of the site as you may see it. Use, from the site, for a page of it as you may read it (an instruction's, at a ref or version, its list of versions, its link by id, or an organization's): what isn't public too, when you may read it, drawn as the site draws a public one; a link by id, as where it is now, with only the query the studio reads at that view. One never released says so to whoever may read its draft, with the way to it; an organization's members also get its drive and settings. Answers not_found for anything else, whether it exists or not. Changes nothing; a read of what isn't public is recorded, as any read is.

  • Effect: read, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
pathstringyesThe page's address on the site: /{owner}/{name}, /{owner}/{name}@{ref}, /{owner}/{name}@v{N}, /{owner}/{name}/versions, /ins_{ULID}[@{sel}][/{view}][?query], or /{owner}.

templates_list

List templates. Use to see the templates you can start an instruction from, a page at a time (20 by default), optionally with their text. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
querystringWords to look for.
includeTextbooleanInclude each template's text.
limitintegerAt most this many (default 20, max 200).
cursorstringThe nextCursor of the previous page.

Answer: templates (object[], always), nextCursor (string | null).

Create and organize

Make an instruction, change its details, and keep it in projects and folders. Deleting moves it to the trash for 30 days; purging can't be undone.

instructions_create

Create an instruction. Create an instruction with its draft and no version yet: blank, from a template (templateId), or from a text you give (content: a document, a pasted prompt), in your personal workspace unless you name an organization, workspace, project or folder. Returns it, its address and the draft's revision (1); it stays a draft until instructions_publish releases it. Sent again with its idempotencyKey, it answers what it made. For your own copy of an instruction, keeping where it came from, use instructions_fork.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes. Opens the MCP App ui://instruction.md/draft
ArgumentTypeRequiredDescription
workspaceIdstringThe workspace (ws_…).
orgIdstringAn organization (its default workspace).
projectIdstringA project in the workspace.
folderIdstringA folder in the workspace.
contentstringThe text. Without it, a template's text or a blank document named by title.
templateIdstringA template to start from (ins_… or owner/name).
titlestringIts title; taken from the text's first heading when absent.
namestringThe URL name; made from the title when absent.
descriptionstringA one-line description.
visibility"private" | "internal" | "public"Who can read its versions (default: the org's policy, else private).
kind"instruction" | "template"What it is (default instruction).
tagsstring[]Tags.
source"blank" | "template" | "import" | "prompt" | "copy" | "migrate"Where the text came from.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: instruction (object, always), uri (string, always), draftRevision (integer, always), links (string[]).

instructions_update

Change an instruction's details. Use to change the title, description, tags, project, folder, license or fork policy. Changes its details, not its text (which ref readers get by default is instructions_refs_set's makeDefault).

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
expectedRevisionintegerThe instruction's revision you read (instructions_get).
patchobjectyesWhat to change.

instructions_rename

Rename the URL name. Use to change the name in the instruction's address (owner/name). The old name keeps redirecting for good, and no one else can take it.

  • Effect: write, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
namestringyesThe new name: lowercase letters, digits and hyphens.

instructions_archive

Archive or unarchive. Use to freeze an instruction read-only (its versions stay readable and followed), or to unfreeze it.

  • Effect: write, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
archivedbooleantrue archives, false unarchives (default true).

instructions_duplicate

Duplicate an instruction. Use to copy an instruction's current text into a new one in the same or another folder. Creates a new instruction with no versions.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
folderIdstringWhere the copy goes (default: the same folder).
titlestringIts title (default: "<title> copy").
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

instructions_delete

Move to the trash. Use to move an instruction to the trash; it can come back for 30 days. Agents following it keep their last version; asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

instructions_undelete

Restore from the trash. Use to bring an instruction back from the trash, or everything deleted together with a folder or project (its trashId). Restores them where they were, a folder or project under a free name when another took its own meanwhile (renamed says which).

  • Effect: write, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
trashIdstringEverything deleted together (trh_…).

instructions_purge

Delete for good. Use to delete an instruction in the trash for good: its draft, versions and history. Can't be undone; refused under legal hold; asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm. Claude Code asks the person before each call
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

folders_create

Create a folder. Use to make a folder in a workspace or project, optionally inside another folder. Folders organize; they grant nothing.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
workspaceIdstringyesThe workspace (ws_…).
namestringyesIts name (1–64 characters, no /).
parentIdstringThe folder it goes in.
projectIdstringThe project it belongs to.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

folders_rename

Rename a folder. Use to rename a folder. Changes only its name.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
folderIdstringyesThe folder (fld_…).
namestringyesIts new name.

folders_move

Move a folder. Use to move a folder under another folder, or to the top. What is inside moves with it.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
folderIdstringyesThe folder.
parentIdstringThe folder to move it into; absent: the top.

folders_delete

Delete a folder. Use to move a folder and everything in it to the trash, under one trashId instructions_undelete restores. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
folderIdstringyesThe folder.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

projects_create

Create a project. Use to make a project: a workspace's top-level group of folders and instructions. Creates an empty one.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
workspaceIdstringyesThe workspace (ws_…).
namestringyesIts name.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

projects_rename

Rename a project. Use to rename a project (to a name no other project in its workspace has). Changes only its name.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
projectIdstringyesThe project (prj_…).
namestringyesIts new name.

projects_delete

Delete a project. Use to move a project, its folders and its instructions to the trash under one trashId. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
projectIdstringyesThe project.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

me_favorites_set

Star an instruction. Use to star an instruction for yourself, or unstar it. Changes only your favorites (me://favorites).

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
onbooleantrue stars, false unstars (default true).

Edit drafts

Every instruction has one draft. An edit names the revision it was made on (expectedRevision). A Contributor's or an agent's edit lands as suggestions.

Example: a tools/call of instructions_draft_edit
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "instructions_draft_edit",
    "arguments": {
      "instructionId": "acme/refunds",
      "expectedRevision": 14,
      "ops": [
        {
          "op": "replace",
          "find": "over €200",
          "text": "over €150"
        },
        {
          "op": "insert",
          "afterHeading": "Exceptions",
          "text": "NEVER: refund a gift card.\n"
        }
      ]
    }
  }
}

instructions_draft_replace

Replace the draft's text. Replace the draft's whole text with a new one, made on the revision you read (expectedRevision). The differences become edits, after a checkpoint of the text it had (instructions_restore puts it back); as a contributor or an agent, or with asSuggestion, they land as suggestions a maintainer accepts. Returns the new revision and any suggestion ids; the text it has already answers changed: false. For a few precise changes, use instructions_draft_edit.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
expectedRevisionintegeryesThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.
contentstringyesThe whole new text: what the draft's accepted text should become.
asSuggestionbooleanMake the change as suggestions a maintainer accepts, even if you could edit directly. Agents suggest by default.

Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]), changed (boolean, always), reason (string).

instructions_draft_edit

Edit the draft. Edit the draft with precise operations, without sending its whole text: replace text by range or by quoting it (find), insert at the end of a section or after some text, delete, move or duplicate a section, set the name or a front-matter key. The ops are one change, made on the revision you read (expectedRevision, required: draft.revision from instructions_get); a stale one answers version_conflict. As a contributor or an agent, or with asSuggestion, they land as suggestions. Returns the new revision; sent again, it answers as it did. For a whole new text, use instructions_draft_replace.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes. Loaded up front in Claude Code
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
expectedRevisionintegeryesThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.
opsobject[]yesThe edits, applied in order.
asSuggestionbooleanMake the change as suggestions a maintainer accepts, even if you could edit directly. Agents suggest by default.

Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]).

instructions_draft_sync

Sync the draft document. Use from an editor that holds the draft as a Yjs document: send your state vector and your update, get back what you lack. Applies your update as yourself.

  • Effect: write, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-live
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
stateVectorstringYour document's state vector, base64.
updatestringYour changes since your last sync, one Yjs update, base64.

instructions_draft_discard

Discard the draft's changes. Use to make the draft the latest version's text again, after a checkpoint of it (its checkpointId, for an Undo through instructions_restore). Drops its pending suggestions too; maintainers only; asks for confirmation — unless the draft is that text already, when nothing changes and nothing is asked (changed: false).

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

instructions_restore

Put an older text back. Use to put a version's or a checkpoint's text back into the draft (a checkpoint's suggestions come back as suggestions). Takes a checkpoint of the draft first; maintainers only.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
versionIdstringA version: ver_…, v3, or a ref.
checkpointIdstringA checkpoint (chk_…).
expectedRevisionintegerThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.

instructions_checkpoints_create

Keep a checkpoint. Use to keep a checkpoint of the draft now (⌘S); checkpoints are otherwise automatic. Adds one to History.

  • Effect: write
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
messagestringA note for it.

instructions_presence_set

Say you are here. Use from an editor every 20 seconds while an instruction is open, and when its caret moves: others see who is here, and the draft's readers their carets (as the MCP Event md.instruction.presence). Expires after two minutes.

  • Effect: write, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-live
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
sessionstringyesThis window's id.
awarenessobjectThis window's Yjs awareness state: {clientId, clock, state} — its caret and selection as relative positions in the draft's text. At most 4 KB; a heartbeat without it keeps the last.
leavebooleanYou closed it.

Check

Run the reader a release uses on a stored draft, and the release checks a ref's gates can require.

instructions_validate

Check a draft. Check an instruction's draft with the reader a release uses: its diagnostics (code, severity, line, message: an error is what a release refuses), the capability families it needs and its spec version. By the instruction, so its text isn't sent again; content checks another text instead. Changes nothing. For a text that isn't stored (not saved yet, or with your suggestions in it), use spec_validate.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
contentstringText to check instead of the draft.

Answer: ok (boolean, always), diagnostics (object[], always), spec (string), requires (string[]), title (string | null), validator (string).

instructions_checks_run

Run the checks. Use before releasing, or before a ref that requires checks moves: validates the draft (or a version) and lints it for credentials, invisible characters and text that overrides a host's instructions. The result is kept for that text, so a version released from it carries it. Changes nothing else.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
versionIdstringA version (ver_…, vN), a ref, or draft (default draft).

Suggestions and comments

Suggested changes in the draft, and comment threads on it.

instructions_suggestions_create

Suggest a change. Suggest a change to the draft as marked text, attributed to you, for a maintainer to accept or reject: replace a range (from, to) or the first match of a phrase (find) with new text; empty text suggests deleting it, and with neither it goes at the end. Returns the suggestion's ids and the draft's revision. Sent again with its idempotencyKey, it answers what it made. For a remark rather than a change, use instructions_comments_create. For a whole text offered back, from a fork, use instructions_proposals_create.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
fromintegerThe start, a UTF-16 offset in the draft's text.
tointegerThe end.
findstringOr the exact text to change.
textstringyesWhat to put there; empty suggests deleting it.
expectedRevisionintegerThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]), suggestionIds (string[], always).

instructions_suggestions_accept

Accept suggestions. Accept suggestions on the draft, by id or all, as a maintainer: their text becomes the draft's, several at once after a checkpoint, so it can be undone. Returns the ids accepted and the draft's revision; ones accepted already answer changed: false. For leaving the draft as it was, use instructions_suggestions_reject.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
idsobjectyesWhich suggestions.
expectedRevisionintegerThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.

instructions_suggestions_reject

Reject suggestions. Reject suggestions on the draft, by id or all, as a maintainer: the draft stays as it was, and their marks go. Returns the ids rejected and the draft's revision; ones rejected already answer changed: false. For making their text the draft's, use instructions_suggestions_accept.

  • Effect: destructive, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
idsobjectyesWhich suggestions.
expectedRevisionintegerThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.

instructions_suggestions_withdraw

Withdraw your suggestion. Use to take back a suggestion you made. Removes its marks.

  • Effect: destructive, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
suggestionIdstringyesThe suggestion.

instructions_comments_create

Comment on the draft. Start a comment thread on words of the draft, quoting them exactly (quote) or by their range (from, to), optionally @mentioning people by handle; notifies its maintainers and whoever you mention. Returns the thread's id and the draft's revision. Sent again with its idempotencyKey, it answers what it made. For a change to the text itself, use instructions_suggestions_create. For an answer in a thread that exists, use instructions_comments_reply.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
quotestringThe exact words it is about.
fromintegerOr a range: the start.
tointegerThe end.
bodystringyesWhat you want to say.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: revision (integer, always), pendingSuggestions (integer), openThreads (integer), acceptedDigest (string), suggestions (string[]), links (string[]), threadId (string, always).

instructions_comments_reply

Reply to a comment. Reply in a comment thread of the draft (a resolved one opens again); notifies the thread's participants. Returns the message's id. Sent again with its idempotencyKey, it answers what it made. For a new thread, use instructions_comments_create.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
threadIdstringyesThe thread.
bodystringyesYour reply.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

instructions_comments_edit

Edit your comment. Use to change the words of a message you wrote. Marks it edited.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
threadIdstringyesThe thread.
messageIdstringyesThe message.
bodystringyesThe new words.

instructions_comments_delete

Delete your comment. Use to delete a message you wrote; a thread goes with its last message.

  • Effect: destructive, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
threadIdstringyesThe thread.
messageIdstringyesThe message.

instructions_comments_resolve

Resolve or reopen a thread. Use to mark a thread resolved, or with resolved: false to reopen it: contributors resolve their own, maintainers any. Hides it from the open list, or puts it back.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
threadIdstringyesThe thread.
resolvedbooleantrue resolves, false reopens (default true).

Proposals

A whole text offered back to an instruction, usually from a fork, reviewed and merged as a new version.

instructions_proposals_create

Offer a whole text back. Offer a whole text to an instruction as a proposal its maintainers review and merge: a fork's text offered back (sourceInstructionId), or any, with a one-line title and why. Notifies its maintainers. Returns the proposal; instructions_proposals_get shows what it changes. Sent again with its idempotencyKey, it answers what it made. For a change to a few words of the draft, use instructions_suggestions_create.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
contentstringyesThe proposed text.
titlestringyesWhat it changes, in a line.
rationalestringWhy.
sourceInstructionIdstringThe fork it comes from.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

instructions_proposals_update

Update a proposal. Use to change your proposal's text, title or rationale, or rebase it on the latest version. Changes the proposal.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
proposalIdstringyesThe proposal (prp_…).
contentstringNew text.
titlestringNew title.
rationalestringNew rationale.
rebasebooleanBase it on the latest version.
expectedRevisionintegerThe proposal's revision you read (instructions_proposals_get); a mismatch answers version_conflict with the current one.

instructions_proposals_review

Review a proposal. Use to approve a proposal, request changes, or comment. Records your review and notifies its author.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
proposalIdstringyesThe proposal.
verdict"approve" | "request_changes" | "comment"yesYour verdict.
commentstringWhat you say.

instructions_proposals_merge

Merge a proposal. Use to release an approved proposal's text as a new version. Moves latest (asking for confirmation) unless refs say otherwise.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
proposalIdstringyesThe proposal.
messagestringThe version message.
refsstring[]Refs to move (default: the default ref; [] for a quiet version).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

instructions_proposals_close

Close a proposal. Use to close a proposal (its author or a maintainer), or reject it (a maintainer). It stops being open.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
proposalIdstringyesThe proposal.
rejectbooleanReject rather than close.
commentstringWhy.

instructions_proposals_list

List proposals. List an instruction's proposals, newest first, optionally by state (active: open, approved or changes_requested). Returns a page (20 by default; nextCursor for more), each with its title, state, author, base and whether it is stale. Changes nothing. For one proposal, with what it changes, use instructions_proposals_get.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Opens the MCP App ui://instruction.md/browse
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
state"open" | "approved" | "changes_requested" | "merged" | "closed" | "rejected" | "active"Only this state; active is any not yet settled (open, approved or changes_requested).
limitintegerAt most this many (default 20, max 200).
cursorstringThe nextCursor of the previous page.

Answer: proposals (object[], always), nextCursor (string | null), instructionId (string).

instructions_proposals_get

Read a proposal. Read one proposal: what it changes, as a unified diff against the version it was based on, with counts; its reviews and state, and whether it is stale (a version came since). include ["texts"] adds the proposal's text, its base's and, when stale, the latest's. Changes nothing. For an instruction's proposals, use instructions_proposals_list.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Opens the MCP App ui://instruction.md/review. Answers of up to 150,000 characters stay in Claude Code's conversation
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
proposalIdstringyesThe proposal.
include"texts"[]What to add to the answer.

Answer: id (string, always), instructionId (string), uri (string), title (string), rationale (string), state (string, always), revision (integer), author (object), mine (boolean), sourceInstructionId (string), baseVersionId (string), baseNumber (integer), headVersionId (string), stale (boolean), contentDigest (string), size (integer), reviews (object[]), mergedVersionId (string), closedBy (object), closedAt (string), createdAt (string), updatedAt (string), diff (object, always), content (string), baseContent (string | null), latestContent (string), links (string[], always).

Release and refs

Make a version from the draft, move refs such as latest and stable, and read the past. Release (instructions_publish) is the same act the editor calls Publish.

Example: a tools/call of instructions_refs_set
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "instructions_refs_set",
    "arguments": {
      "instructionId": "acme/refunds",
      "ref": "stable",
      "versionId": "v3",
      "policy": {
        "requireChecks": true,
        "promote": {
          "from": "latest",
          "afterMinutes": 1440
        }
      }
    }
  }
}

instructions_publish

Release a version. Release the draft's accepted text as the next version (v1, v2 …) with a message. By default it moves the default ref (latest), so the agents following it switch, which it asks the person to confirm first (needs_confirmation); refs [] makes a quiet version nobody follows yet. The first release needs visibility: ask the person who may read it. Returns the version and the instruction; the same release sent again answers the version it made. For moving a ref to a version that exists, or rolling back, use instructions_refs_set. For releasing at a later time, use instructions_schedules_create.

  • Effect: destructive. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
messagestringWhat changed, for the people and agents that follow it.
refsstring[]Refs to move (default: the default ref, latest; [] for a quiet version).
expectedRevisionintegerThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
source"mcp" | "studio" | "ci" | "ai_assisted" | "cli"Where the change came from (default mcp).
visibility"private" | "internal" | "public"Who can read its versions: private (you and who you share it with), internal (its organization), public (everyone). Required on the first release; changing it later needs manage.

Answer: version (object, always), instruction (object, always), links (string[]).

instructions_refs_set

Point a ref at a version. Point a ref (latest by default, or stable, beta…) at a version, rolling back included; with makeDefault the ref also becomes the one readers get when they name none; policy replaces its gates: signed versions only, passed checks, who may move it, a timed promotion from another ref. Moving the default ref, or making another the default, asks for confirmation, since its followers switch. Returns the ref, its version and the one before; a ref there already answers changed: false. For releasing the draft as a new version, use instructions_publish.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
refstringThe ref (default latest).
versionIdstringyesThe version: ver_…, v3, or another ref (its own name keeps it where it is).
makeDefaultbooleanAlso make this ref the default one: what instruction://{id} reads when no ref is named, and what a new binding follows (default false). Needs manage.
policyobjectThe ref's gates, replacing the ones it has (changing them needs manage): requireSignature, requireChecks, allowedPublishers, promote {from, afterMinutes}.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Answer: ref (string, always), versionId (string, always), number (integer, always), previousVersionId (string | null), defaultRef (string), changed (boolean, always), reason (string), links (string[]).

instructions_refs_delete

Delete a ref. Use to delete a ref other than latest and the default ref. Agents following it hold their last version. A ref with gates takes manage and asks for confirmation: its gates go with it.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
refstringyesThe ref.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

instructions_refs_list

List refs. Use to see an instruction's refs, the version each points at and its gates (a page at a time, 50 by default), and the promotions of the last 30 days. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: instructionId (string), refs (object[], always), promotions (array), nextCursor (string | null).

instructions_versions_list

List versions. List an instruction's released versions, newest first: each one's number, message, author, the refs on it, and whether it is signed or revoked. Returns a page (20 by default; nextCursor for more); detail full adds digests, signatures and checks. Changes nothing. For a version's text, use instructions_versions_read. For what changed between two of them, use instructions_diff.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Opens the MCP App ui://instruction.md/browse
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
limitintegerAt most this many (default 20, max 200).
cursorstringThe nextCursor of the previous page.
detail"summary" | "full"How much of each item: summary (default) — id, number, message, authorName, refs, signed, revoked, createdAt; full — all it has.

Answer: versions (object[], always), nextCursor (string | null), instructionId (string).

instructions_versions_get

Get a version. Get one released version's facts: its number, message, author, refs, digest, signatures and checks, by its id (ver_…), number (v3) or a ref. Changes nothing. For its text, use instructions_versions_read.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
versionIdstringyesver_…, v3, or a ref.

instructions_versions_read

Read a version's text. Read a released version's text, by its id (ver_…), number (v3) or a ref (latest by default): as authored, with its digest and signatures; or, with resolve true, as delivered for the params you give — its bases and includes resolved from instructions you may read, the agent's text with its status (complete or partial) and a delivery signature. Records a read: in the audit, for what isn't public. For the draft's text (with include ["draft"]), use instructions_get. For which versions there are, use instructions_versions_list. For a version's facts without its text, use instructions_versions_get.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Answers of up to 150,000 characters stay in Claude Code's conversation
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
versionIdstringver_…, v3, or a ref (default latest).
resolvebooleanDeliver it: its parameters, bases and includes resolved.
paramsobjectParameter values.

Answer: instructionId (string), versionId (string, always), number (integer, always), digest (string), content (string, always), signatures (object | null), delivered (boolean), deliveredDigest (string), status (string), manifest (object), diagnostics (object[]), deliverySignature (string | null).

instructions_diff

Compare two texts. Compare two of an instruction's texts (versions by id or number, refs, or the draft) as a unified diff with the lines added and removed: from latest to the draft by default. Changes nothing. For which versions there are, use instructions_versions_list.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads. Answers of up to 150,000 characters stay in Claude Code's conversation
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
fromstringA version, a ref, or draft (default latest).
tostringA version, a ref, or draft (default draft).

Answer: from (string, always), to (string, always), unified (string, always), stats (object, always), fromDigest (string), toDigest (string), sameDigest (boolean).

instructions_versions_revoke

Revoke a version. Use to revoke a version no ref points at: agents pinned to it hold their last good one. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm. Claude Code asks the person before each call
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
versionIdstringyesThe version.
reasonstringWhy.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Schedules

A release or a ref move at a set time.

Example: a tools/call of instructions_schedules_create
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "instructions_schedules_create",
    "arguments": {
      "instructionId": "acme/refunds",
      "action": "set_ref",
      "ref": "stable",
      "versionId": "v4",
      "at": "2026-11-02T09:00:00+01:00"
    }
  }
}

instructions_schedules_create

Schedule a release. Schedule a release of the draft (action publish) or a ref's move to a version (set_ref) for a later time, a minute to 90 days ahead (at: ISO 8601 with its offset). It asks for confirmation now, since nothing asks then, and runs as you if you may still do it; a first release needs visibility. Returns the schedule; instructions_schedules_cancel cancels it before it runs. Sent again with its idempotencyKey, it answers what it made. For releasing now, use instructions_publish.

  • Effect: destructive. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
action"publish" | "set_ref"yesRelease the draft (publish) or move a ref (set_ref).
atstringyesWhen, ISO 8601 with its offset.
messagestringpublish: the version's message.
refstringset_ref: the ref (default latest).
versionIdstringset_ref: the version (ver_…, vN).
visibility"private" | "internal" | "public"publish: who can read its versions, applied with the release. Required when it will be the first; changing it needs manage.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

instructions_schedules_list

List scheduled releases. Use to see an instruction's scheduled releases and ref moves, and those of the last 30 days with what came of them (anyone who reads it), 20 a page by default. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
limitintegerAt most this many (default 20, max 200).
cursorstringThe nextCursor of the previous page.

Answer: schedules (object[], always), nextCursor (string | null), instructionId (string).

instructions_schedules_cancel

Cancel a scheduled release. Use to cancel a scheduled release or ref move before it runs. Nothing else changes.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
scheduleIdstringyesThe schedule (sch_…).

Who can read an instruction's versions (visibility), who has which permission on it (access), and signed read links.

Example: a tools/call of instructions_access_set
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "instructions_access_set",
    "arguments": {
      "instructionId": "acme/refunds",
      "grants": [
        {
          "handle": "maria",
          "permission": "suggest"
        },
        {
          "email": "sam@acme.example",
          "permission": "read"
        }
      ]
    }
  }
}

instructions_visibility_set

Set who can read it. Set who may read an instruction's versions: private (you and those it is shared with), internal (its organization) or public (anyone, signed in or not, and found in search). Making it public asks for confirmation, saying what that means; its draft, suggestions and comments stay with the people who work on it. Returns the instruction; the visibility it has already answers changed: false. For sharing it with particular people, agents or organizations, use instructions_access_set.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
visibility"private" | "internal" | "public"yesThe visibility.
expectedRevisionintegerThe instruction's revision you read (instructions_get); a mismatch answers version_conflict with the current one.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Answer: instruction (object, always), from (string), changed (boolean, always), reason (string), links (string[]).

instructions_access_list

See who has access. Use to see who has access to an instruction: its grants (a page at a time, 50 by default) and whether its workspace's roles apply. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
limitintegerAt most this many (default 50, max 500).
cursorstringThe nextCursor of the previous page.

Answer: instructionId (string), visibility (string), workspaceBaseline (boolean), revision (integer, always), workspace (object), grants (object[], always), pendingRequests (integer), nextCursor (string | null), links (string[]).

instructions_access_set

Change access. Share an instruction: give people (by handle, email or id), agents or a whole organization a permission (read, suggest, edit for agents, publish, manage), or none to take one away; the grants you don't name stay. workspaceBaseline says whether its workspace's roles apply too. Widening access asks for confirmation. Returns who has access now; what holds already answers changed: false. For making it private, internal or public as a whole, use instructions_visibility_set.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
grantsobject[]The grants to change (the others stay as they are).
workspaceBaselinebooleanWhether the workspace's roles apply.
expectedRevisionintegerThe access revision you read.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

instructions_access_requests_create

Ask for access. Use to ask an instruction's maintainers for more access (to read, suggest, or maintain), with a note. Notifies them.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
permission"read" | "suggest" | "publish"yesWhat you ask for.
messagestringA note.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

instructions_access_requests_list

List access requests. Use to see who is waiting for access to an instruction, and the requests answered in the last 30 days. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
state"pending" | "approved" | "denied" | "withdrawn"Only requests in this state (default: the pending ones and those answered in the last 30 days).
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: requests (object[], always), nextCursor (string | null), instructionId (string), links (string[]).

instructions_access_requests_resolve

Answer an access request. Use to approve (writing the grant) or deny an access request. Notifies the requester.

  • Effect: destructive, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
requestIdstringyesThe request (req_…).
approvebooleanyestrue approves, false denies.
permission"read" | "suggest" | "edit" | "publish" | "manage"The permission: read (Reader), suggest (Contributor), publish (Maintainer), manage (Admin); edit is for agents.

Make a read link. Use to make a signed, revocable link anyone can read a version or ref through, signed in or not: it opens as the text (markdown), or in a browser as a page. Returns the link once.

  • Effect: destructive
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
targetstringA ref, which the link then follows, or a version (default: its default ref).
labelstringWhat it is for.
expiresInintegerSeconds until it stops working (a minute to a year; default never).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

List read links. Use to see an instruction's read links (never their secret part), newest first, 50 a page by default. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
includeInactivebooleanInclude the revoked and expired ones (default: only the links that work).
limitintegerAt most this many (default 50, max 500).
cursorstringThe nextCursor of the previous page.

Answer: items (object[], always), nextCursor (string | null), instructionId (string).

Revoke a read link. Use to stop a read link working. Takes effect at once.

  • Effect: destructive, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
linkIdstringyesThe link (lnk_…).

Fork and transfer

A copy of your own that keeps its origin, and moving an instruction to another owner.

instructions_fork

Make your own copy. Make your own copy of an instruction you can read, keeping where it came from (origin): of the version its readers get, or another you name, in your personal workspace unless you name another workspace or organization. Returns the copy, its address and its draft's revision (1); offer changes back with instructions_proposals_create on the original. Sent again with its idempotencyKey, it answers what it made. For a new instruction from nothing, a template or a text, use instructions_create.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
workspaceIdstringWhere the copy goes (default: your personal workspace).
orgIdstringOr an organization: the copy goes to its default workspace.
folderIdstringA folder in that workspace.
versionIdstringWhich version: ver_…, vN or a ref (default: the one readers get, its default ref).
namestringThe copy's name.
titlestringThe copy's title.
visibility"private" | "internal" | "public"Who can read the copy's versions (default: its organization's policy, else private).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: instruction (object, always), uri (string, always), origin (object), license (string), draftRevision (integer, always), links (string[]).

instructions_transfer

Move to another organization. Use to move an instruction to another organization or workspace you administer. Its address changes (the old one redirects); asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
orgIdstringThe organization (org_…).
workspaceIdstringThe workspace (ws_…).
namestringIts name there.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Export

One instruction's versions, or everything you own, as a file.

instructions_export

Export an instruction. Use to take an instruction away as a file: md answers one version's text now. zip (every version with its record, its refs, the draft if you work on it) and oci (an OCI image layout, one manifest per version tagged vN and with its refs) are made in the background: the answer is a jobId at once, the file appears in me://exports (kept 7 days), and you are told in me://inbox. Changes nothing else.

  • Effect: write
  • Who can call it: People and agents
  • Rate limit: person-writes. Answers of up to 150,000 characters stay in Claude Code's conversation
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
format"md" | "zip" | "oci"What to make (default md).
versionIdstringmd: a version (ver_…, vN), a ref, or draft; default the default ref.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

me_export

Export your data. Use to export everything you own as a zip. Returns a jobId at once; the zip appears in me://exports (kept 7 days), and you are told in me://inbox.

  • Effect: write
  • Who can call it: People and agents
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Following

An agent declares what it follows (a binding), reports what it applied, and the people who manage an instruction see its consumers.

Example: a tools/call of instructions_bindings_create
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "instructions_bindings_create",
    "arguments": {
      "instructionId": "acme/refunds",
      "target": "stable",
      "mode": "follow",
      "consumer": {
        "name": "support-bot",
        "kind": "agentd",
        "host": "prod-eu-1",
        "version": "2.4.0"
      }
    }
  }
}

instructions_bindings_create

Follow an instruction. Follow an instruction, as an agent: a ref whose new versions you take (its default ref unless you name one, such as stable), or a version pinned, and who you are (consumer). Returns your binding and the address to read and subscribe to (instruction://{id}, or instruction://{id}@{ref}); after applying a version, say so with instructions_bindings_report. Following it again as the same consumer answers the binding you have (created false). For saying which version you applied, use instructions_bindings_report.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:follow
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
targetstringA ref (default the default ref), or a version id to pin.
mode"follow" | "pin"follow a ref, or pin a version.
host"claude-code" | "codex" | "claude-desktop" | "chatgpt" | "cursor" | "vscode" | "agentd" | "sdk" | "ci" | "other" | "copilot" | "gemini-cli" | "antigravity" | "qwen-code" | "opencode" | "kilo" | "droid" | "devin" | "pi" | "kiro" | "amp" | "cline" | "goose" | "junie" | "crush" | "zed" | "acp" | "aider" | "warp"The app the agent runs in (claude-code, codex…), when it says.
consumerobjectWho you are.
policyobjectWhat you refuse to apply.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

instructions_releases_list

Follow your releases (apps). Use as an app a person connected (instructions:all, or chosen instructions with instructions:follow): without a cursor, the latest released version of each instruction the person's grant follows, and a cursor; with one, every release, new instruction and removal since, in order. Released versions only; read each with instruction://{id}@{versionId}. The same as the MCP Event md.instruction.releases. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
cursorstringThe nextCursor of the previous answer; none: a snapshot now.
limitintegerAt most this many (default 100, max 500).

Answer: items (object[], always), nextCursor (string | null), snapshot (boolean, always).

instructions_bindings_list

List followers' bindings. Use to see your bindings to an instruction (everyone's, if you manage it), or without one all of yours. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
minebooleanOnly your own, even on an instruction you manage.
limitintegerAt most this many (default 25, max 500).
cursorstringThe nextCursor of the previous page.

Answer: bindings (object[], always), nextCursor (string | null), instructionId (string).

instructions_bindings_delete

Stop following. Use to remove a binding (yours, or any if you manage the instruction). Stops counting it as a consumer.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:follow
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
bindingIdstringyesThe binding (sub_…).

instructions_bindings_report

Report what you applied. Report, as an agent, the version you applied from what you follow, with the digest of what you received, so its maintainers see who holds what, who is behind and from which app (host: claude-code, codex…; instructions_consumers_list). Name your binding when you follow it as more than one consumer. Returns your binding; the same report again answers changed: false. For starting to follow it, use instructions_bindings_create.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:follow
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
bindingIdstringYour binding (sub_…); needed when you follow the instruction from more than one consumer.
versionIdstringyesThe version you applied.
deliveredDigeststring | nullThe digest of what you received (sha256:…); null or absent: the version's own.
clientobjectThe software that applied it.
host"claude-code" | "codex" | "claude-desktop" | "chatgpt" | "cursor" | "vscode" | "agentd" | "sdk" | "ci" | "other" | "copilot" | "gemini-cli" | "antigravity" | "qwen-code" | "opencode" | "kilo" | "droid" | "devin" | "pi" | "kiro" | "amp" | "cline" | "goose" | "junie" | "crush" | "zed" | "acp" | "aider" | "warp"The app the agent runs in, where it applied the version (claude-code, codex…): its maintainers see how many follow it from each. Not the machine (consumer.host).

instructions_bindings_pause

Pause delivery. Use to pause delivery to one consumer: it keeps its last version and is told. Maintainers only.

  • Effect: destructive, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
bindingIdstringyesThe binding.
reasonstringWhy, for the consumer (kept with the event it is told by).

instructions_bindings_resume

Resume delivery. Use to resume delivery to a paused consumer. It gets the current version again.

  • Effect: write, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
bindingIdstringyesThe binding.
reasonstringWhy, for the consumer (kept with the event it is told by).

instructions_consumers_list

See who follows it. Use to see who follows an instruction, what each holds, who is behind, and who is live. consumers lists every reader from what it did (its last read is the version it has; a binding's report adds confirmed), and bindings the declared followers. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
state"live" | "recent" | "declared"Only these.
refstringOnly followers of this ref.
limitintegerAt most this many (default 25, max 500).
cursorstringThe nextCursor of the previous page.

Answer: instructionId (string), counts (object), bindings (object[], always), live (array), hosts (object), consumers (array), liveUpdates (object), nextCursor (string | null), links (string[]).

Deployments

Deployment rules that make an agent for every instruction they select, the agents they made, and what a runner reports.

Example: a tools/call of deployments_rules_create
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "deployments_rules_create",
    "arguments": {
      "orgId": "acme",
      "name": "Support on agentd",
      "platform": "agentd-prod",
      "selector": {
        "project": "prj_01JX0000000000000000000000",
        "tags": {
          "all": [
            "support"
          ]
        }
      },
      "controls": {
        "onRelease": "live",
        "maxAgents": 20
      }
    }
  }
}

deployments_rules_create

Run a scope's instructions on a platform. Use to run every instruction of a scope as agents on a platform you name (laptop, agentd-prod), one each: a project, a folder (deep: with subfolders), tags, a list or a workspace, AND-combined, only what you can read. Instructions entering the scope later get an agent; leaving, it is retired (controls.onLeave). Team plan and above; admins. Returns the rule and what it runs (preview); in an organization new agents wait for approval unless onCreate is start. For seeing what a selector takes before saving it, use deployments_rules_preview. For running one instruction, use deployments_create.

  • Effect: write
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Team and Enterprise

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
namestringyesWhat the rule is for ("Support on agentd").
platformstringyesWhere its agents run: a short label (laptop, agentd-prod).
selectorobjectyesWhich instructions: project, folder {id, deep}, tags {all, any}, instructions, workspace — AND-combined, at least one — narrowed by visibility, with exclude {instructions, tags}.
controlsobjectHow it runs: ref, onRelease, onCreate, onLeave, maxAgents, parameters, budget, requireSignature, answerWithin.
workspaceIdstringOnly instructions of this workspace (ws_… or its slug).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: rule (object, always), preview (object), links (string[]).

deployments_rules_update

Change a deployment rule. Use to rename a rule, change what it selects or its controls (merged; a control set to null goes back to its default), or pause it: a paused rule makes and changes nothing, its agents keep running at their version, and releases wait until it resumes. Its agents follow at once (a new ref or parameters reach each). Returns the rule and its preview; the same change again answers changed: false.

  • Effect: write, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
ruleIdstringyesThe rule (dpr_…).
namestringIts new name.
selectorobjectWhich instructions: project, folder {id, deep}, tags {all, any}, instructions, workspace — AND-combined, at least one — narrowed by visibility, with exclude {instructions, tags}.
controlsobjectHow it runs: ref, onRelease, onCreate, onLeave, maxAgents, parameters, budget, requireSignature, answerWithin.
pausedbooleanPause it (true) or resume it (false).

Answer: rule (object, always), preview (object), fields (string[]), changed (boolean), reason (string).

deployments_rules_delete

Delete a deployment rule. Use to delete a rule: its agents are retired (their runners stop them), or kept when its onLeave is keep. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
ruleIdstringyesThe rule (dpr_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Answer: ruleId (string, always), deleted (boolean, always), retired (integer), kept (integer).

deployments_rules_list

List deployment rules. Use to see an organization's deployment rules, a page at a time: each with its scope, controls, platform and how many agents it has in each state. available says whether its plan has rules (Team and above). Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
platformstringOnly rules of this platform.
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: rules (object[], always), nextCursor (string | null), orgId (string), available (boolean).

deployments_rules_get

Read a deployment rule. Use to read one rule with its agents (those of instructions you can read: state, version, drift, last report) and the instructions it refused for maxAgents. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
ruleIdstringyesThe rule (dpr_…).
retiredbooleanInclude retired agents (default false).

Answer: rule (object, always), deployments (object[], always), refused (object[]), links (string[]).

deployments_rules_preview

Preview a deployment rule. Use to see what a selector would run now, as you can read the organization, without saving: the instructions in scope (owner/name, title, the version the ref names, whether each gets an agent), how many agents (maxAgents counted) and how many aren't released yet. Changes nothing. For saving it as a rule, use deployments_rules_create.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
selectorobjectyesWhich instructions: project, folder {id, deep}, tags {all, any}, instructions, workspace — AND-combined, at least one — narrowed by visibility, with exclude {instructions, tags}.
controlsobjectHow it runs: ref, onRelease, onCreate, onLeave, maxAgents, parameters, budget, requireSignature, answerWithin.
workspaceIdstringOnly instructions of this workspace.

Answer: orgId (string), selector (object), controls (object), available (boolean), instructions (object[], always), count (integer), agents (integer, always), overLimit (integer), unreleased (integer), maxAgents (integer), truncated (boolean).

deployments_create

Deploy an instruction. Use to run one instruction as an agent on a platform you name (laptop, agentd-prod), following a ref (its default ref unless named): Deploy to… Pro plan and above; needs manage on it. Started at once by an organization's admin or in your own organization, else it waits for an admin's approval. The same instruction and platform again answers the deployment it has (created: false). For running every instruction of a scope, use deployments_rules_create.

  • Effect: write
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Pro, Team, and Enterprise

ArgumentTypeRequiredDescription
instructionIdstringyesThe instruction: its id (ins_…), owner/name, or instruction:// address.
platformstringyesWhere its agent runs: a short label (laptop, agentd-prod).
refstringThe ref its agent follows (default the instruction's default ref).
parametersobjectParameter values for this deployment (an object, at most 16 KB).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: deployment (object, always), created (boolean, always), links (string[]).

deployments_list

List deployments. Use, as a runner (instruction-agents fleet, agentd), to read the agents to run: an organization's deployments, or one rule's (with its controls), on a platform, of instructions you can read. Each has the instruction, its ref, the version the ref names now (version), the one the agent may run (approvedVersion; a release waiting for approval is pendingVersion), parameters, state and onRelease. Without state, every one not retired. Changes nothing. For saying what an agent runs, use deployments_report.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
ruleIdstringOnly this rule's (dpr_…).
platformstringOnly this platform's.
state"pending_approval" | "active" | "paused" | "retired"Only these.
limitintegerAt most this many (default 100, max 500).
cursorstringThe nextCursor of the previous page.

Answer: deployments (object[], always), nextCursor (string | null), orgId (string), platform (string), rule (object).

deployments_approve

Approve a deployment. Use to approve what waits on a deployment: a new agent (it starts) or a release held for approval (its agent takes that version). Admins of its organization. Nothing waiting answers changed: false.

  • Effect: destructive, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
deploymentIdstringyesThe deployment (dep_…).
versionIdstringThe version approved: the pending one for a release; for a new agent, the one it starts at (default what its ref names).

Answer: deployment (object, always), approved (string), changed (boolean), reason (string).

deployments_retire

Retire an agent. Use to retire one deployment's agent: its runner stops it. One a rule made is left out of the rule from now on (its selector's exclude). Admins of its organization; retired already answers changed: false.

  • Effect: destructive, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
deploymentIdstringyesThe deployment (dep_…).

Answer: deployment (object, always), excluded (boolean), changed (boolean), reason (string).

deployments_report

Report a deployment. Report, as a runner, what one deployment's agent does: running, the version it applied, its health and last error, the app it runs in (host). Kept as the deployment's observed state (drift shows when it isn't the approved version) and as your binding to the instruction, so its consumers list shows it. The same report again answers changed: false. For reading the agents to run, use deployments_list.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:follow
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
deploymentIdstringyesThe deployment (dep_…).
runningbooleanyesWhether its agent runs now.
versionIdstringThe version it applied (ver_… or vN).
health"ok" | "degraded" | "failed" | "needs_sign_in"How it is doing; needs_sign_in: held back, or stopped, until something in needs is given.
errorstringIts last error (the last lines of its output), at most 2,000 characters.
hoststringThe app the agent runs in: claude-code, codex, agentd…
needsobject[]What the agent needs before it can run, at most 20 (RFC-0058). At most 20 items.
activityobject[]What the agent said and did since the last report: at most 20 lines, added to its conversation (RFC-0059). At most 20 items.
subagentsobject[]The subagents the agent started in its current task, at most 20, the newest last (RFC-0059 §10); an empty list: none now. At most 20 items.
sealedErrorstringSealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused.
remoteobjectWhere the agent is controlled in its own app (RFC-0059 §11: Claude Code's Remote Control); absent: not there.

Answer: deployment (object, always), changed (boolean, always), bindingId (string).

Conversations

An agent's questions and permission requests to its people, and messages to a running agent.

Example: a tools/call of deployments_asks_create
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "deployments_asks_create",
    "arguments": {
      "deploymentId": "dep_01JX0000000000000000000000",
      "kind": "permission",
      "tool": {
        "name": "Bash",
        "input": {
          "command": "git push origin main"
        },
        "description": "Push the fix"
      }
    }
  }
}

deployments_asks_create

Ask a person, for an agent. Use, as the runner of a deployment's agent, to ask the people who answer for it: a question (1 to 4, each with 2 to 6 choices) or a permission (a tool the agent would use, and what it would do). They are told; the card waits the rule's answerWithin (default 30 minutes), then a permission counts as denied and a question is left to the agent. Read the answer with deployments_asks_get (or when deployment://{org}/{platform} changes). Never put a secret in it. For reading the answer, use deployments_asks_get. For a card no longer needed, use deployments_asks_withdraw.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:follow
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
deploymentIdstringyesThe deployment (dep_…).
kind"question" | "permission"yesA question with choices, or a permission for a tool.
questionsobject[]kind question: 1 to 4 questions. At most 4 items.
toolobjectkind permission: the tool.
suggestionsobject[]kind permission: the rules the agent's app would remember for allow_run. At most 10 items.
contextstringWhat the agent was doing, in a line or two.
sealedstringSealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: ask (object, always), created (boolean).

deployments_asks_get

Read an agent's question. Use to read one of an agent's cards: open, answered (the answer: a permission's decision allow, allow_run or deny, or each question's answer, and a note), expired (nobody answered in time: the default) or withdrawn. Changes nothing but closing a card past its time. For asking, use deployments_asks_create.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
askIdstringyesThe card (age_…).

Answer: ask (object, always), deployment (object).

deployments_asks_withdraw

Withdraw an agent's question. Use, as its runner, to close a card the agent no longer waits on (it ended, was restarted, went on without it). The people asked are no longer shown it. Closed already answers changed: false. For asking, use deployments_asks_create.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:follow
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
askIdstringyesThe card (age_…).
reasonstringWhy, in a few words.

Answer: ask (object, always), changed (boolean), reason (string).

deployments_asks_list

See what agents ask you. Use to see the questions and permissions an organization's agents wait on that you answer for (as an admin, or as whoever made, deployed or runs the agent): open ones oldest first (the default), or all of them newest first. Each with its agent. Changes nothing but closing cards past their time. For answering one, use deployments_asks_answer.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
state"open" | "all"open (the default) or all.
deploymentIdstringOnly this agent's.
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: asks (object[], always), nextCursor (string | null), orgId (string).

deployments_asks_answer

Answer an agent. Use to answer an agent's card, as a person who answers for it: a permission with decision allow, allow_run (for the rest of this run) or deny; a question with answers {"<question>": "<a choice's label or your own words>"} (a list where several may be picked). A note goes to the agent with it. Its runner hands it to the agent at once. Once only: answered already by someone is a conflict. For the cards waiting, use deployments_asks_list.

  • Effect: write, idempotent
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
askIdstringyesThe card (age_…).
decision"allow" | "allow_run" | "deny"A permission's answer.
answersobjectA question card's answers, by question.
notestringWords for the agent with the answer (at most 2,000 characters).
sealedstringSealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused.

Answer: ask (object, always), changed (boolean), reason (string).

deployments_messages_send

Write to an agent. Use to tell a deployment's agent something while it runs (its runner hands it over at once, or at the agent's next step), or to interrupt it (it stops what it is doing and waits for you) or restart it. For the people who answer for it. For reading its conversation, use deployments_messages_list.

  • Effect: write
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
deploymentIdstringyesThe deployment (dep_…).
textstringWhat to tell it (at most 4,000 characters).
control"interrupt" | "restart"Interrupt it, or restart it.
sealedstringSealed conversations (RFC-0060 §10, an agent following a sealed instruction): this item as an imd-seal/1 envelope of kind message (objectId <deploymentId>/…), made with the workspace's key; its plain fields are then refused.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: entry (object, always), created (boolean).

deployments_messages_list

Read an agent's conversation. Use to read a deployment's conversation: what its agent said and did, its questions and permissions with their answers, what people wrote to it — oldest first, after a line's seq (without after: the last limit). As its runner, take: true answers only the messages and controls its agent hasn't been given, and marks them given (each is handed over once). For writing to it, use deployments_messages_send.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
deploymentIdstringyesThe deployment (dep_…).
afterstringOnly lines after this seq.
takebooleanAs its runner: take what waits for the agent.
limitintegerAt most this many (default 100, max 500).

Answer: deployment (object), entries (object[], always), after (string), more (boolean).

Organizations, members and workspaces

Organizations, their members and invitations, and their workspaces and workspace roles.

orgs_list

List your organizations. Use to see the organizations you belong to, with your role and their plan. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: orgs (object[], always), nextCursor (string | null).

orgs_get

Get an organization. Use to see an organization: its workspaces, members count and plan (and policy, for admins). Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

orgs_create

Create an organization. Use to create a team organization; you become its owner, with a default workspace. Creates it on the free plan.

  • Effect: write
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
slugstringyesIts URL name.
displayNamestringIts name.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

orgs_rename

Rename an organization. Use to change an organization's display name or its URL name (one or both); an old URL name redirects for good (no one else can take it), and a new one changes every instruction's owner/name address.

  • Effect: write, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
slugstringThe new slug.
displayNamestringThe new display name.

orgs_delete

Delete an organization. Use to delete a team organization and everything in it (owners only; refused under legal hold). Asks for confirmation. Its people lose access and its agents stop at once; the rest goes in the background (the jobId), after an export of it is made for you: it appears in me://exports (kept 7 days), and you are told in me://inbox.

  • Effect: destructive, idempotent. Asks to confirm. Claude Code asks the person before each call
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

orgs_members_list

List members. Use to see an organization's members and their roles, a page at a time (25 by default). Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
limitintegerAt most this many (default 25, max 500).
cursorstringThe nextCursor of the previous page.
detail"summary" | "full"How much of each item: summary (default) — principalId, type, role, name, handle (not their email or workspaces); full — all it has.

Answer: members (object[], always), nextCursor (string | null), orgId (string).

orgs_members_add

Add a member. Use to add one of the organization's own agents as a member. People join by invitation, which they accept (orgs_invitations_create): adding a person here is refused.

  • Effect: destructive
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
principalIdstringyesThe agent (agt_…).
role"admin" | "billing" | "member" | "guest"Their role (an agent is a member).
workspaceIdstringA workspace to give them workspaceRole in (default: the default workspace).
workspaceRole"reader" | "contributor" | "maintainer" | "admin"Their role in that workspace (an agent is at most a maintainer).

orgs_members_update

Change a member's role. Use to change a member's organization role (only owners make owners; the last owner stays). Changes what they may do.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
principalIdstringyesThe member.
role"owner" | "admin" | "billing" | "member" | "guest"yesThe role.

orgs_members_remove

Remove a member. Use to remove a member (or leave yourself); never the last owner. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
principalIdstringyesThe member.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

orgs_invitations_create

Invite someone. Use to invite someone by email with a role, optionally into a workspace. Returns the invitation link once.

  • Effect: write
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
emailstringyesTheir email.
role"admin" | "billing" | "member" | "guest"Their role.
workspaceIdstringThe workspace (ws_…).
workspaceRole"reader" | "contributor" | "maintainer" | "admin" | "none"A workspace role; none removes it.
messagestringA note.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

orgs_invitations_list

List pending invitations. Use to see an organization's pending invitations. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: invitations (object[], always), nextCursor (string | null), orgId (string).

orgs_invitations_revoke

Revoke an invitation. Use to cancel a pending invitation. Its link stops working.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
invitationIdstringyesThe invitation (inv_…).

orgs_invitations_peek

See what an invitation is for. Use, from an app, signed in as the person it was sent to, to see what an invitation is for before accepting it: the organization's name and slug, the role and workspace role it gives, and when it expires. A wrong, withdrawn or expired token, or one used already (other than by you while you're still a member), is not_found, the same answer for each; one sent to another email address is refused as accepting it would be. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
tokenstringyesThe invitation's token, or its link.

Answer: org (object, always), role (string, always), workspaceRole (string), expiresAt (string).

orgs_invitations_accept

Accept an invitation. Use, signed in as the person it was sent to (your email is its address), to accept an invitation with its token, or — one your organization's identity provider made, from me_invitations_list — by its id, when your sign-in's verified email is its address. Makes you a member. For the invitations your identity provider made, use me_invitations_list.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
tokenstringThe invitation's token.
invitationIdstringOr the id (inv_…) of one your identity provider made, addressed to your verified email.

me_invitations_list

Your invitations. Use to see the invitations waiting for you because an organization's identity provider provisioned you (SCIM), for your sign-in's verified email (an admin's invitation comes by its emailed link). Accept one with orgs_invitations_accept and its id; ignoring it changes nothing. Changes nothing. For accepting one, use orgs_invitations_accept.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads

No arguments.

Answer: invitations (object[], always).

orgs_workspaces_list

List workspaces. Use to see an organization's workspaces you can see, a page at a time (50 by default): each with your role in it and whether it is restricted to its own people. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: workspaces (object[], always), nextCursor (string | null), orgId (string).

orgs_workspaces_get

Get a workspace. Use to see a workspace with its members and their roles. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).

orgs_workspaces_create

Create a workspace. Use to create a workspace in an organization you administer: open to its members (each with their role in the default workspace) unless restricted to the people you add. You become its admin. How many an organization may hold is its plan's (several on Team and above).

  • Effect: write
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
slugstringyesIts URL name.
namestringIts name.
restrictedbooleanOnly the people added to it work in it (default false: every member of the organization does).
settingsobjectIts settings (an object, at most 16 KB).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

orgs_workspaces_update

Change a workspace. Use to rename a workspace, restrict it to its own people or open it to the organization's members, or change its settings. Changes the workspace.

  • Effect: write, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).
namestringIts name.
slugstringIts URL name.
restrictedbooleanOnly the people added to it work in it; false opens it to every member. The default workspace is never restricted.
settingsobjectIts settings.

orgs_workspaces_delete

Delete a workspace. Use to delete an empty workspace other than the default. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

orgs_workspaces_roles_set

Set a workspace role. Use to give a member a workspace role (Reader, Contributor, Maintainer, Admin) or remove it. Changes what they may do there.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).
principalIdstringyesThe member.
role"reader" | "contributor" | "maintainer" | "admin" | "none"yesA workspace role; none removes it.

Policy

The organization's policy: default visibility, what agents may do, signed versions only, the assistant switch and more.

orgs_policy_get

Get an organization's policy. Use to see an organization's policy: default visibility, what agents may do, signing. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

orgs_policy_set

Change policy. Use to change an organization's policy (merged into what it has). Changes what its members and agents may do.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
policyobjectyesWhat to change of the policy: defaultVisibility, agentPublish, agentSharing, aiAutoPublish, requireSignedVersions, memberRole, integrationsOnly, developerMode, workspacePeople, assistant.

Integrations

The MCP servers, skills, agents and APIs an organization approves for its instructions, and the tools it blocks on them.

Example: a tools/call of orgs_integrations_tools_set
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "orgs_integrations_tools_set",
    "arguments": {
      "orgId": "org_01",
      "integrationId": "itg_01",
      "tools": [
        "events.delete"
      ],
      "state": "blocked"
    }
  }
}

orgs_integrations_list

List integrations. Use to see an organization's integrations (MCP servers, MCP registries, skill repositories, A2A agents) with what their last pull found, and whether its instructions are restricted to them. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

Answer: orgId (string), integrations (object[], always), integrationsOnly (boolean), features (object).

orgs_integrations_add

Add an integration. Use to add an MCP server, an MCP registry, a GitHub repository of skills or an A2A agent to an organization (Pro and above). The server pulls its definitions in the background; adding one again pulls it again.

  • Effect: write, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Pro, Team, and Enterprise

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
kind"mcp" | "registry" | "skills" | "agent"yesWhat it is: an MCP server's endpoint, an MCP registry, a GitHub repository of skills, an A2A agent (its Agent Card or its endpoint).
urlstringyesIts https:// address.
titlestringIts name (default: what it calls itself).
branchstringSkills: the branch (default: the repository's).
pathstringSkills: the folder to look in (default: the whole repository).
searchstringRegistry: only the servers whose name has this.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: integration (object, always).

orgs_integrations_sync

Pull an integration again. Use to pull an integration's definitions again now. Changes what it offers once the pull is done.

  • Effect: write, idempotent, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
integrationIdstringyesThe integration (itg_…).

Answer: integration (object, always).

orgs_integrations_remove

Remove an integration. Use to remove an integration and what it offered. Where instructions are restricted to integrations, the objects it approved show as not approved.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
integrationIdstringyesThe integration (itg_…).

Answer: removed (string, always).

Search integrations. Use to find an organization's integrated MCP servers, APIs, skills and agents by words in their names, or to check which targets (https addresses, registry names) its integrations approve. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
querystringWords in a name or a description.
kind"mcp" | "service" | "skill" | "agent"Only this kind (service: an API).
targetsstring[]Targets to check, at most 100. At most 100 items.
limitintegerAt most this many items (default 20, max 200).

Answer: orgId (string), items (object[], always), approved (string[]), blocked (object), integrationsOnly (boolean).

orgs_integrations_tools_list

List an MCP server's or an API's tools. Use to see the tools an organization's integrated MCP server lists, or an API's operations (each a tool, with its method and path), each allowed or blocked for its instructions, and what a tool found for the first time gets (newTools). include ["inputSchema"] adds each tool's input schema (and an operation's output schema). 100 a page by default. Changes nothing. For allowing or blocking them, use orgs_integrations_tools_set.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
integrationIdstringyesThe MCP server's or the API's integration (itg_…).
querystringWords in a tool's name or description.
include"inputSchema"[]What to add to the answer.
limitintegerAt most this many tools (default 100, max 300).
cursorstringThe nextCursor of the previous page.

Answer: orgId (string), integrationId (string, always), title (string), newTools (string), canBlock (boolean), tools (object[], always), nextCursor (string | null).

orgs_integrations_tools_set

Allow or block an MCP server's tools. Use to allow or block tools of an integrated MCP server, or an API's operations, for the organization's instructions (Pro and above): the tools named, or every tool when tools is left out; and newTools, what a tool the next pulls find gets (allow — an API's reads, its writes still blocked — or block until reviewed). A blocked tool is never offered as you write, and an instruction that names one is marked. Changes what its instructions may use. For the tools and their states, use orgs_integrations_tools_list.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Pro, Team, and Enterprise

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
integrationIdstringyesThe MCP server's integration (itg_…).
toolsstring[]The tools to change, at most 300 (default: every tool).
state"allowed" | "blocked"What they become.
newTools"allow" | "block"What a tool found for the first time gets: allow, or block until reviewed.

Answer: integration (object, always), changed (boolean, always), updated (integer), reason (string).

orgs_integrations_apis_add

Add an API. Use to add an API to an organization (Pro and above) from its OpenAPI document (3.x or Swagger 2.0): its https url, or the document itself (an upload, 5 MB at most). Reads it now; each operation with an operationId becomes a tool instructions can name, reads (GET, HEAD) allowed, other methods blocked until an admin allows them. The API is never called. A url answering 401 or 403 needs token (sent once, to that address only, never kept). For reading it again, use orgs_integrations_apis_pull.

  • Effect: write, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Pro, Team, and Enterprise

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
urlstringThe OpenAPI document's https:// address.
documentstringOr the document itself, JSON or YAML (an upload), at most 5 MB. At most 5242880 characters.
fileNamestringAn upload's file name, to know it by.
titlestringIts name (default: the document's title).
tagsstring[]Only the operations with one of these tags (an API of more than 300 operations is narrowed so). At most 50 items.
tokenstringOnly if the url needs one: a bearer token, or the value of tokenHeader. Used for this one read and never kept. At most 8192 characters.
tokenHeaderstringThe header the token goes in, such as X-API-Key (default: Authorization: Bearer).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: integration (object, always), operations (integer, always), blocked (integer).

orgs_integrations_apis_pull

Read an API's document again. Use to read an API's OpenAPI document again now: from its url (with token again if it needed one: tokens are never kept), or, for an uploaded one, from the document uploaded again. Operations found for the first time get the default (reads allowed, writes blocked); decisions made stay. The API is never called. For adding one, use orgs_integrations_apis_add.

  • Effect: write, idempotent, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
integrationIdstringyesThe API's integration (itg_…).
documentstringAn uploaded API's document, again. At most 5242880 characters.
fileNamestringIts file name.
tokenstringIf its url needs one: used for this one read and never kept. At most 8192 characters.
tokenHeaderstringThe header the token goes in (default: Authorization: Bearer).

Answer: integration (object, always), operations (integer, always), blocked (integer).

People directories and SCIM

Directories the editor offers people from as you write, and SCIM tokens for provisioning members.

Example: a tools/call of orgs_people_directories_add
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "orgs_people_directories_add",
    "arguments": {
      "orgId": "org_01",
      "type": "okta",
      "url": "https://acme.okta.com",
      "token": "00ab…"
    }
  }
}

Search people. Use to find people of an organization — its members, the people its identity provider provisions, and the people of the directories it added (Okta, Entra ID, Google Workspace, Workday, SCIM, JSON, files) — by words in their name, email, job title or team, with what an instruction writes to name them (ref). Only offered directories unless directory names one; departed people only with include ["departed"]. 100 a page by default. Changes nothing. For resolving references an instruction already names, use orgs_people_get.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
querystringWords in a name, email, job title or team.
directorystringOnly this directory: workspace, its id (itg_…) or its key.
include"departed"[]What to add.
limitintegerAt most this many people (default 100, max 1000).
cursorstringThe nextCursor of the previous page.

Answer: people (object[], always), nextCursor (string | null), orgId (string), total (integer).

orgs_people_get

Resolve people. Use to resolve the people an instruction names — its :person[…]{ref=…} references (principal://usr_…, person://{directory}/{id}) — to who they are: name, job title, team, manager, picture, and whether they are still at the organization. At most 100 at once; the ones it doesn't know are listed in missing. Changes nothing. For finding people by name, use orgs_people_search.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
refsstring[]yesThe references, 1 to 100. At most 100 items.

Answer: orgId (string), orgName (string), people (object[], always), missing (string[], always).

orgs_people_directories_list

List people directories. Use to see where an organization's people come from: this workspace (its members and the people SCIM provisions) and the directories it added, each with how many people, whether they are offered as you write, and when it was last pulled and by whom. Changes nothing. For adding one, use orgs_people_directories_add.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

Answer: orgId (string), orgName (string), directories (object[], always), features (object).

orgs_people_directories_add

Add a people directory. Use to add a people directory to an organization (Pro and above) and pull its people now: Okta, Microsoft Entra ID (a Graph token, or tenant with clientId and clientSecret), Google Workspace, Workday (a report's url), a SCIM server, any JSON url, or a CSV or JSON file (document), the last ones with a mapping. Names, emails, titles, teams, managers and pictures only. A credential is used for this one pull and never kept. For pulling again, use orgs_people_directories_pull. For the directories already added, use orgs_people_directories_list.

  • Effect: write, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Pro, Team, and Enterprise

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
type"okta" | "entra" | "google" | "workday" | "scim" | "json" | "csv"yesWhere the people are.
urlstringIts https address: the Okta organization, the Workday report, the SCIM base URL, the JSON address.
documentstringA CSV or JSON file's text (an upload), at most 5 MB. At most 5242880 characters.
fileNamestringAn upload's file name.
titlestringIts name (default: its type's).
tenantstringEntra ID: the tenant (its id or domain), with clientId and clientSecret.
domainstringGoogle Workspace: only this domain (default: the whole account).
mappingobjectJSON and CSV: where each field is, {list, next, id, name, email, title, department, manager, picture, active, location, extra: {label: path}}: a JSON path of names and indexes, or a CSV column.
tokenstringThe credential for this one pull, never kept: an API token or a bearer token. At most 8192 characters.
tokenHeaderstringJSON and SCIM: the header the token goes in (default: Authorization: Bearer).
usernamestringWorkday: the integration user, with password (Basic).
passwordstringWorkday: its password, used once and never kept. At most 1024 characters.
clientIdstringEntra ID: the app's client id, with clientSecret and tenant (client credentials).
clientSecretstringEntra ID: the app's client secret, used once and never kept. At most 1024 characters.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: directory (object, always), people (integer, always), departed (integer).

orgs_people_directories_pull

Pull a people directory again. Use to pull a people directory's people again now, with its credential again if it needed one (credentials are never kept), or an uploaded file again. People no longer found are kept and marked as departed. For adding one, use orgs_people_directories_add.

  • Effect: write, idempotent, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
integrationIdstringyesThe directory (itg_…).
documentstringAn uploaded directory's file, again. At most 5242880 characters.
fileNamestringIts file name.
tokenstringIts credential, used once. At most 8192 characters.
tokenHeaderstringThe header the token goes in.
usernamestringWorkday's user.
passwordstringIts password, used once. At most 1024 characters.
clientIdstringEntra ID's client id.
clientSecretstringIts secret, used once. At most 1024 characters.

Answer: directory (object, always), people (integer, always), departed (integer).

orgs_people_directories_set

Offer or hide a directory's people. Use to offer a directory's people as the organization's members write (offered true) or hide them from suggestions (false); this workspace's own people too (directory workspace). References already written keep resolving.

  • Effect: write, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
directorystringyesworkspace, or a directory's id (itg_…) or key.
offeredbooleanyesOffered as you write.

Answer: directory (string, always), offered (boolean, always), changed (boolean).

orgs_scim_tokens_list

List SCIM tokens. Use to see an organization's SCIM tokens (never their values) and the SCIM base URL its identity provider pushes people to. Changes nothing. For making or rotating one, use orgs_scim_tokens_create.

  • Effect: read, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

Answer: orgId (string), available (boolean), baseUrl (string), tokens (object[], always).

orgs_scim_tokens_create

Make or rotate a SCIM token. Use to make the bearer token an identity provider (Okta, Entra ID …) provisions an organization's people with over SCIM 2.0 (Team and above; owners only, at most 5 working), shown once and kept only as its hash; with replaces, the old one is revoked now or after keepOldHours (at most 24). People only. For revoking one, use orgs_scim_tokens_revoke. For the tokens, use orgs_scim_tokens_list.

  • Effect: destructive
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Team and Enterprise

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
labelstringWhat it is for, such as Okta.
replacesstringRotate: the token (sct_…) this one replaces.
keepOldHoursintegerRotate: hours the old one still works (0–24, default 0).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Answer: token (object, always), secret (string, always), baseUrl (string).

orgs_scim_tokens_revoke

Revoke a SCIM token. Use to revoke a SCIM token at once: the identity provider's next push with it is refused. For making a new one, use orgs_scim_tokens_create.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
tokenIdstringyesThe token (sct_…).

Answer: token (object, always), changed (boolean, always), reason (string).

Sign-in and domains

An organization's own identity provider (single sign-on) and its verified domains. Single sign-on is not available yet. The tools are listed to an organization's admins, and saving a provider or turning sign-in through it on answers limit_reached on a plan without it.

Example: a tools/call of orgs_signin_provider_save
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "orgs_signin_provider_save",
    "arguments": {
      "orgId": "org_01",
      "kind": "oidc",
      "name": "Okta",
      "issuer": "https://acme.okta.com",
      "clientId": "0oa1…",
      "clientSecret": "…"
    }
  }
}

orgs_signin_get

See your organization's sign-in. Use to see how an organization's people sign in through its own identity provider (Enterprise): the provider (OIDC or SAML, never its secret), its email domains with the DNS TXT record each needs and whether it is verified, whether sign-in through it is on and required, whether AI clients (Claude) connect its people through it, and the values to give the identity provider. Changes nothing. For setting up the provider, use orgs_signin_provider_save. For turning it on, use orgs_signin_set.

  • Effect: read, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

orgs_signin_provider_save

Set up your identity provider. Owners. Asks first. Use to set up or change the identity provider an organization's people sign in with (Enterprise): OIDC with its issuer, client id and client secret, or SAML with its metadata address or XML. The connection is tested first (discovery, the client id and secret, the metadata); the secret goes to the identity provider only, never kept or shown. Saved off: verify a domain, then turn it on with orgs_signin_set. For the state, use orgs_signin_get. For adding the email domains, use orgs_signin_domains_add. For turning it on, use orgs_signin_set.

  • Effect: destructive, reaches a third party. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
kind"oidc" | "saml"yesHow the identity provider signs people in.
namestringWhat people see it called, such as Okta. At most 100 characters.
issuerstringOIDC: the provider's issuer, such as https://acme.okta.com.
discoveryUrlstringOIDC: its discovery document's address, if not at the issuer.
clientIdstringOIDC: the client id the provider gave instruction.md.
clientSecretstringOIDC: that client's secret: sent to the identity provider only, never kept or shown. Leave out to keep the one set. At most 4096 characters.
metadataUrlstringSAML: the provider's metadata address.
metadataXmlstringSAML: the metadata XML, instead of its address. At most 524288 characters.

orgs_signin_provider_remove

Remove your identity provider. Owners. Asks first. Use to stop an organization's people signing in through its identity provider and forget it: their accounts stay, and they sign in another way; AI clients stop connecting through it. Its domains stay, verified. For only turning it off, use orgs_signin_set.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

orgs_signin_domains_add

Add an email domain. Use to add an email domain (acme.com) whose people sign in through the organization's identity provider (Enterprise). Answers the DNS TXT record to publish; verify it with orgs_signin_domains_verify. Public mail services and a domain another organization verified are refused. For the identity provider, use orgs_signin_provider_save. For verifying it, use orgs_signin_domains_verify. For removing one, use orgs_signin_domains_remove.

  • Effect: write, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
domainstringyesThe email domain, such as acme.com.

orgs_signin_domains_verify

Verify an email domain. Use once the domain's TXT record is published: looks it up now and, if it holds this organization's value, marks the domain verified (sign-ins are routed by verified domains only). Checked again every few hours; a record gone three times in a row unverifies it. For the record to publish, use orgs_signin_domains_add.

  • Effect: write, idempotent, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
domainstringyesThe email domain.

orgs_signin_domains_remove

Remove an email domain. Use to remove an email domain: its people's sign-ins stop going to the organization's identity provider (and stop being required to). Their accounts stay. A domain that routes sign-ins is an owner's to remove, asked first. For adding one, use orgs_signin_domains_add.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
domainstringyesThe email domain.

orgs_signin_set

Turn your sign-in on or off. Owners. Asks first. Use to turn sign-in through the organization's identity provider on or off (on needs a verified domain), to require it for the verified domains' people (owners only; one owner must sign in another way), and to let AI clients such as Claude connect the organization's people through it without a sign-in (enterprise-managed authorization, Enterprise; OIDC). Each one named changes; the others stay. For the state, use orgs_signin_get. For the identity provider, use orgs_signin_provider_save. For removing it, use orgs_signin_provider_remove.

  • Effect: destructive. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
onbooleanSign-in through the identity provider on (true) or off.
requireSsobooleanThe verified domains' people sign in through it only (owners).
emaobjectEnterprise-managed authorization: AI clients through the identity provider.

orgs_domains_list

List your domains. Use to see an organization's domains: the DNS TXT record each needs, whether it is verified, and what uses it (sign-in routing, apps' Verified badge). Changes nothing. For adding one, use orgs_domains_add.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

Answer: orgId (string), domains (object[], always).

orgs_domains_add

Add a domain. Use to add a domain (acme.com) the organization will prove it controls, on any plan: answers the DNS TXT record to publish; then orgs_domains_verify. Public mail services, ours, and a domain another organization verified are refused. For your domains, use orgs_domains_list. For verifying it, use orgs_domains_verify.

  • Effect: write, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.
domainstringyesThe domain, such as acme.com.

Answer: orgId (string), domains (object[], always).

orgs_domains_verify

Verify a domain. Use once the domain's TXT record is published: looks it up now and, if it holds this organization's value, marks it verified. Checked again every hour; gone three times in a row, it is unverified (and apps needing it turn off). For the record to publish, use orgs_domains_add.

  • Effect: write, idempotent, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
domainstringyesThe domain.

Answer: orgId (string), domains (object[], always), verified (boolean, always), reason (string).

orgs_domains_remove

Remove a domain. Use to remove a domain. One that routes sign-ins is an owner's and asked first; one an app's Verified badge or redirects need is asked first (the app turns off where a redirect is on it).

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
domainstringyesThe domain.

Answer: orgId (string), domains (object[], always), changed (boolean, always).

Apps

Apps an organization registers to sign people in with instruction.md, and its policy for apps. Sign in with instruction.md is not available yet: while it is off, the server refuses every app's call.

Example: a tools/call of orgs_apps_create
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "orgs_apps_create",
    "arguments": {
      "orgId": "org_01",
      "name": "Acme Agents",
      "homepage": "https://acme.com",
      "redirectUris": [
        "https://app.acme.com/cb"
      ],
      "clientType": "public",
      "scopes": [
        "instructions:selected"
      ]
    }
  }
}

orgs_apps_list

List your apps. Use to see the apps an organization registered for Sign in with instruction.md: each one's client id, redirect URIs, client type, the scopes it may ask for, its Verified badge (a domain the organization proved), its review and state, and how many people use it; with the plan's limit, the scope catalogue and our authorization endpoints. Changes nothing. For registering one, use orgs_apps_create.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

Answer: orgId (string), apps (object[], always), limit (object), on (boolean), features (object), catalogue (object[]), endpoints (object).

orgs_apps_get

Get an app. Use to see one of an organization's apps (as orgs_apps_list shows each). Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
appIdstringyesThe app (app_…).

Answer: app (object, always).

orgs_apps_create

Register an app. Use to register an app that signs people in with instruction.md (owners and admins): its name, homepage, privacy and terms links, redirect URIs (https on a verified domain, or loopback 127.0.0.1/[::1] for native apps), public (PKCE) or confidential (private_key_jwt with a jwksUri), and its scopes; or a client metadata document's URL (on a verified domain). No client secret ever. Sensitive scopes wait for review. Answers the client id. For your apps, use orgs_apps_list. For asking for sensitive scopes, use orgs_apps_review_request.

  • Effect: write, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.
namestringWhat people see it called (2–60 characters; never instruction.md's or another organization's domain). At most 60 characters.
homepagestringIts homepage (https).
privacyUrlstringIts privacy policy (https).
termsUrlstringIts terms (https).
logoUrlstringIts logo (https, on a verified domain: else not shown).
redirectUrisstring[]1 to 10: https on a verified domain, a loopback (http://127.0.0.1/…, http://[::1]/…), or a reversed-domain scheme (com.acme.app:/cb). At most 10 items.
clientType"public" | "confidential"public: PKCE (S256); confidential: private_key_jwt with jwksUri.
jwksUristringA confidential app's public keys (https).
cimdUrlstringInstead of the fields above: its client metadata document's URL (https, on a verified domain); the client id is this URL.
scopes"instructions:read" | "instructions:selected" | "instructions:follow" | "instructions:all"[]What it may ask people for.

Answer: app (object, always).

orgs_apps_update

Change an app. Use to change an app's fields (each one named changes), or read its client metadata document again (refresh). Taking a redirect URI or a scope away asks first: people using it there stop being able to.

  • Effect: destructive. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
appIdstringyesThe app (app_…).
namestringIts name. At most 60 characters.
homepagestringIts homepage.
privacyUrlstringIts privacy policy.
termsUrlstringIts terms.
logoUrlstringIts logo.
redirectUrisstring[]Its redirect URIs, all of them. At most 10 items.
clientType"public" | "confidential"Its client type.
jwksUristringIts keys.
scopesstring[]What it may ask for, all of them.
refreshbooleanRead its client metadata document again.
cimdUrlstringAn app registered by its client metadata document: that address (it can't change).

Answer: app (object, always), changed (boolean, always).

orgs_apps_rotate

Give an app a new client id. Asks first. Use to replace an app's client id: the old one, and every token of it, stops working at once; people's grants stay. Not for an app registered by its client metadata document (its URL is its id).

  • Effect: destructive. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.
appIdstringyesThe app (app_…).

Answer: app (object, always), previousClientId (string, always).

orgs_apps_revoke

Revoke an app. Asks first. Use to revoke an app for good: every call it makes as anyone is refused from the next one, its people's grants go, and its client is deleted.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
appIdstringyesThe app (app_…).

Answer: app (object, always), changed (boolean, always).

orgs_apps_review_request

Ask for sensitive scopes. Use to ask instruction.md to review an app's sensitive scope (instructions:all: every released instruction of the workspaces a person picks, new ones too, and their releases; Team and above): it needs a verified domain for its homepage, redirects and keys, a privacy policy and terms, and a note of what it will do. Bound to the app as it is now: a change sends it back to review. For registering the app, use orgs_apps_create.

  • Effect: write
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
appIdstringyesThe app (app_…).
scopes"instructions:all"[]yesThe scopes to review.
notestringyesWhat the app will do with them. At most 2000 characters.

Answer: app (object, always).

orgs_apps_policy_get

See the apps your people use. Use to see the third-party apps that reach an organization's instructions through its people, each allowed, blocked or neither, and whether only approved apps may. Changes nothing. For allowing or blocking, use orgs_apps_policy_set.

  • Effect: read, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

Answer: orgId (string), available (boolean), on (boolean), onlyApproved (boolean, always), apps (object[], always).

orgs_apps_policy_set

Allow or block apps. Use to allow or block apps for an organization's instructions, or allow only approved ones (Team and above). Blocking and only-approved ask first, and take effect at the apps' next call. For the list, use orgs_apps_policy_get.

  • Effect: destructive. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
onlyApprovedbooleanOnly allowed apps reach the organization's instructions.
allowstring[]Apps to allow.
blockstring[]Apps to block.
clearstring[]Apps to neither allow nor block.

Answer: orgId (string), available (boolean), on (boolean), onlyApproved (boolean), apps (object[], always), changed (boolean, always).

Signing keys and agent credentials

The organization's signing keys, and agent credentials (client id and secret) for agents that sign in on their own.

orgs_keys_list

List publisher keys. Use to see an organization's publisher keys (JWKS with states): what verifiers pin, 50 a page by default. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringThe organization: its id (org_…) or its slug.
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: keys (object[], always), nextCursor (string | null), orgId (string), owner (string).

orgs_keys_add

Add your own key. Use to register a bring-your-own Ed25519 public key (OKP JWK) for signing versions with the CLI. Adds it as active.

  • Effect: destructive
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On every plan

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
jwkobjectyesThe public JWK: {kty: OKP, crv: Ed25519, x}.
kidstringIts key id: 1–64 letters, digits, dots, colons, hyphens or underscores (default: the JWK's own kid, else byo- and its fingerprint).
labelstringWhat it is.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

orgs_keys_rotate

Rotate the platform key. Use to retire the organization's active platform key and make the next. New versions are signed with the new one.

  • Effect: destructive
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

orgs_keys_retire

Retire a key. Use to retire a key: past versions still verify, new ones aren't signed with it. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
kidstringyesThe key id.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

orgs_keys_revoke

Revoke a key. Use to revoke a key: versions signed with it count as unsigned for ref and binding policies. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm. Claude Code asks the person before each call
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
kidstringyesThe key id.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

orgs_agents_list

List agents. Use to see an organization's agent and service credentials with their scopes (never a secret), 50 a page by default. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
includeRevokedbooleanInclude the revoked ones (default false).
limitintegerAt most this many (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: agents (object[], always), nextCursor (string | null), orgId (string).

orgs_agents_create

Connect an agent. Use to issue a client-credentials principal for an agent in this organization. Returns its secret once, with the token URL and audience (sent again with its idempotencyKey, the agent without its secret).

  • Effect: destructive
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Pro, Team, and Enterprise

ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
namestringyesIts name.
kind"agent" | "service"What it is (default agent).
scopes"instructions:read" | "instructions:write" | "instructions:publish"[]What it may do.
workspaceRole"reader" | "contributor" | "maintainer" | "admin" | "none"A workspace role; none removes it.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

orgs_agents_rotate

Rotate an agent's secret. Use to give an agent a new secret; the old one stops working at once. Returns the new secret once; asks for confirmation.

  • Effect: destructive. Asks to confirm. Claude Code asks the person before each call
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
agentIdstringyesThe agent (agt_…).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

orgs_agents_revoke

Revoke an agent. Use to revoke an agent: no new tokens, its membership removed. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm. Claude Code asks the person before each call
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
agentIdstringyesThe agent.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Sealed workspaces

End-to-end encrypted workspaces: beta, not yet independently reviewed. The server stores and serves sealed text it can't read.

seal_keys_get

Get my encryption key. Use to get your encryption key for sealed instructions: its public identity and fingerprint, and the records that unlock it (each wrapped by a passkey, a security key, a passphrase, a recovery key or a device: opened only on your own device). key is null when you have none yet. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads

No arguments.

seal_keys_register

Set up my encryption key. Use once, from the editor, the CLI or @instruction.md/seal, to register your encryption key for sealed instructions: its public identity (X-Wing and Ed25519 public keys, fingerprint) and one or more unlock records, a recovery key among them for a person. The private key never comes here unwrapped. Returns the key and its unlock records; sent again with its idempotencyKey, it answers what it made.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
publicobjectyesThe public identity: {suite: imd-seal/1, kind, kem, sig, fingerprint}.
unlocksobject[]yesHow the key unlocks: 1 to 20 records. At most 20 items.
labelstringA name for the key.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

seal_unlocks_add

Add a way to unlock my key. Use to add a way to unlock your encryption key: a passkey, a security key, a passphrase, a recovery key or this device (an imd-seal/1 unlock record made on your device). Returns the record.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
recordobjectyesThe unlock record.
labelstringA name for it ("YubiKey 5C", "MacBook").
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

seal_unlocks_remove

Remove a way to unlock my key. Use to remove one way to unlock your encryption key; the last one, and your only recovery key, stay. Returns whether it was removed.

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
unlockIdstringyesThe unlock record (slu_…).

seal_key_services_register

Register a key service. Use, as an organization's admin, to register the key of its @instruction.md/mcp proxy (instruction-mcp key init --key-service): the company's key service, which sealed workspaces can then give their key to (seal_wraps_add) so its people's AI apps and agents read them through it. Returns the key.

  • Effect: write
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
publicobjectyesThe key service's public identity (imd-seal/1, kind key-service).
labelstringWhere it runs ("mcp.acme.com").

seal_key_services_list

List key services. Use to see an organization's key services (its @instruction.md/mcp proxies' keys), to give a sealed workspace's key to one. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

seal_workspaces_get

Get a sealed workspace. Use to see whether a workspace is sealed: its key's epoch, the workspace key wrapped to you (myWrap, opened on your device), who holds the key, who set up a key and waits for it (waiting), and who has no key yet. epoch reads an earlier epoch's wrap. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).
epochintegerAn earlier epoch's wrap, for versions made then.
recipientstringA key service's fingerprint: its wrap instead of yours (what the organization's @instruction.md/mcp proxy opens).

seal_workspaces_enable

Seal a workspace. Use to seal an empty workspace (Team and Enterprise): from then on its instructions are encrypted on its people's devices and instruction.md can't read them. wraps: the new workspace key wrapped (imd-seal/1) to you and the others who read it. Asks for confirmation. Returns the sealed workspace.

  • Effect: destructive. Asks to confirm
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes

Plans On Team and Enterprise

ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).
wrapsobject[]yesThe workspace key wrapped to each recipient, you among them.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

seal_wraps_add

Give the workspace key. Use, holding a sealed workspace's key, to give its current epoch to people of the workspace who set up a key (seal_workspaces_get waiting), or to the organization's key service: wraps made on your device. Returns the workspace and who was added.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).
wrapsobject[]yes1 to 200 wraps. At most 200 items.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

seal_workspaces_rotate

Rotate a workspace's key. Use when someone leaves a sealed workspace, or by policy: a new epoch's key, wrapped to everyone who keeps reading (made on your device). New versions use it; earlier ones keep theirs. Asks for confirmation. Returns the workspace.

  • Effect: destructive. Asks to confirm
  • Who can call it: People only
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).
workspaceIdstringyesThe workspace (ws_…).
epochintegeryesThe new epoch: the current one plus one.
wrapsobject[]yesThe new key wrapped to each recipient, you among them.
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

instructions_sealed_draft_put

Write a sealed draft. Use to write a sealed instruction's draft: its whole text sealed on your device as an imd-seal/1 envelope (kind draft, objectId draft, the workspace's current epoch, your key as its author and signer), made on the revision you read. instruction.md checks the signature and stores it without reading it. Returns the new revision.

  • Effect: write
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
expectedRevisionintegeryesThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.
envelopeobjectyesThe draft's envelope.

instructions_sealed_publish

Release a sealed version. Use to release a sealed instruction's next version: its text sealed on your device (kind version, objectId v<next number>, parent the latest version's digest or null). Moves the default ref unless refs says otherwise, which asks for confirmation; the first release needs visibility (private or internal). checks: what your editor or proxy found, kept as client-asserted. Returns the version.

  • Effect: destructive. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:publish
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
envelopeobjectyesThe version's envelope.
messagestringWhat changed.
refsstring[]Refs to move (default: the default ref).
visibility"private" | "internal"Who can read its versions; required on the first release.
checksobjectThe checks run where it was sealed (client-asserted).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Activity and audit

What happened to an instruction, and the organization's audit trail.

Example: a tools/call of instructions_audit_query
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "instructions_audit_query",
    "arguments": {
      "instructionId": "acme/refunds",
      "types": [
        "version.*",
        "ref.changed"
      ],
      "from": "2026-10-01T00:00:00Z"
    }
  }
}

instructions_activity_list

List recent activity. List what happened to an instruction, newest first: releases, ref moves, edits, reviews, access; each with when, who and a sentence. Returns a page (25 by default, at most 100; nextCursor for more); detail full adds each event's subject and where it came from. Changes nothing. For the audit trail, filtered, with reads of what isn't public, use instructions_audit_query.

  • Effect: read, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
limitintegerAt most this many (default 25, max 100).
cursorstringThe nextCursor of the previous page.
detail"summary" | "full"How much of each item: summary (default) — id, type, at, actor, versionId, summary; full — all it has.

Answer: events (object[], always), nextCursor (string | null), instructionId (string), links (string[]).

instructions_audit_query

Query the audit trail. Query the audit trail of an instruction or an organization: who changed what and when, and who read what isn't public; filtered by event types (exact, a family such as version.*, or read; except leaves types out), words (q), a workspace, principal, a time range (from, to: ISO 8601), transport and outcome, newest first. Returns a page of records (25 by default; nextCursor for more), each with its workspace and without its origin and subject unless detail is full. Changes nothing. For an instruction's recent activity, in sentences, use instructions_activity_list.

  • Effect: read, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
orgIdstringThe organization (org_…).
typesstring[]Only these.
exceptstring[]All but these (the same forms as types).
qstringOnly records whose sentence, actor's name or type has these words, whatever their case. At most 200 characters.
workspaceIdstringOnly what happened in this workspace of the organization (ws_…).
principalstringOnly this principal.
fromstringFrom (ISO 8601).
tostringUntil (ISO 8601).
transportstringOnly reads over this.
outcomestringOnly this outcome.
limitintegerAt most this many (default 25, max 500).
cursorstringThe nextCursor of the previous page.
detail"summary" | "full"How much of each item: summary (default) — each record without via or subject; full — all it has.

Answer: records (object[], always), nextCursor (string | null), instructionId (string), orgId (string), filters (object).

instructions_audit_export

Export the audit. Use to export a filtered audit trail as NDJSON or CSV (never content). Returns a jobId at once; the file appears in me://exports (kept 7 days), and you are told in me://inbox.

  • Effect: write
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
instructionIdstringThe instruction: its id (ins_…), owner/name, or instruction:// address.
orgIdstringThe organization (org_…).
typesstring[]Only these.
exceptstring[]All but these (the same forms as types).
qstringOnly records whose sentence, actor's name or type has these words, whatever their case. At most 200 characters.
workspaceIdstringOnly what happened in this workspace of the organization (ws_…).
principalstringOnly this principal.
fromstringFrom (ISO 8601).
tostringUntil (ISO 8601).
transportstringOnly reads over this.
outcomestringOnly this outcome.
format"ndjson" | "csv"The file's format (default ndjson).
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

Usage and billing

What an organization uses of its plan, and the way to pay.

orgs_usage_get

Get usage. Use to see an organization's usage this period against its plan's allowances. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

orgs_billing_checkout

Upgrade the plan. Use to start paying for a plan: returns a Stripe checkout URL the person opens; the plan changes once they pay. Team is billed for each person in the organization who isn't a guest, as they join. Refused when the organization already pays (change the plan with orgs_billing_portal) or its plan is set by contract.

  • Effect: write, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
plan"pro" | "team"yesThe plan.
idempotencyKeystringAny unique string: the call sent again with it answers its first result.

orgs_billing_portal

Open the billing portal. Use to change or cancel the plan, the payment method and the billing details, and to see invoices: returns a Stripe page URL the person opens. Needs a plan bought first (orgs_billing_checkout). Changes nothing here.

  • Effect: write, idempotent, reaches a third party
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

orgs_spending_set

Set the spending limit. Use to set how much overage an organization may spend, in cents (0 refuses overage). People only.

  • Effect: destructive, idempotent
  • Who can call it: People only. Needs org:admin
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
limitCentsintegeryesThe limit, in cents.

Your account

Your profile, preferences, notifications, the apps you connected, and deleting your account.

Example: a tools/call of me_apps_grant
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "me_apps_grant",
    "arguments": {
      "clientId": "imd-app-01j",
      "scopes": [
        "instructions:selected"
      ],
      "authorizationDetails": [
        {
          "type": "instruction_access",
          "instructions": [
            "ins_01"
          ],
          "actions": [
            "read"
          ]
        }
      ]
    }
  }
}

me_profile_update

Change your profile. Use to change your name, title, handle, time zone or language. Changes your profile (me://profile).

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
namestringYour name.
titlestringYour title.
handlestringYour handle (renames your personal organization too).
timeZonestringAn IANA time zone.
languagestringA BCP 47 language tag.

me_preferences_set

Change your preferences. Use to change your synced preferences: appearance, editor, notifications, privacy. Merged into what you have (me://preferences).

  • Effect: write, idempotent
  • Who can call it: People and agents
  • AI app scope: instructions:write
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
prefsobjectyes{appearance, editor, notifications, privacy}: each section's settings, merged into what you have.
expectedRevisionintegerThe revision you read (the draft's, for draft tools); a stale one answers version_conflict.

me_notifications_read

Mark notifications read. Use to mark notifications read, by id or all. Clears them from the unread count.

  • Effect: write, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
idsstring[]Which.
allbooleanEvery one.

me_apps_list

Your connected apps. Use to see the apps you connected with Sign in with instruction.md: what each may do, the instructions you chose for it, and when it last read anything. Changes nothing. For disconnecting one, use me_apps_revoke. For what one did, use me_apps_activity.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads

No arguments.

Answer: on (boolean), apps (object[], always).

What an app asks of you. Use, in the studio's picker, to see what an app asks for, your grant to it, and the instructions and projects you may choose for it. Changes nothing. For choosing, use me_apps_grant.

  • Effect: read, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
clientIdstringyesThe app's client id.

Answer: app (object, always), asks (object[], always), picks (boolean, always), grant (object | null), choices (object).

me_apps_grant

Choose what an app may reach. Use, in the studio's picker, to consent to an app's scopes and, for instructions:selected, choose the instructions and projects it may read (and follow): RFC 9396's shape, type instruction_access. Replaces your earlier choice. For what it asks, use me_apps_consent_get.

  • Effect: write, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
clientIdstringyesThe app's client id.
scopesstring[]yesWhat you consent to.
authorizationDetailsobject[]What the scopes cover. At most 20 items.

Answer: grant (object, always).

me_apps_revoke

Disconnect an app. Asks first. Use to disconnect an app: it can't read anything of yours from its next call. For your apps, use me_apps_list.

  • Effect: destructive, idempotent. Asks to confirm
  • Who can call it: People and agents
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
appIdstringyesThe app (app_… or its client id).

Answer: appId (string, always), changed (boolean, always).

me_apps_activity

What an app did. Use to see an app's recent calls as you (allowed or refused, newest first, kept 90 days). Changes nothing. For your apps, use me_apps_list.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
appIdstringyesThe app (app_… or its client id).
limitintegerAt most this many (default 50, max 200).

Answer: appId (string), calls (object[], always).

me_delete

Delete your account. Use to delete your account and everything in your personal organization; hand over team organizations you alone own first. Asks for confirmation.

  • Effect: destructive, idempotent. Asks to confirm. Claude Code asks the person before each call
  • Who can call it: People and agents
  • AI app scope: instructions:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

The language (spec_*)

The instruction language's own tools. They work on any text you pass, store nothing, and are the same functions the instruction CLI runs offline.

spec_validate

Check a text. Use to check any instruction text: its diagnostics (code, severity, line, message: an error is what a release refuses), the capability families it needs, and its spec version. Changes nothing; a stored draft is instructions_validate's, by its id.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
contentstringyesThe text.

Answer: ok (boolean, always), diagnostics (object[], always), spec (string), requires (string[]), title (string | null), validator (string).

spec_format

Format a text. Use to format an instruction text the conservative way the studio does. Returns the formatted text; changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
contentstringyesThe text.

spec_outline

Outline a text. Use to see a text's sections, rules and blocks with their lines, and its word and rule counts. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
contentstringyesThe text.

spec_fixes

Get fixes for a problem. Use to get the quick fixes for a diagnostic, as replace ops ready for instructions_draft_edit; a text still in Specification 1.1 gets its conversion. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
contentstringyesThe text.
codestringOnly this diagnostic code.
lineintegerOnly this line.

spec_deliver

Show what a model receives. Use to see what a model would receive from a text for given parameters: its agent text (instruction-text/1), whether it resolved completely, and its diagnostics. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
contentstringyesThe text.
paramsobjectParameter values.

spec_convert

Convert a prompt. Use to turn a system prompt into an instruction: its rules become MUST, SHOULD and NEVER lines. Returns the text to create; changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
promptstringyesThe system prompt.
titlestringA name for it.

spec_explain

Explain the language. Use to explain a kind, a keyword or a diagnostic code, with a link into spec://. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: People and agents
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
topicstringyesA kind, keyword or code.

Staff and platform tools

Not callable by customers. instruction.md's staff tools are refused to anyone else, and the platform tools are listed only to instruction.md's own services. They are here so a tools/list you read from a staff or service account is explained.

admin_apps_reviews_list

List app reviews. Staff only (the system organization's owners). Use to list apps waiting for a review of their sensitive scopes (or those approved or rejected). Changes nothing. For deciding one, use admin_apps_review.

  • Effect: read, idempotent
  • Who can call it: instruction.md staff only (not callable by customers). Needs org:admin
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
state"pending" | "approved" | "rejected"Which (default pending).

Answer: state (string), apps (object[], always).

admin_staff_list

List instruction.md's staff. Staff only. Use to see who instruction.md's staff are: the people who review apps' sensitive scopes and change who staff are. Changes nothing. For changing them, use admin_staff_set.

  • Effect: read, idempotent
  • Who can call it: instruction.md staff only (not callable by customers). Needs org:admin
  • Rate limit: person-reads

No arguments.

Answer: staff (object[], always).

admin_staff_set

Change instruction.md's staff. Staff only. Asks first. Use to make someone instruction.md staff, or stop them being staff (never the last). Each change is an event of instruction.md's own organization. For who they are, use admin_staff_list.

  • Effect: destructive. Asks to confirm
  • Who can call it: instruction.md staff only (not callable by customers). Needs org:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
userstringyesThe person: their id (usr_…), handle or email.
staffbooleanyestrue: staff; false: not.

Answer: userId (string, always), staff (boolean, always), changed (boolean, always).

admin_apps_review

Decide an app review. Staff only. Asks first. Use to approve an app's sensitive scopes (people may be asked for them from then on, each consenting) or reject them with a reason its owners see. For the queue, use admin_apps_reviews_list.

  • Effect: destructive. Asks to confirm
  • Who can call it: instruction.md staff only (not callable by customers). Needs org:admin
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.
appIdstringyesThe app (app_…).
decision"approve" | "reject"yesThe decision.
notestringWhy (required to reject). At most 2000 characters.

Answer: app (object, always).

support_requests_list

List support requests. Use, as instruction.md's staff, to list the requests people sent from the support and contact pages, newest first, by status, kind or words in them. 50 a page by default. Refused to anyone who isn't staff. Changes nothing. For one request with its log, use support_requests_get.

  • Effect: read, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
status"new" | "open" | "waiting" | "resolved" | "spam"Only requests in this status.
kind"sign-in" | "billing" | "account" | "sales" | "partnerships" | "security" | "press" | "other"Only requests of this kind.
querystringWords in the number, name, email, organization or message. At most 200 characters.
limitintegerAt most this many requests (default 50, max 200).
cursorstringThe nextCursor of the previous page.

Answer: requests (object[], always), nextCursor (string | null).

support_requests_get

Get a support request. Use, as instruction.md's staff, to read one support request whole: what the person wrote, the account they were signed in as, how they were proven, any recovery, and its log of every step. Changes nothing. For finding requests, use support_requests_list. For changing its status, adding a note or recording a proof, use support_requests_update.

  • Effect: read, idempotent
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
requestIdstringyesThe request: its id (sr_…) or its number (R-XXXX-XXXX).

Answer: request (object, always).

support_requests_update

Update a support request. Use, as instruction.md's staff, to change a support request's status, add a note, or record how the person was proven to be the account's (sso, org-admin, or checks, each named, with the account). Every change is a row of the request's log. For reading it first, use support_requests_get. For starting the recovery of a sign-in once proven, use support_requests_recover.

  • Effect: write
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
requestIdstringyesThe request: its id (sr_…) or its number (R-XXXX-XXXX).
status"new" | "open" | "waiting" | "resolved" | "spam"Its new status.
notestringA note for the log. At most 5000 characters.
verificationobjectHow the person was proven to be the account's.

Answer: request (object, always), changed (boolean), reason (string).

support_requests_recover

Start a sign-in recovery. Use, in the studio, as instruction.md's staff, to move the support-led recovery of a lost passkey on: one staff member asks for it, another approves it (the account and its organizations' owners are told, a 24-hour cool-off starts), then staff start it, once: it ends the account's sessions and lets them enrol a new passkey. Each step asks for confirmation. The start answers what to tell the person, once; never send it by email. Refused for staff's and instruction.md's own accounts. For recording the proof first, use support_requests_update.

  • Effect: destructive. Asks to confirm
  • Who can call it: instruction.md's own apps only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
requestIdstringyesThe request: its id (sr_…) or its number (R-XXXX-XXXX).
confirmTokenstringFrom a needs_confirmation answer, once the person agreed: for this call, 10 minutes. Without it nothing changes.

Answer: request (object, always), step (string, always), recovery (object | null, always).

admin_orgs_list

List every organization. Use, as a platform service, to list every live organization with its plan. Changes nothing.

  • Effect: read, idempotent
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-reads
ArgumentTypeRequiredDescription
type"personal" | "team" | "enterprise" | "system"Only organizations of this type.
plan"community" | "pro" | "team" | "enterprise"Only organizations on this plan.
limitintegerAt most this many (default 500, max 1000).
cursorstringThe nextCursor of the previous page.

Answer: orgs (object[], always), nextCursor (string | null).

orgs_entitlements_set

Write entitlements. Use, as the billing service, to write an organization's plan and limits. Changes what it may do.

  • Effect: destructive, idempotent
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
entitlementsobjectyes{plan, seats, status, validUntil, source, limits, features}.

orgs_usage_set

Write usage. Use, as a platform service, to write an organization's usage counters. Replaces them.

  • Effect: destructive, idempotent
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).
usageobjectyes{meter: used}.
periodStartstringThe month they count: a date or ISO 8601 time in it (default this month).

orgs_usage_fold

Fold usage. Use, as a platform service, to recount an organization's usage for the period. Rewrites its counters.

  • Effect: destructive, idempotent
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

orgs_usage_recount

Recount storage. Use, as a platform service, to recount an organization's stored bytes. Rewrites its storage counter.

  • Effect: destructive, idempotent
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringyesThe organization (org_…).

orgs_billing_reconcile

Reconcile billing. Use, as a platform service, to re-read Stripe and rewrite one organization's entitlements, or every one's. Changes plans to match Stripe.

  • Effect: destructive, idempotent, reaches a third party
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringThe organization (org_…).

admin_gc_run

Collect garbage. Use, as a platform service, to purge the expired trash and stale records. Deletes what retention says, and returns what it deleted (more: true when a run's cap left some).

  • Effect: destructive, idempotent
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
limitintegerAt most this many instructions purged in one run (and ten times as many stored texts) (default 1000, max 10000).

admin_index_rebuild

Rebuild search. Use, as a platform service, to rebuild every search document, or one organization's. Rewrites the search index.

  • Effect: write, idempotent
  • Who can call it: instruction.md's own services only (not callable by customers)
  • Rate limit: person-writes
ArgumentTypeRequiredDescription
orgIdstringOnly this organization's (its id or slug).

Last checked against the product:

Was this page helpful? Report a problem