KDCube
← Engineering blog
2026-07-06 · Deep

Named Services: Ontologic Tools

named-services ontology realms use-cases grants object_ref object.search object.action

Named services give an agent one small grammar — list, search, get, act — and let every domain teach its own vocabulary at runtime. A domain models itself once, as a realm: typed objects, self-contained refs, its own search questions, and role-guarded use cases. Any operator — the chat agent, an external agent over MCP, a UI — works every realm through the same verbs.

Every tool an agent carries costs something before it is ever called.

It occupies context. It competes for the agent's attention at every decision. It ships its own parameter shapes, its own error dialect, its own half-documented conventions. Connect an agent to mail, chat, tasks, boards, and memory the direct way — one tool per operation — and the tool list grows with every domain: five tools for mail, seven for the messenger, four for the tracker. Twenty domains later the agent spends its judgement choosing between eighty near-synonyms, and every new domain makes every old one slightly harder to use.

Named services take the other road. The agent carries a fixed grammar of generic operations, and each domain plugs in as a realm — a namespace that describes itself: what its objects are, how to find them, what can be done to them, and who may do it. The grammar is learned once. The domains are open-ended.

TWO WAYS TO CONNECT DOMAINS TO AN AGENT one tool per operation every domain ships its own verbs into the context agent search_gmail read_gmail_message send_gmail download_attachments forward_gmail search_slack list_channels read_history post_message upload_file memory_search task_create canvas_patch … tool count grows with every domain one grammar, self-describing domains generic operations; each realm teaches its own vocabulary agent THE VERBS · FIXED about schema list search get action upsert host_file delete THE REALMS · OPEN-ENDED mail: slack: conv: mem: cnv: task: … tool count stays constant; domains scale
Two ways to connect domains. The grammar is constant; the realms are open-ended.

The whole idea in one line

The platform fixes the verbs; each domain declares its nouns and use cases; grants decide who may conjugate what.

the verbs   about · capabilities · schema · list · search · get
            action · upsert · host_file · delete            (fixed)
the nouns   object kinds + refs, declared per realm         (open-ended)
the guard   per-operation grants at the door,
            the realm's own authorization inside            (role-guarded)

This is why the word ontologic fits: a realm is a small ontology — the domain's entities, their identities, their relations, and the bounded operations that make sense on them — published behind a uniform interface instead of a pile of bespoke endpoints.

What a realm declares

Modeling a domain as a realm means answering five questions. The mail: realm answers them like this:

ANATOMY OF ONE REALM — WHAT A DOMAIN DECLARES (EXAMPLE: mail:) object kinds the domain's nouns — mail.account · mail.message · mail.attachment typed objects refs mail:gmail:<account>:message:<id> — every emitted ref resolves later, with no ambient state round-trip search the domain's own questions — filters like account_id · gmail_query; hits carry account labels lean hits actions named use cases, each behind a grant — send · forward · download_attachments · request_upload role-guarded about · schema the realm explains itself — account selection, file delivery, and the consent-error contract are part of the model self-teaching Declare these five things and every operator — chat agent, external agent, UI — can work the domain through the same grammar.
Declare these five things once; every operator works the domain through the same grammar.
  • Object kinds are the domain's nouns — typed, with the fields an operator can actually act on. Internal ranking scores and storage details stay out of the model.
  • Refs are the identities. A ref emitted by search or list is a promise: hand it back to get or action later — from another process, another session, another client — and it resolves. Refs embed what they need (mail:gmail:<account>:message:<id> carries its account), so no ambient state is required.
  • Search speaks the domain's own question language. Mail filters by account and provider query; the tracker filters by status and assignee; the board searches pinned text. The filters are self-describing — type, meaning, default — so an operator can fill them without guessing.
  • Actions are the domain's use cases, named and bounded: send, forward, post_message, request_upload. Each action is a deliberate decision about what this domain offers to outside operators — and each sits behind a grant.
  • About and schema make the realm self-teaching. An operator that has never seen the namespace reads the schema and knows how accounts are selected, how files are delivered, and what every denial will look like.

Same verb, every domain's vocabulary

Once the grammar is fixed, domains stop being integrations and start being vocabularies. The operator's skill transfers completely: learn to work one realm, and the next realm costs only a schema read.

ONE GRAMMAR × MANY REALMS — SAME VERB, EACH DOMAIN'S OWN VOCABULARY mail: slack: task: cnv: search receipts from a vendor, across labeled accounts decisions in a channel, messages or files open issues, filtered the tracker's way pinned cards about a topic get a message with body and attachment refs channel history, a file by its ref one issue, its files and links a board with cards, comments, provenance act send · forward request_upload post_message upload_file upsert issue host_file upsert = patch comment · move
The grammar is the interface; the vocabulary is the domain's.

A real trace, end to end, from an external agent connected over MCP — finding the pictures a teammate posted with a phrase:

search  namespace=slack  query="ПР 176 in:#kdcube-users"
   -> one hit: slack:…:message:C…:1782589383.978809   (labeled account, channel, ts)
get     the channel ref, window = that one timestamp
   -> the message object: text + THREE file refs (slack:…:file:F…)
get     each file ref
   -> download: {encoding: "url", url, expires_at}    (signed, short-lived)
HTTP GET each url
   -> three PNGs, bytes never inside a tool result

Four generic calls, zero Slack-specific tooling on the agent's side. The same four calls, with different vocabulary, walk mail, tasks, boards, and memory.

Role-guarded use cases

Exposing a domain to outside operators is an act of trust, so the model carries its guard with it — in two gates that answer two different questions.

ROLE-GUARDED IN TWO GATES operator agent or app gate 1 · the door delegated grants, consented once, checked per operation mail:read mail:send slack:read slack:w… may this client call this verb here? identity rides along gate 2 · the realm the domain authorizes with its own rules, per identity gmail:send slack:* realm's own ACLs may this user do this, here, now? the domain objects · use cases a denial is an answer: reason · candidates · where to fix it · retry hint
Grants at the door, the realm's own rules inside — and a denial is an answer, never a dead end.

Gate one belongs to the door. When an operator connects, the user consents to specific grants — mail:read, slack:write — and every call is checked against them, per namespace and per operation. The search verb on mail: can be granted while action stays withheld.

Gate two belongs to the domain. The realm receives the operator's identity and authorizes with its own rules — connected-account claims for provider realms (gmail:send, slack:files:write), the realm's own access model for everything else. The platform passes identity through; the domain stays the authority on its own data.

Gate two is demand-driven: nothing is asked up front — the ATTEMPT that hits a missing claim raises the ask, scoped to exactly that operation's claims, while the turn keeps working. And when a gate says no, the answer is part of the ontology too:

needs_connected_account_consent
  reason:              connect_required | claim_upgrade_required |
                       reconnect_required | account_required
  candidates:          [{account_id, label, email, workspace, status, claims}]
  connection_hub_url:  ABSOLUTE deep link into the seeded consent plan
  retry_hint:          whether the same call succeeds afterwards
  instructions:        the agent's next step, in words it can relay

An operator that hits a wall learns which wall, who can open it, and whether to retry. The agent relays a fix; the user performs one consent; the call succeeds.

Model your own domain

The recipe generalizes to any subsystem you want operators to work with. Take a logistics desk as an example — shipments, carriers, exceptions:

  1. Name the nouns. freight.shipment, freight.carrier, freight.exception — the entities an operator reasons about, with the fields they can act on.
  2. Give them identities. freight:shipment:<id>, freight:exception:<shipment>:<seq> — refs that round-trip with no ambient session.
  3. Write the questions. Search filters the desk already thinks in: status, carrier, route, overdue_days — each self-described.
  4. Name the use cases. reschedule, assign_carrier, escalate_exception, attach_pod — the operations the domain chooses to offer, each a bounded verb with a declared payload.
  5. Guard them. freight:read for search/get; freight:dispatch for the actions that move real trucks. The door checks grants; the domain applies its own approval rules inside.
  6. Teach it. Put the selection rules, the file story, and the denial shapes into about/schema — so the first operator to connect needs no onboarding call.
  7. Teach it to humans too. Declare the presentation layer beside the schema: a purpose sentence, an honest works-with line, human labels per operation and action ("Reschedule a shipment"), object-kind one-liners. The capability picker renders exactly this as the realm's service card — the user reads it, understands it, and narrows it per operation.

The test of a good realm now has two readers: an operator who has never seen your domain reads schema, runs search, follows a ref through get, and performs one guarded action — correctly, on the first try; and a user who has never seen your domain reads its card and knows what it does, what it touches, and how to turn any part of it off.

One model, every operator

The same declaration serves every kind of operator the platform hosts:

  • The chat agent reaches realms as tools inside its turn — search recall across conversations, board patches, task updates.
  • External agents over MCP connect to one gateway surface, consent to grants, and work the same realms with the same verbs — including moving real files through signed upload slots and download URLs.
  • UIs treat refs as draggable, openable objects: a card pinned to a board, a task opened in its tracker, a memory focused in its viewer — the realm resolves what the ref means.
  • Automations address the same objects by the same refs on a schedule, with the same guards.

That is the payoff of modeling the domain once, ontologically: the vocabulary is written one time, by the people who own the domain — and every operator, human-driven or agentic, inherits it.

Read more

KDCube Deep · 06.07.2026