How a named service introduces itself: intro, about, schema

When an agent connects a new namespace through a named service, it has to learn a realm it has never seen. The named service answers in three ways, not one — and the difference between them is the whole point. They sit at different costs and arrive at different moments:

• intro — always there, no call. The realm's one-line self-introduction, rendered into the agent's system instruction the moment the namespace is connected, so it is never pruned.
• provider.about — a tool the agent calls when it decides to engage, for the fuller capability picture. Its result lands in the timeline, where it can be compacted away over time.
• object_schema — a tool the agent calls just before it writes, for the exact JSON shape of one object kind. Also a timeline read — transient, re-fetched when needed again.

Cheap-and-always → deep-on-demand → precise-just-in-time.

intro — the catalog-level self-introduction

This is the one that matters most, because it is the only one that is passive. The agent never asks for it. When a namespace is connected, the provider's published intro line lands directly in the agent's catalog/roster, right alongside the tools it can call:

Named-service namespaces available to this agent
(pass one as the `namespace` argument):
- `parts`  — Spare-parts inventory — stock levels, suppliers, and reorder
             status. Look here to check availability or place a reorder;
             a "low_stock" event means a part dropped below its threshold.
- `tickets`— Support tickets — open issues, status, and assignee. ...
- `notes`  — Shared team notes — short kept facts pinned for later. ...

That single line does three jobs at once. It tells the agent what the realm is, when it should reach for it, and what the events arriving from that namespace mean — so when a parts event shows up mid-conversation, the agent already understands it without a tool call. The intro is semantic grounding: it is what lets the agent connect a namespace it has never seen to the work in front of it, and interpret that namespace's inbound events, for free.

A provider publishes it at registration time, and it is rendered into the agent's ReAct system instruction as one row per connected namespace — part of the stable instruction block, not a timeline message. That is why it is the anchor: the instruction block is always in front of the model and is never pruned, so the intro is structurally permanent where everything else here comes and goes. If a provider ships no intro, the roster falls back to the provider's label, then to the bare namespace name — so the line is always present, just less helpful.

provider.about — the on-demand deep dive

Once the intro has told the agent which namespace fits, provider.about is the tool it calls to learn what exactly that namespace can do: its purpose in full, its searchable scopes, the ref grammar, the object kinds, the domain language. The intro is a sentence in the system instruction; provider.about is the manual you open when you've decided to read it. Its result is read into the timeline as a tool result, so it costs a round-trip and is prunable — the platform compacts older timeline content, so the description ages out and the agent simply re-fetches it the next time it needs the detail.

object_schema — the just-in-time write shape

The last level is the narrowest and the latest. Right before the agent mutates an object, it calls object_schema for one object_kind to get the exact payload: the fields, which are required, the enums, the filter contract, and how each collection field applies on write. The agent should not guess an object's body from a card it saw or an old example — it asks for the shape, then sends the write. Like provider.about, the schema is a timeline read that can be compacted away afterward — which is fine, because it is fetched just-in-time for one write and not meant to linger. object_schema is precise and transient; it answers "what JSON do I send to change this," nothing broader.

The arc

Three questions, three moments — and two places. The intro is foundational because it lives in the system instruction and never ages out; about and schema are timeline reads that the platform compacts over time and the agent re-fetches on demand. The mistake is to collapse them — to treat the intro as something the agent has to call, or to blur about and schema into one "describe the provider" step. Keeping them distinct is what makes the catalog cheap and permanent, the deep dive deliberate, and the write precise.

Documentation on GitHub

The live docs behind this entry:

• Named services — overview
• Writing a provider
• Connecting a namespace