Manifest

The plugin's interface to the LLM. Structured metadata the runtime composes into the system prompt and feeds to the discovery meta-tools.

What it is

Every plugin declares a manifest of type PluginManifest. It is not human documentation — it is structured metadata the LLM reads. The runtime uses it three ways:

  1. The Tier-1 prompt block — the "Available Capabilities" list rendered for always plugins on every turn.
  2. list_capabilities — the meta-tool the agent calls to enumerate what it can load.
  3. load_capability — the meta-tool that returns a manifest in full when the agent activates a plugin mid-conversation.

On the Workers runtime (@ixo/oracle-runtime-workers 0.39.0 and later) it is also used two more ways: the one-line on-demand catalogue in the system prompt (from brief), and the capability router, which reads summary and whenToUse to decide which plugins a message needs. See Meta-tools and loading.

What each field is for

FieldPurpose
titleHuman-readable label. Distinct from name (kebab-case unique ID).
summaryOne-line description. Heads each Tier-1 entry for always plugins as - **{name}** — {summary}.
whenToUseTrigger phrases. The single most important field — quality here determines whether the LLM picks the plugin when it should. Required when visibility !== 'silent'. The first two render into Tier-1 as a When to use: sub-bullet. On the Workers runtime the capability router reads every line, with the summary, to decide whether to preload the plugin.
whenNotToUseAnti-pattern phrases. Use to disambiguate from overlapping plugins. The first renders into Tier-1 as an Avoid for: sub-bullet.
examplesFew-shot user-message → tool-call bindings. Cross-checked at boot — every example's tool must reference a tool this plugin registers. The first renders into Tier-1 as an Example: sub-bullet.
tagsLowercase labels for search.
categoryOne of: data, communication, automation, memory, integration, ui, auth, observability, core.
visibilityalways / on-demand / silent. See Visibility tiers.
stabilitystable / beta / experimental. Surfaced as a hint to the agent.
requiresCloudflare Workers runtime only. User-controlled Authorization Network (UCAN) capabilities the user's delegation must grant before the plugin can be loaded or its tools run. See requires.
briefWorkers runtime 0.39.0 and later. A few words (at most 60 characters) on what load_capability adds: the plugin's line in the on-demand catalogue. Falls back to a clipped summary. See brief.
onDemandToolsWorkers runtime 0.39.0 and later. Tools kept out of the tool list until load_capability names the plugin, while the rest of the plugin stays as its visibility says. See onDemandTools.
routableWorkers runtime 0.39.0 and later. false keeps the capability router from preloading the plugin; it can still be loaded. See routable.

Full schema table and validation rules live at Manifest schema reference.

Where the agent sees it

Tier-1 plugins pay token cost on every turn forever — and not just the summary: each entry also renders whenToUse, whenNotToUse, and the first example as sub-bullets, so manifest length is prompt length. on-demand plugins cost nothing in the prompt until the agent loads them (on the Workers runtime, from 0.39.0, one short catalogue line each). silent plugins are never listed in Tier-1 and can't be loaded through the meta-tools (note: a silent plugin's tools, if it ships any, are still bound and callable — silent is not a security boundary).

Writing a good manifest

  • Be specific in whenToUse. "Weather questions" is too vague. "User asks about current weather, temperature, precipitation, or wind in any city" is precise. Name what the plugin does: the capability router decides from these lines and the summary.
  • Give an on-demand plugin a brief on the Workers runtime. It is what the model reads about the plugin in the catalogue when it decides whether to load it.
  • Use whenNotToUse to disambiguate when your plugin conceptually overlaps with another (Firecrawl vs Sandbox vs Domain Indexer is the canonical case).
  • Examples should cover the typical patterns, not just the obvious one.
  • Keep tags lowercase. They're for search ranking, not display.
  • Pick visibility deliberately. Default to on-demand; promote to always only when the agent needs the plugin on nearly every turn.
Tip

The manifest is the part of your plugin the LLM reads most. Treat it like a system prompt: write it carefully, test it with real user messages, and iterate. A vague manifest is the most common reason a plugin doesn't fire when it should.

Write a plugin

Where the manifest lives in code.

Manifest schema reference

Exact field types and constraints.

Source: PluginManifest.