Цю сторінку ще не перекладено.

Tools, skills, agents and services

This page is for developers who write or read instructions that name the things an agent works with: MCP servers, the tools on them, skills, other agents and web APIs. It lists every attribute of the five kinds, the protocol values they take, and how an organization's integrations policy is served with the text and applied to them.

These five kinds are the connected objects of the first edition (instruction/1), with person, role, source and wallet. A connected object describes something outside the document. Declaring one grants nothing: see Naming a tool never grants access.

The kinds at a glance

KindFormsRequiredWhat it names
mcp:::mcp{…} … ::: or ::mcp{…}idAn MCP server: its address, the account to use there, and the tools the agent uses, may call without asking, or must not call.
tool:::tool{…} … ::: or ::tool{…}id, server, nameOne tool on a server the document declares, or names outright.
skill:::skill{…} … ::: or ::skill{…}idA skill: instructions the model loads when they apply, written inline or fetched from GitHub.
agent:::agent{…} … ::: or ::agent{…}idAnother agent: a remote one the agent talks to (such as over A2A), or one the host runs itself.
service:::service{…} … ::: or ::service{…}idA web API, such as one described by an OpenAPI document.

A container (:::kind{…} to :::) has a Markdown body: what the object is for, in prose, for the agent and for people. A leaf (::kind{…}) has none. Attributes are written on one line, inside the braces.

The attribute tables below are read from the specification's registry (packages/spec/specification/registry.json) when this page is built. The reader checks each value's type and reports invalid-attributes for a wrong one, or for a required one that is missing.

MCP servers

mcp names an MCP server. This is the calendar server of the specification's introduction:

instruction.md
:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::
AttributeTypeMeaning
registrystringAn MCP registry that lists the server (its address or name). A server named only by a registry has no address to connect to: instruction agents apply skips it.
serverstringThe server's name in that registry, such as io.example/weather.
accountstringThe name of the credential to use there, such as work. Each machine says what it means; the instruction never holds a key.
toolslistThe tools the instruction uses on that server.
allowlistTools the agent may call without asking. A tool in deny is never in allow.
denylistTools the agent must not call.
resolverstringA resolver declared in the front matter's resolvers. instruction.md binds no resolver, so nothing is looked up.
protocolstringThe protocol and, optionally, its versions, as under Protocol values below.

A list attribute is written as a quoted string of names apart by commas or spaces (tools="events.list,availability.read"), or as a list. src is the server's Streamable HTTP address. A host connects only to an https: address, or to http: on localhost, 127.0.0.1 or [::1], and never to one with a user name or password in it.

account is a name, never a credential. What account=personal means on a given machine (a variable, a command that prints a key, a sign-in, your identity provider) is set there, with instruction agents accounts. See Servers, skills and accounts.

Tools

tool names one tool on a server. server is #id of an mcp or a service in the same document, or a server named outright (a registry name or an address). name is the tool's own name there.

AttributeTypeMeaning
serverstringThe server the tool is on: #id of the document's mcp or service, or a server named outright.
namestringThe tool's name on that server. On a service with protocol=openapi, an operationId in its OpenAPI document.
allowlistTyped as a list of names. The reader checks its shape only.
denylistTyped as a list of names. The reader checks its shape only.
protocolstringThe protocol and, optionally, its versions.

A rule refers to a declared tool with the inline form :tool[label]{ref=#id}. The agent reads it as label (tool; #id), so the rule and the declaration stay tied together:

instruction.md
::tool{id=list server=#calendar name=events.list}

MUST: check :tool[the calendar]{ref=#list} before proposing a time.

The inline kinds :mcp[…], :skill[…], :agent[…] and :service[…] work the same way. A ref to an #id the document doesn't have is a reference-optional warning; one to an object of another kind is a reference-kind error. See References.

Skills

skill is a skill the model loads when it applies. Write its text in the body, or point src at a SKILL.md on GitHub.

AttributeTypeMeaning
triggerstringWhen the model should load it. Used as the skill's description when description is absent.
resolverstringA resolver declared in the front matter's resolvers.
protocolstringThe protocol and, optionally, its versions.

What a host uses as the skill's description, the line that tells the model when to load it: description, else trigger, else title, else id.

A src is fetched only from GitHub, in one of three forms:

  • https://github.com/<owner>/<repo>/blob/<ref>/<path>.md, a file's page
  • https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>.md, the raw file
  • https://github.com/<owner>/<repo>/tree/<ref>/<dir>, a folder: its SKILL.md

Any other address is not fetched, and the skill is not set up. With sha256=sha256:<64 hex>, a fetched file that hashes to something else is not written. A src that starts with # is not a fetch: the body is used.

Agents

agent is another agent. What it is depends on three attributes:

  • With protocol, src or endpoint, it is a remote agent the enclosing agent talks to. An A2A agent (protocol=a2a) needs src (its Agent Card) or endpoint (where it receives messages); without either, the reader reports invalid-attributes.
  • With none of them, it is an agent the host runs itself. Its body is its instruction: its own prose, rules, servers and skills.
AttributeTypeMeaning
protocolstringHow the agent is reached, such as a2a. With protocol, src or endpoint, it is a remote agent; with none of them, an agent the host runs.
endpointstringWhere a remote agent receives messages.
bindingstringA protocol binding's own value. The reader checks its type; the binding gives its meaning.
tenantstringA protocol binding's own value. The reader checks its type; the binding gives its meaning.
skillslistA list of the remote agent's skills. The reader checks its type.
resolverstringA resolver declared in the front matter's resolvers.
accountstringThe name of the credential to reach it with.

Agents the host runs, and the agent manifest

The document itself is always one agent, the root, named after the instruction. A host-run agent at the top level reports to the root; one nested inside another reports to that one. A nested container's fence is shorter than the one around it, so the outer agent takes four colons:

instruction.md
---
spec: "1"
title: Support
---

# Support

Route each customer to the right person.

::::agent{id=lead title="Lead"}
Take the escalations. Reply within the hour.

:::mcp{id=desk title="Help desk" src="https://desk.example/mcp" account=work tools="tickets.list,tickets.reply"}
The help desk.
:::
::::

:::skill{id=triage title="Triage a ticket" description="Sort a new ticket by urgency."}
1. Read the ticket.
2. Pick an urgency.
:::

An mcp, skill, workflow, schedule or remote agent inside a host-run agent belongs to that agent alone. Everything outside every host-run agent is the root's. A host reconciles agents by id from one version to the next. When a declared agent has the instruction's own name, the root is named <name>-root.

A host reads this as the agent manifest (format agent-manifest/1, agentManifest in the instruction.md package: see JavaScript). For the document above:

agent-manifest/1
{
  "format": "agent-manifest/1",
  "implicit": false,
  "agents": [
    {
      "id": "support",
      "title": "Support",
      "reportsTo": null,
      "depth": 0,
      "reports": [
        "lead"
      ],
      "servers": [],
      "skills": [
        "triage"
      ],
      "routines": [],
      "peers": [],
      "needs": [
        "agents",
        "skills"
      ]
    },
    {
      "id": "lead",
      "title": "Lead",
      "reportsTo": "support",
      "depth": 1,
      "reports": [],
      "servers": [
        {
          "id": "desk",
          "title": "Help desk",
          "src": "https://desk.example/mcp",
          "tools": [
            "tickets.list",
            "tickets.reply"
          ]
        }
      ],
      "skills": [],
      "routines": [],
      "peers": [],
      "needs": [
        "agents",
        "mcp"
      ]
    }
  ],
  "needs": [
    "agents",
    "mcp",
    "skills"
  ]
}

needs names what a platform must support to run each agent: agents (it starts or reports to another), mcp, skills, workflows, and a2a (it talks to a remote agent). implicit is true when the document declares no host-run agent. An agent without an id, or with an id already used, is not an agent of its own: its body counts as its owner's. Deployments run these agents; the managed-agents page covers platforms that provision them.

Services and OpenAPI

service is a web API. With protocol=openapi/3.0 or openapi/3.1, src is the API's OpenAPI document (JSON or YAML), not the API's own address, and a tool on the service names an operation by its operationId:

instruction.md
::service{id=crm title="CRM" protocol=openapi/3.1 src="https://docs.crm.example/openapi.json"}

::tool{id=find server=#crm name=findCustomer}

::tool{id=refund server=#crm name=createRefund}

MUST: look the customer up with :tool[findCustomer]{ref=#find} before you answer.

NEVER: call :tool[createRefund]{ref=#refund} without a person's yes.
AttributeTypeMeaning
resolverstringA resolver declared in the front matter's resolvers.
accountstringThe name of the credential to call it with.
media-typestringThe media type of what src points at, such as application/json.
protocolstringThe protocol and, optionally, its versions. openapi/3.1 makes src an OpenAPI document.

An organization can import an OpenAPI document as an integration, so its operations become tools an admin allows or blocks. See Integrations and tool policy.

Common attributes

These are shared by every kind. The connected objects use these:

AttributeMeaning
idIts identity in the document: what #id references, a tool's server, and a host reconciles by. Letters, digits, ., _ and -.
titleThe name readers and the generated heading show.
descriptionOne line on what it is for. A skill's description tells the model when to load it.
srcWhere it is: an MCP server's address, an Agent Card, an OpenAPI document, a skill's SKILL.md on GitHub.
requiredA flag: the document needs it. Passed on to a host with the server.
versionThe version of what src names, as data.
sha256sha256: and 64 hex digits: what the fetched file must hash to. A skill whose file differs is not written.

What the agent receives

The agent's text gives each object a generated heading, ### <kind>: <title>, then its attributes in one canonical JSON line, then its body. The id and title are left out of the attribute line. For this document:

instruction.md
---
spec: "1"
title: Support agent
---

# Support agent

Answer customers about their bookings.

:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

::tool{id=list server=#calendar name=events.list}

::service{id=crm title="CRM" protocol=openapi/3.1 src="https://api.example.com/openapi.json"}

::tool{id=find server=#crm name=findCustomer}

:::agent{id=travel title="Travel researcher" protocol=a2a src="https://example.org/.well-known/agent-card.json"}
Ask it for travel options; it answers with a list.
:::

:::skill{id=triage title="Triage a ticket" description="Sort a new ticket by urgency."}
1. Read the ticket.
2. Pick an urgency.
:::

MUST: check :tool[the calendar]{ref=#list} before proposing a time.
BECAUSE: double bookings cost the customer a trip.

the agent receives:

instruction-text/1
# Support agent

Answer customers about their bookings.

### mcp: Calendar

Attributes: {"account":"personal","allow":["events.list","availability.read"],"deny":["events.delete"],"src":"https://calendar.example.org/mcp","tools":["events.list","availability.read"]}

Read appointments for planning. Ask Alex before changing an invitation.

### tool: list

Attributes: {"name":"events.list","server":"#calendar"}

### service: CRM

Attributes: {"protocol":"openapi/3.1","src":"https://api.example.com/openapi.json"}

### tool: find

Attributes: {"name":"findCustomer","server":"#crm"}

### agent: Travel researcher

Attributes: {"protocol":"a2a","src":"https://example.org/.well-known/agent-card.json"}

Ask it for travel options; it answers with a list.

### skill: Triage a ticket

Attributes: {"description":"Sort a new ticket by urgency."}

1. Read the ticket.
2. Pick an urgency.

MUST: check the calendar (tool; #list) before proposing a time.
BECAUSE: double bookings cost the customer a trip.

spec_validate reports the capability families it uses as requires: here ["connected","guidance"]. What an agent receives covers the whole text profile.

Protocol values

protocol on a connected object is a name, then optionally / and its versions apart by commas. A name is lowercase letters, digits and - starting with a letter (a2a, x402), or a reverse-domain name with a path (com.example/rail). The reader checks only the syntax: a value that doesn't match is a protocol-syntax error. Choosing a version is the host's.

ValueNameVersions
a2aa2aevery stable version
x402/2x4022
openapi/3.0,3.1openapi3.0, 3.1
mcp/2026-07-28mcp2026-07-28
com.example/rail/1com.example/rail1
A2Aprotocol-syntax error—
x402/protocol-syntax error—

A bare name means every version its binding marks stable. A binding is an extension manifest (format instruction-extension/1, role binding) that says which versions of a protocol exist, how mature each is, and how to compare them. A host speaking a version can serve a document that asks for another when the binding's rule says so:

  • exact: only the version as written.
  • semver-minor: from 1.0, the same major version at the same minor or above (3.1 serves 3.0); before 1.0, the same minor only (0.2 is not 0.3).
  • date: a revision date on or after the one asked for.

When no version both sides share is left, the host reports protocol-unsupported. The bindings the reference library ships (BINDINGS in packages/spec/src/bindings.ts):

BindingProtocolVersionsComparedKindsWhat it means
org.x402/x402x4021 (deprecated), 2 (stable)exactwallet, service—
org.openapis/openapiopenapi2.0 (deprecated), 3.0 (stable), 3.1 (stable)semver-minorservice, toolservice.src: the OpenAPI document (JSON or YAML), not the API's own address; tool.name: an operation's operationId in that document

The integrations policy

An organization decides which MCP servers, skills, agents and services its instructions may use, and which of a server's tools. That decision travels in the instruction's front matter, so any reader that parses the text knows it, however the text was fetched.

There are two keys with one shape:

  • integrations is the author's. It can only narrow what the instruction uses.
  • host-integrations is written only by the host that serves the instruction. A source that holds it is refused at release: host-matter-authored, "host-integrations is the host's: it is added when the instruction is served, so a source never holds it".
instruction.md
---
spec: "1"
title: Calendar helper
integrations:
  allowed: ["https://calendar.example.org/mcp"]
  servers:
    "https://calendar.example.org/mcp":
      blocked: [events.delete]
---

:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

Each key is a mapping with two keys of its own:

  • allowed: when present, every target the document's connected objects may use. An empty list allows none; an absent one restricts nothing.
  • servers: a server's target mapped to its tools. Each has blocked (tools not to use), default (allowed, the default, or blocked: what any other tool is) and, with default: blocked, allowed (the tools still allowed).

A target is a connected object's src, endpoint, registry or server that leaves the document. A relative path or a #id is the document's own and is never a target. Targets are compared normalized: an http(s) address with its scheme and host lower-cased and its default port, fragment and trailing slash dropped (its path keeps its case); any other target trimmed and lower-cased. Any other key, or a value of another shape, is an invalid-metadata error.

How the two layers combine

The reader merges the host's layer and the author's:

  • A target is allowed only when every layer that has allowed lists it.
  • A tool is blocked when any layer blocks it, or when any layer blocks by default and doesn't allow it.

So an author can narrow the host's policy and never widen it. An author's default: allowed doesn't reopen a server the host closed.

Against the merged policy, the reader reports two warnings. The object stays in the text as written.

  • tool-blocked: a tool whose name is blocked on its server, and each tool an mcp lists in tools or allow that is blocked there. "events.move: this tool is blocked in your workspace" when the host blocks it, "… by this instruction's integrations" when the author does. A tool in deny never reports.
  • integration-not-allowed: an mcp, skill, agent or service with a target outside the allowed ones. "… is not one of your workspace's integrations, so it is not used".

What instruction.md serves

instruction.md stores each version exactly as it was released. Whatever serves a version (the instruction:// resources, instructions_versions_read without resolve, a read link, the page's Markdown) puts the organization's current policy for the targets the text names into its front matter, as its own lines right after the opening ---. With no front matter, it adds one. With nothing to say (no restriction, no decisions on the servers the text names), it serves the bytes unchanged.

A sealed instruction is served as the envelope it was released as, with nothing added to it: its policy is only in the resource's md.instruction/policy. On a self-hosted server, served texts carry the block only with IMD_HOST_MATTER=on (the chart's config.hostMatter); it is off by default, and every served text is then the released bytes. See Self-hosting.

Plans On Team and Enterprise

Plans On Pro, Team, and Enterprise

The first badge is for Only approved integrations, which fills allowed. The second is for blocking a server's tools, which fills servers; on a plan without it, blocks are not served. Both are set in Settings ▸ Integrations: see Integrations and tool policy.

A workspace that allows only the calendar server and blocks two of its tools serves this source:

As released
---
spec: "1"
title: Calendar helper
---

:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

::tool{id=move server=#calendar name=events.move}

as:

As served
---
host-integrations:
  allowed: ["https://calendar.example.org/mcp"]
  servers:
    "https://calendar.example.org/mcp": {"blocked": ["events.delete", "events.move"]}
spec: "1"
title: Calendar helper
---

:::mcp{id=calendar title="Calendar" src="https://calendar.example.org/mcp" account=personal tools="events.list,availability.read" allow="events.list,availability.read" deny="events.delete"}
Read appointments for planning. Ask Alex before changing an invitation.
:::

::tool{id=move server=#calendar name=events.move}

The block's first line is host-integrations:, every other line starts with two spaces, each ends in LF, and values are JSON. The reader gives the effective policy (ReadResult.policy):

The effective policy
{
  "allowed": [
    "https://calendar.example.org/mcp"
  ],
  "servers": {
    "https://calendar.example.org/mcp": {
      "blocked": [
        "events.delete",
        "events.move"
      ],
      "default": "allowed"
    }
  },
  "from": {
    "host": true,
    "author": false
  }
}

and its warning:

Diagnostics
warning: tool-blocked: events.move: this tool is blocked in your workspace

An MCP resource read says so in its _meta, beside the digest of the released bytes:

_meta
{
  "md.instruction/digest": "sha256:…",
  "md.instruction/hostMatter": "host-integrations",
  "md.instruction/policy": {"allowed":["https://calendar.example.org/mcp"],"servers":{"https://calendar.example.org/mcp":{"blocked":["events.delete","events.move"]}}}
}

md.instruction/policy is the same policy as data. A version is never changed, but its policy can be: a pinned version served with a policy gets the cache hint md.instruction/cache {"maxAge": 30, …}, not {"immutable": true, …}, and its etag names the block too.

Signatures and the served lines

The block is outside the signed bytes. A version's digest and its author signature cover the source as released. A verifier given a served text checks the digest against each of its authored candidates: the text itself; the text without the host-integrations line and the indented lines after it, when the front matter opens with them; and, when that leaves an empty front matter, the text without it too. verifyAuthor in the instruction.md package does this, as the Go, Python and Rust libraries do. A block anywhere else in the front matter is the author's and is part of what they signed. See Signing and verification.

The delivered text carries no front matter, so it carries no policy either. A host that enforces the policy reads it from the served text or from md.instruction/policy.

Naming a tool never grants access

An instruction describes intended use. tools, allow and deny say what the agent should and shouldn't do; they don't make a tool callable, and they don't take one away. Access comes from the host:

  • The credential behind each account, which the machine holds.
  • The host's own permissions. instruction agents apply writes allow and deny as Claude Code's or Codex's own permission rules, and the organization's blocked tools join deny. See Servers, skills and accounts.
  • The organization's policy, served with the text.

A deny is a request the host may enforce. An agent whose host ignores it can still call the tool, if its credential allows the call. Give each account the narrowest credential the work needs.

What a host sets up

instruction agents apply and the runner read the root agent's servers and skills (format agent-machinery/1, machineryOf in the instruction.md package). Servers and skills inside a host-run agent are that agent's, not the root's. For the document under What the agent receives:

agent-machinery/1
{
  "format": "agent-machinery/1",
  "servers": [
    {
      "id": "calendar",
      "title": "Calendar",
      "url": "https://calendar.example.org/mcp",
      "account": "personal",
      "tools": [
        "events.list",
        "availability.read"
      ],
      "allow": [
        "events.list",
        "availability.read"
      ],
      "deny": [
        "events.delete"
      ]
    }
  ],
  "skills": [
    {
      "id": "triage",
      "title": "Triage a ticket",
      "description": "Sort a new ticket by urgency.",
      "body": "1. Read the ticket.\n2. Pick an urgency."
    }
  ],
  "skipped": [],
  "digest": "sha256:005133386bc5d296400fee311f61d2e569ae3bf7b46e33831df5082a993f6aca"
}

A server's allow drops any tool that is also in deny. digest is the SHA-256 of the servers and skills in canonical JSON, so a host applies again only when it changes. With the organization's catalog, a blocked tool joins its server's deny, and under Only approved integrations an unapproved server or skill is skipped. What can't be set up is listed in skipped, with why:

Why What to do
it has no id Give the object an id.
its address isn't https: <src> Use an https: address, or http: on this machine.
it is named by a registry, with no address to connect to Add src.
it has no address Add src.
the organization hasn't approved this server Use an approved integration, or ask an admin to add it in Settings ▸ Integrations.
its src isn't a SKILL.md on GitHub: <src> Point src at a GitHub file or folder, or write the skill's text in its body.
the organization hasn't approved this skill's source Use an approved source, or ask an admin to add it.
it has no text and no src Write the skill's text in its body, or add src.

If it doesn't work

What you see Why What to do
invalid-attributes: "… needs server=…" A tool without server or name. Add both: ::tool{id=… server=#… name=…}.
invalid-attributes: "an A2A agent needs src=… (its Agent Card) or endpoint=…" protocol=a2a with neither. Add the Agent Card's address as src, or endpoint.
protocol-syntax A protocol that isn't a name with optional versions, such as A2A or x402/. Write it in lower case, with versions after one /: x402/2.
tool-blocked A tool the workspace or the instruction blocks. Use another tool, or ask an admin to allow it in Settings ▸ Integrations. When the instruction's own integrations blocks it, take it out of blocked there.
integration-not-allowed A server, skill, agent or service the workspace hasn't approved, or that the instruction's own integrations leaves out. Use one of the integrations, or ask an admin to add it. For the instruction's own list, add the target to integrations.allowed.
host-matter-authored on release The source holds host-integrations, for example after copying a served text. Remove the block. To narrow what the instruction uses, write integrations.
An author signature fails over a served text A verifier that doesn't take the host's lines out first. Update the library: verifyAuthor checks the authored candidates.

More messages are on Diagnostics and fixes. Still stuck: ask us.

Questions

Does naming a tool in an instruction give the agent access to it?

No. tools, allow and deny describe intended use and grant nothing. What the agent can call depends on the credential the machine holds and on the host's own permissions. See Naming a tool never grants access.

Can an author allow a tool the workspace blocks?

No. The reader merges the two layers so that a tool is blocked when any layer blocks it. An author's integrations can only narrow the host's policy.

Why does the text I fetched have front matter I didn't write?

That is the organization's policy, host-integrations, added when the version is served. It is outside the signed bytes, and the digest and the signature still verify over the served text. See What instruction.md serves.

Can a skill come from somewhere other than GitHub?

A skill's text can always be written in its body. A src is fetched only from github.com or raw.githubusercontent.com; any other address is skipped with a reason.

When is an agent one the host runs?

When it has none of protocol, src and endpoint. Its body is then its instruction, and it reports to the agent around it, or to the root. See Agents the host runs, and the agent manifest.

Last checked against the product:

Was this page helpful? Report a problem