What are resource annotations, used for?

4 minadvancedmcpresourcesannotations

Quick Answer

Resource content blocks can carry an optional annotations object with audience (an array like ["user"] or ["assistant"], indicating who the content is really intended for) and priority (a number from 0 to 1 signaling how important this content is relative to other context, when something has to be dropped or truncated). A host with limited context budget can use priority to decide which resources to trim first, and audience to decide whether something should be shown in a UI to the human, fed to the model, or both. These annotations don't change the actual content, they just give the host extra signal for making inclusion and presentation decisions when it can't include everything.

Detailed Answer

When a host juggles many resources against a finite context window, it needs some basis for deciding what to keep and what to cut. Annotations give it that basis without the host having to guess.

Example

{
  "uri": "file:///project/CHANGELOG.md",
  "mimeType": "text/markdown",
  "text": "## v2.1.0\n...",
  "annotations": {
    "audience": ["assistant"],
    "priority": 0.3
  }
}

This says: the content informs the model's reasoning, and doesn't need its own dedicated spot in the human-facing UI. It's also relatively low priority compared to other context competing for the same budget.

How a host might use these fields

audience: a value of ["user"] suggests content meant to be displayed directly, like a rendered image the user should see. ["assistant"] suggests content meant to inform the model's reasoning, without necessarily being shown verbatim in the UI. Some content is annotated for both.
priority: when a host must trim included resources to fit a context budget, it can sort candidates by priority and drop the lowest-priority ones first. That beats trimming arbitrarily — by resource order or file size — in a way that might discard something important.

Why this is optional metadata, not required

Most simple servers never need this. Annotations exist for the case where a host aggregates large amounts of resource content from multiple servers at once, and needs a principled way to prioritize. A single-purpose server with a handful of small resources gets no practical benefit from priority/audience hints, since there's rarely a meaningful tradeoff to make between them.

Related Resources

Resources