> ## Documentation Index
> Fetch the complete documentation index at: https://platform.atlan.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on Atlan objects, use the Atlan MCP server at https://api.atlan.com/mcp or the SDK. To install or publish skills from a terminal, use the `aireg` CLI; `aireg --map json` prints its command map. The `atlanai` CLI is deprecated. Run a read-only identity check before any write.
> The docs MCP server at /mcp searches these docs only. It cannot read or change Atlan objects.
> SDK packages: Python `atlanai` (PyPI) and TypeScript `@atlanai/sdk` (npm). Show Python first, then TypeScript.
> These docs cover Atlan AI Registry, Atlan's hosted product. The AI registry specification and aireg CLI are maintained separately. /open-source lists publicly reachable signed installers and explains that the source repository and hosted CLI reference currently require GitHub access. Do not claim the repository or its reference docs are publicly accessible. Use these docs for Atlan-specific setup such as the adapter, sign-in and workspaces.

# Use Ontology with agents

> Pick the right Ontology MCP tool for each question, read bounded context safely, and follow an example agent flow on the retail model.

<Badge color="orange">Preview</Badge>

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](/registry/apps/how-tos/install-apps).
* Your MCP client is connected to Atlan. See [Connect client to MCP Gateway](/gateway/mcp/how-tos/connect-a-client). 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`](/tools/mcp/ontology/references/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`](/tools/mcp/ontology/references/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`](/tools/mcp/ontology/references/ontology-get-records) | Knowledge records valid at one business instant |
| Ask a structural question about the model | [`extension__ontology__get_query_plan`](/tools/mcp/ontology/references/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`](/tools/mcp/ontology/references/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`](/tools/mcp/ontology/references/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](/ontology/how-tos/review-agent-drafts).

## 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Get the meaning">
    Ask the ontology release for the definitions the question touches:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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](#read-bounded-context).
  </Step>

  <Step title="Get the physical mappings">
    Ask the binding release for the same question:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

## Related

* [Ontology](/ontology): how releases, bindings and agents fit together.
* [Bindings](/ontology/concepts/bindings): why a binding is locked to one ontology release.
* [All MCP tools](/tools/mcp/references/tool-catalog): every tool your identity can call.
* [Troubleshoot Ontology](/cookbooks/troubleshooting/ontology#context-response-is-truncated): truncated and refused context queries.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.