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 to browse or search the realm's capability catalog, then expand the exact working contract it needs: fields, selectors, filters, actions, and claims. Also a timeline read — transient, re-fetched when needed.

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 working contract

The last level is progressive and just in time. Before the agent searches, reads, or changes an object, it uses object_schema to navigate from the realm's root to one exact working contract:

object_schema(namespace="docs")
  -> root catalog: documents · editing · discussion · exports

object_schema(namespace="docs", schema_path="/discussion")
  -> one nested catalog node

object_schema(namespace="docs", query="reply to a comment",
              search_mode="hybrid")
  -> ranked capabilities with catalog_path + object_kind + schema_operation

object_schema(namespace="docs", object_kind="docs.comment_thread",
              schema_operation="object.action:reply_comment")
  -> the exact executable contract

Each call chooses one projection: browse with schema_path, search with query, or expand an exact contract with object_kind plus schema_operation. In particular, query and schema_operation are not combined in one call; the search result supplies the identifiers for the next exact expansion.

The catalog is recursive: a large provider can group capabilities by domain and subdomain to any useful depth. The query searches those provider-declared capabilities, not the user's documents. The agent reads the selected contract, then makes the object call. Like provider.about, each schema result is a timeline read that can be compacted and fetched again when needed.

The schema is the realm's language

The schema does not repeat the provider's API. It names the things a user and an agent recognize, how they relate, and what can happen to them. A document realm, for example, can describe documents, tabs, comment threads, replies, and exports. Its actions can cover finding and copying a document, editing a selected tab, replying to a matching comment, or exporting a portable file.

This is a lightweight operational domain model, not an automatically inferred formal ontology. The provider author chooses the vocabulary and executable affordances. One backend may publish more than one named-service projection when different use cases need different objects, actions, or authority; each projection remains a coherent language instead of a mirror of every API method.

The agent should not ask the user for a Google commentId. The schema can express: comment text contains “payment terms”, author is me, resolved is false, action is reply. The named-service provider reads bounded document comments, resolves one matching thread, performs the provider call, and returns the updated result. Provider IDs stay behind that boundary as machine handles.

Tabs use the same idea for document edits: “append this to the second tab” can be expressed by position, title, title fragment, or hierarchy without asking the user for a Google tabId.

This is domain language, not a promise that KDCube adds semantic search over provider objects. Object search goes only as far as the provider allows. KDCube can evaluate explicit fields in a bounded provider response, such as one document's tabs or comments, but it does not build an index over the provider's object space. Meaning-based object search is exposed only when the provider supplies it.

Capability search is separate. Its corpus is the app-owned schema declaration: catalog labels, descriptions, keywords, kinds, and operation ids. KDCube can index that small declaration in shared bundle storage and search it lexically or, when embeddings are available, semantically or in hybrid mode. The result reports which mode actually ran.

The provider-owning bundle prepares that index once per immutable, timestamped generation. Its identity includes the catalog declaration and embedding profile, so an unchanged load reuses the same generation and a meaningful change creates the next one. The newest successful loader retains the current generation plus its immediate predecessor and removes older file families. Agents only query the prepared capability declaration; they do not build it.

The provider also has to be honest about what it can express. Google's stable Drive comments API provides document-level threads. Native tab-anchored comments and richer comment operations are part of the Google Docs API Developer Preview. If that preview capability is not configured, the schema must not advertise it. A request for a tab-anchored comment receives a clear capability error; it is not silently turned into a document-level comment.

The current KDCube Docs adapter resolves tabs by title, literal title fragment, position, or hierarchy. It resolves document-level comments by literal text, quoted text, author, resolved state, or position. Ambiguous matches return choices. Native tab-anchored comments remain a preview-only provider capability.

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.

Since then: the human projection

The same three-level self-description gained a fourth projection — for people. A realm now declares a presentation layer beside its schema (purpose sentence, honest works-with line, human labels per operation and action, object-kind one-liners), and the capability picker renders it as the realm's service card. The arc's test doubles: the agent answers its three questions from intro/about/schema; the user answers theirs — what does this service do, what does it touch, how do I turn part of it off — from the card.

Documentation on GitHub

The live docs behind this entry:

• Named Services: The Interface Between Agents And App Realms
• Create a Named Service: Teach the Platform Your Domain
• Connect Your Named Services To Claude Code
• Named services — overview
• Ontologic tools
• Writing a provider
• Connecting a namespace