Use Ontology with agents

Preview Agents read your ontology through six read-only MCP tools. This page shows which tool answers which question, and how an agent should read a bounded response before it writes a query.

Before you begin

An administrator has installed the Ontology app, and the Ontology Binding app if agents need table names. See Install and manage apps.
Your MCP client is connected to Atlan. See Connect client to MCP Gateway. Reconnect after an app is installed so the client lists the new tools.
You have the ontology ID and an exact release ID (rel_…). Studio shows the release ID after you publish, and the ontology ID is the part of the Studio address after #/o/.

Choose a tool

The agent needs to…	Call	Returns
Understand the business terms in a question	`extension__ontology__get_context`	The smallest relevant set of definitions from one release, ranked, with a token estimate
Know which tables, columns and joins to query	`extension__ontology_binding__get_context`	The same definitions paired with their published mappings, plus a report of missing mappings
Find the policy or control in force on a date	`extension__ontology__get_records`	Knowledge records valid at one business instant
Ask a structural question about the model	`extension__ontology__get_query_plan`	A logical plan for a SPARQL `SELECT`, and results when it only reads model metadata
Hand the model to an RDF, OWL or SKOS tool	`extension__ontology__get_export`	A deterministic document with a loss report
Check a model it drafted before a person saves it	`extension__ontology__get_import_preview`	Proposed definitions, validation results, and a preview ID

All six tools are read-only. None of them saves a draft, publishes a release, reads warehouse rows or runs SQL. To turn an agent’s proposal into drafts, a person approves it in Studio; see Review agent-drafted definitions.

Example: answer a question about orders

A user asks, “Which customers placed more than three orders last month?” Here is how an agent answers it from the retail model.

Open an MCP session

Call mcp__initialise once per conversation and pass its session_id to every tool call. Each call also takes a rationale: one sentence on why the agent is calling the tool, recorded for audit.

Get the meaning

Ask the ontology release for the definitions the question touches:

{
  "ontology_id": "ontology_01example",
  "release_id": "rel_01example",
  "query": "customers orders",
  "include": ["object_types", "link_types"],
  "max_resources": 10,
  "max_tokens": 4000,
  "session_id": "mcp_session_<your-session-id>",
  "rationale": "Read the released definitions for customers and their orders."
}

The response names the release and manifest_digest it read. Each resource has selected_because (for example term_match or relationship_path) and a depth from the direct match. Here it returns Customer, Order and the places link, which says each Order has exactly one Customer.

Check that nothing was cut

Read truncated before you rely on the answer. If it is true, follow refinement_hints: use more specific terms, narrow include, or raise max_resources or max_tokens within their bounds. See Read bounded context.

Get the physical mappings

Ask the binding release for the same question:

{
  "binding_id": "ontology_binding_01example",
  "release_id": "rel_01bindingexample",
  "query": "customers orders",
  "session_id": "mcp_session_<your-session-id>",
  "rationale": "Find the declared tables and joins for customers and orders."
}

Each resource pairs the logical_definition with its binding: Customer in retail.core.customers, Order in retail.core.orders, and places joined on customer_id. Read the handoff report: its blockers list anything unmapped, such as property_unmapped for ordered_at, with a remediation. The response always reports source_verification: declarative_unverified and is_execution_verified: false, so treat the names as declarations.

Query with the agent's own connection

The agent writes SQL from the mapped names and runs it through its own, separately governed data connection. Ontology doesn’t run it.

Add governed evidence (optional)

If the answer depends on a policy, such as which orders count as returns, call extension__ontology__get_records with as_of set to the business date in question. It returns only records valid at that instant.

Read bounded context

Context tools return a slice of the release sized for a prompt, not the whole model. You set the bounds; the response tells you whether they cut anything.

Input	Ontology context	Binding context	What it controls
`query`	1 to 4,096 characters	1 to 4,096 characters	The business terms to match. Common plurals and a few synonyms, such as customer and client, also match.
`max_resources`	1 to 50, default 15	1 to 50, default 20	How many definitions come back.
`max_depth`	0 to 4, default 2	0 to 3, default 1	How many link hops to follow from a direct match.
`max_tokens`	1 to 32,000, default 12,000	128 to 32,000, default 8,000	The estimated token budget for the returned definitions.
`include`	Optional list of kinds	Not available	Restrict results to kinds such as `object_types` or `concepts`.

Read these response fields before using the result:

Field	Meaning
`truncated`	`true` when more definitions matched than `max_resources` allows, or the next one would exceed `max_tokens`.
`refinement_hints`	Fixed advice when the result was cut, or when nothing matched.
`token_estimate` (`estimated_tokens` for bindings)	Estimated size of the returned definitions.
`release_id`, `manifest_digest`	The exact release read. Keep them with the answer for audit.

A shallow max_depth leaves linked definitions out without setting truncated, so raise it if a related type you expect is missing. A request outside a bound is refused with a 422 rather than silently clamped.

Verify

The context response’s release_id is the release you meant, and its manifest_digest matches the Release checksum in Studio.
truncated is false, or the agent has followed the refinement hints.
In Studio, Agent context > Ask with the same question and release returns the same definitions.

Ontology: how releases, bindings and agents fit together.
Bindings: why a binding is locked to one ontology release.
All MCP tools: every tool your identity can call.
Troubleshoot Ontology: truncated and refused context queries.

Skill management

Agent management

AI Gateway

Metrics Studio

Ontology

Before you begin

Choose a tool

Example: answer a question about orders

Read bounded context

Verify

​Before you begin

​Choose a tool

​Example: answer a question about orders

​Read bounded context

​Verify

​Related

Before you begin

Choose a tool

Example: answer a question about orders

Read bounded context

Verify

Related