Ontology CLI

<!-- Sub-reference for the `ontology-cli` skill, `consumption` mode. Indexed directly from `skills/ontology-cli/SKILL.md`. -->

ontology-cli consumption — Verified calls and troubleshooting

Verified Ontology Agent MCP calls and troubleshooting. Selection rules live in the consumption mode reference indexed from SKILL.md.

Contents

Call template

WS and ONT are resolved workspace/item GUIDs, never guesses. Resolve within the named workspace; use Catalog Search only when none was supplied (see 0. Resolve the IDs). APIHOST is https://api.fabric.microsoft.com. Use a body file: inline questions break shell quoting.

az rest --method post \
  --url "$APIHOST/v1/mcp/dataPlane/workspaces/$WS/items/$ONT/ontologyEndpoint" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "Content-Type=application/json" "Accept=application/json, text/event-stream" \
            "x-ms-fabric-skill=ontology-cli" \
  --body "@/tmp/payload.json" 1>ont_resp.json 2>ont_err.txt
cat ont_resp.json

The --resource audience is https://api.fabric.microsoft.com. Allow at least 120 seconds per ask_ontology call.

PowerShell: prepare an absolute UTF-8-without-BOM payload and validate it locally before POST, following consumption/request-files.md, indexed in SKILL.md. Pass the same quoted "@$payloadPath" to the CLI; recreate variables in fresh shells.

Do not call the variable HOST. In PowerShell $host is a reserved automatic variable, the assignment fails, and the call has to be re-issued -- which bills the agent twice.

Capturing the answer without paying twice

Each tools/call is billed. Save the complete first response with 1> and read it in the same command. Never call once for --query result.isError and again for content: Keep $payloadPath pointing to the actual request you prepared. In a fresh shell, recreate that request's absolute path; do not replace it with a discovery filename.

# correct -- the answer is on disk before anything tries to display it
$null = Get-Content -LiteralPath $payloadPath -Raw -ErrorAction Stop |
  ConvertFrom-Json -ErrorAction Stop
az rest --method post --url "$APIHOST/v1/mcp/dataPlane/workspaces/$WS/items/$ONT/ontologyEndpoint" `
  --resource "https://api.fabric.microsoft.com" `
  --headers "Content-Type=application/json" "Accept=application/json, text/event-stream" `
            "x-ms-fabric-skill=ontology-cli" `
  --body "@$payloadPath" 1>ont_resp.json 2>ont_err.txt
function ConvertFrom-McpResponseText([string]$text) {
  try {
    $json = $text | ConvertFrom-Json -ErrorAction Stop
    if ($null -ne $json.id -and ($json.PSObject.Properties['result'] -or $json.PSObject.Properties['error'])) {
      return $json
    }
  } catch {}
  $events = [regex]::Split($text.Trim(), '\r?\n\r?\n')
  for ($i = $events.Count - 1; $i -ge 0; $i--) {
    $data = @(($events[$i] -split '\r?\n') |
      Where-Object { $_ -match '^data:' } |
      ForEach-Object { $_ -replace '^data:\s?', '' }) -join "`n"
    if ($data -and $data -ne '[DONE]') {
      try {
        $json = $data | ConvertFrom-Json -ErrorAction Stop
        if ($null -ne $json.id -and ($json.PSObject.Properties['result'] -or $json.PSObject.Properties['error'])) {
          return $json
        }
      } catch {}
    }
  }
  throw 'Ontology MCP response contained neither JSON nor a valid SSE data frame.'
}
$j = ConvertFrom-McpResponseText (Get-Content ont_resp.json -Raw)
if ($j.PSObject.Properties['error']) {
  throw ("Ontology MCP JSON-RPC error: " + ($j.error | ConvertTo-Json -Depth 30 -Compress))
}
"isError=" + $j.result.isError
$j.result.content | Where-Object type -eq 'text' | ForEach-Object text

Do not capture stdout into $resp, guard on it being empty, then write it: a wrapper can lose stdout after a successful slow call. Redirect to disk first. Recover display or projections from that file; never re-send the body.

For PowerShell-native HTTP, use Invoke-WebRequest so either JSON or SSE remains raw text; do not redirect an Invoke-RestMethod object through the table formatter:

$headers.Accept = 'application/json, text/event-stream'
$response = Invoke-WebRequest -Method Post -Uri $uri -Headers $headers -Body $body
$response.Content | Set-Content response.txt
$j = ConvertFrom-McpResponseText $response.Content

Verbatim JSON replies

For an explicit raw-schema request, do not reconstruct JSON or shorten identifiers while composing the answer. In the same PowerShell invocation that parses the saved response into $j, construct and check the exact reply draft:

function Get-VerifiedOntologyReply([string]$serviceText, [string]$draftPath) {
  if ([string]::IsNullOrWhiteSpace($serviceText)) { throw 'Saved Ontology response has no text to deliver.' }
  $draft = Get-Content -LiteralPath $draftPath -Raw -Encoding UTF8 -ErrorAction Stop
  if (-not $draft.Contains($serviceText)) {
    throw 'Reply draft changed the service text. Rebuild it from the saved response and recheck.'
  }
  return $draft
}
$serviceText = @($j.result.content | Where-Object type -eq 'text' | ForEach-Object text) -join "`n"
$draftPath = Join-Path ([IO.Path]::GetTempPath()) ('ontology-answer-' + [guid]::NewGuid().ToString('N') + '.md')
$fence = '```'
$draft = "isError=$($j.result.isError)`n`n$fence" + "json`n$serviceText`n$fence"
try {
  [IO.File]::WriteAllText($draftPath, $draft, [Text.UTF8Encoding]::new($false))
  Get-VerifiedOntologyReply -serviceText $serviceText -draftPath $draftPath
} finally {
  if (Test-Path -LiteralPath $draftPath) { Remove-Item -LiteralPath $draftPath -ErrorAction Stop }
}

Use that checked draft unchanged for the final chat response. Do not retype its JSON or identifiers after checking. Recheck any edited draft; if it fails, recover the text from the saved response, never by issuing another tools/call. In a new PowerShell invocation, redefine the helpers and reparse the saved response first. Do not silently switch to file-only delivery when the user requested the content in chat.

0. Resolve the IDs

Choose the path that preserves the user's scope:

• Workspace supplied: resolve that workspace, then list its Ontology items with GET {host}/v1/workspaces/{WS}/items?type=Ontology and exact-filter the name or ID locally. Do not broaden to tenant-wide Catalog Search.

• No workspace supplied: use Catalog Search. Every hit carries hierarchy.workspace.id beside id, so one result provides both halves of the MCP URL. This path requires the Catalog.Read.All delegated scope.

Inside a supplied workspace — exact-filter the item locally:

az rest --method get \
  --url "$APIHOST/v1/workspaces/$WS/items?type=Ontology" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "x-ms-fabric-skill=ontology-cli" \
  --query "value[?displayName=='ClinicNetwork'].{name:displayName,id:id}" -o table

With no workspace supplied, by name — the user said "the ClinicNetwork ontology":

cat > /tmp/find.json << 'EOF'
{"search": "ClinicNetwork", "filter": "Type eq 'Ontology'", "pageSize": 30}
EOF
az rest --method post --url "$APIHOST/v1/catalog/search" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "x-ms-fabric-skill=ontology-cli" \
  --body @/tmp/find.json \
  --query "value[].{name:displayName, id:id, ws:hierarchy.workspace.id}" -o table

By bare GUID — drop search entirely and match id yourself. Do not pass the GUID as search; verified on a live tenant, that returns the derived <name>_lh_<guid> and <name>_graph_<guid> artefacts plus unrelated noise, and not the ontology:

cat > /tmp/all.json << 'EOF'
{"filter": "Type eq 'Ontology'", "pageSize": 100}
EOF
az rest --method post --url "$APIHOST/v1/catalog/search" \
  --resource "https://api.fabric.microsoft.com" \
  --headers "x-ms-fabric-skill=ontology-cli" \
  --body @/tmp/all.json \
  --query "value[?id=='$ONT'].hierarchy.workspace.id | [0]" -o tsv

If the result is empty and continuationToken is non-empty, repeat with that token before concluding the ontology is absent — but cap the walk at three pages and then ask for the workspace instead.

Verified search behaviour

search matches case-insensitive word prefixes across name and description — it is neither an exact match nor typo-tolerant. The behaviour below was measured on a live tenant; the names are illustrative, standing in for two ontologies called ClinicNetwork and ClinicOperations:

So more than one hit is the normal case. Show displayName, workspace and id, and let the user choose; picking the first silently will eventually answer from the wrong ontology.

1. Discover the surface

cat > /tmp/payload.json <<'JSON'
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
JSON

Add --query "result.tools[].name" to the template to see just the names:

["search_ontology", "ask_ontology", "list_ontology_rules", "list_ontology_entities"]

ask_ontology is present, so this is a supported new-experience (V2) Ontology and the rest of the session may use it. If ask_ontology is absent, stop before tools/call.

2. Ask a business question

User: "Using the ClinicOperations ontology, how many clinics are there?"

cat > /tmp/payload.json <<'JSON'
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"ask_ontology","arguments":{"request":"How many clinics are there?"}}}
JSON

Response:

{ "jsonrpc": "2.0", "id": 2,
  "result": {
    "_meta": { "conversationId": "8b319d38-6472-4bd8-8351-80959687c0d3" },
    "content": [ { "type": "text", "text": "There are **5 clinics**." } ],
    "isError": false } }

Answer to the user: There are 5 clinics in the ClinicOperations ontology.

Note what is not here: no definition fetch, no base64 decode, no hand-written SQL, no delegation to a sibling skill. One discovery call and one question.

3. Ask for runnable code

queryLanguage accepts KQL, SQL, DAX, Python, the ontology DSL, or Ontology/Eventhouse-runnable KQL that joins KQL, SQL and DAX sources. Name it and the execution target inside request:

{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"ask_ontology","arguments":{"request":
   "Generate runnable code that returns the number of appointments per practitioner. queryLanguage: KQL. Execution target: Eventhouse."}}}

The returned text is KQL grounded in the ontology's real bindings — a concrete connection string and real table and column names, not placeholders. Present it to the user; hand execution to eventhouse-cli only if they ask for it. This call is slower than a plain question.

4. An unsupported V1 ontology

When tools/list omits ask_ontology — for example, it returns only ["list_ontology_entity_types", "search_ontology"] — stop before tools/call. Do not use search_ontology as a fallback.

Tell the user:

Natural-language queries in ontology-cli support only new-experience (V2) Ontologies. This Ontology uses the earlier V1 experience, so I did not run the query. Upgrade or recreate it in the new Ontology experience, then try again.

5. Inspect the schema

Only when the user actually asked a schema question. Filter whenever you can — the unfiltered form returned roughly 44,000 characters for a 13-entity ontology.

{"jsonrpc":"2.0","id":5,"method":"tools/call",
 "params":{"name":"list_ontology_entities","arguments":{"entityName":"Appointment"}}}

result.content[0].text parses to:

{ "values": [ { "name": "Appointment", "lineageTag": "...", "keyProperties": [ ... ],
                "backingTable": { ... }, "additionalBackingTables": [ ... ],
                "properties": [ ... ], "synonyms": [ ... ], "annotations": [ ... ],
                "resourceLinks": [ ... ] } ] }

6. A follow-up question

Every tools/call is independent -- the server keeps no conversation, so a follow-up that relies on the previous turn will be answered without that context. Fold the carried-over facts into the new request:

Keep result._meta.conversationId in your notes; it identifies the call in a support ticket even though it cannot be replayed.

Version gating, as observed

tools/list against two ontologies in the same workspace returns different sets:

V2 ontology -> search_ontology, ask_ontology, list_ontology_rules, list_ontology_entities
V1 ontology -> list_ontology_entity_types, search_ontology

Only the first surface is supported for natural-language consumption. The V1 list is shown solely so the client can recognize and reject it; do not call search_ontology.

Calling a gated tool anyway returns HTTP 200 carrying:

{ "result": { "content": [{ "type": "text",
  "text": "Tool 'ask_ontology' is not supported for this ontology artifact version." }],
  "isError": true } }

Phrasing the request

request is the only input, so the whole question has to live in that one string.

The last row matters more than it looks: site names repeat, so a request that groups by name merges distinct sites into one row. Ask for the identifier whenever the question says "for each".

Troubleshooting