Generated banner for Nvidia Ontology Query
Generated logo for Nvidia Ontology Query

Nvidia Ontology Query

NVIDIAOfficialCreated by NVIDIA

  • Skill
  • Tool integration
  • Data and AI
  • Apache-2.0
  • Medium risk

From the author

Query Auto Ontology and validate generated SQL, rows, and answers. Use for MCP or REST access, readiness, authentication, conversations, and grounded questions.
— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured procedure for agents to interact with the Auto Ontology system. It emphasizes a rigorous validation process for all generated answers, ensuring that SQL, returned rows, and prose are checked against material constraints before being presented. The skill supports both MCP for direct reads and a REST gateway for authenticated access, while strictly separating query execution from data management tasks.

What it does

  • Verifies system readiness and database connectivity before query execution.
  • Searches semantic terms to confirm answerability within the ontology.
  • Executes text-to-SQL queries via MCP or authenticated REST endpoints.
  • Validates generated SQL, row data, and prose against material constraints.
  • Handles conversation threads and state management for multi-turn interactions.
  • Provides fallback mechanisms for authentication and error handling.

When to use it

  • When you need to retrieve grounded, data-backed answers from an Auto Ontology deployment.
  • When performing diagnostic or descriptive analysis that requires SQL validation.
  • When integrating an agent with an Auto Ontology instance via MCP or REST.
  • When you need to ensure that query results are accurate and meet specific business logic requirements.

Advantages

  • Ensures high-integrity answers through a mandatory validation workflow.
  • Provides a consistent interface for both MCP and REST-based clients.
  • Reduces errors by enforcing checks on SQL, grain, and data lineage.
  • Supports secure, authenticated access to ontology data.

Usage examples

“How many orders were shipped last week?”
The agent checks readiness, searches for relevant terms, executes the query, validates the SQL and rows, and returns a verified count.
“What is the total revenue for the current quarter?”
The agent performs a grounded query, verifies the measure grain and time scope, and provides a validated answer based on the returned rows.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/nvidia-ontology-query/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip nvidia-ontology-query.zip -d .agents/skills

Documentation by NVIDIA

<!-- SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0 -->

Auto Ontology grounded queries

Purpose

Query the current Auto Ontology implementation from an agent without prescribing a harness, SDK, or LangGraph template. Typed workflow artifacts, statuses, gates, and handoffs are in runtime-contract.yaml.

Prerequisites

Use a running Auto Ontology deployment and an authenticated MCP or REST client. If Auto Ontology is not running, use nvidia-ontology-setup first.

Limitations

This skill reads and validates answers. It does not expose FastAPI directly, write semantic definitions, publish governed results, or provide a raw-schema browser. Hand mutations and publication to nvidia-ontology-management.

Instructions

  1. Call readiness before asking a question.

  2. Discover terms and confirm answerability through the semantic layer.

  3. Ask through MCP, or use the authenticated Next.js REST gateway as fallback.

  4. Validate material intent, SQL, rows, truncation, and prose before presenting a claim-bearing answer.

Prefer MCP for reads

When the harness speaks MCP, use it. The handshake tool list is the live source of truth (mcp/auto_ontology_mcp/tools.py). Do not copy a tool table into the session; if the handshake and this skill disagree, trust the handshake.

Sequence (the server also advertises this so models do not jump straight to ask_question):

  1. check_readiness — compiled semantic layer and a live DB connection.

  2. search_terms — what the nouns mean here.

  3. check_answerable — cheap coverage check.

  4. ask_question — full text-to-SQL; tens of seconds; answer + SQL + rows (capped at 100 rows, with row_count / truncated).

  5. For a claim-bearing answer, validate material intent, generated SQL, returned rows, truncation, and prose using query-validation.md.

Everything on MCP reads. There is no MCP tool for raw databases, schemas, or columns on purpose. describe_table is the legitimate table view: terms and SQL attributes the table participates in.

Connect: AUTO_ONTOLOGY_API_URL is the web app. Run auto-ontology-mcp, point the client at …/mcp, user signs in. No token on the MCP server. Details: repository mcp/README.md and docs/mcp.md.

REST fallback and write handoff

When MCP is unavailable, public clients call the authenticated Next.js gateway, not FastAPI :3001. FastAPI trusts x-auto-ontology-user-id and must not be exposed. A direct FastAPI request without conversation_id is stateless; with conversation_id it requires that internal header.

Auth (any of these; resolved in one place):

  • Browser session cookie

  • API token: x-api-key: $AUTO_ONTOLOGY_API_TOKEN (Authorization: Bearer works for auto_ontology_… tokens too). Token acts as its owner.

  • OAuth bearer issued by Auto Ontology (MCP sign-in)

  • SSO id token (Authorization: Bearer <jwt>), e.g. AI-Q — see stack.md

Shapes: docs/openapi/auto-ontology-api.json. Do not scrape all ~87 operations. A write request hands off to nvidia-ontology-management; this skill does not turn a read-only question into a mutation.

Chat

POST /api/chat/completions — SSE step / result / error / charts, then [DONE]. Permission chat:use; a request with conversation_id also needs conversation:write, or it gets 403.

  • Omit conversation_id for a one-shot (no history, no chart step).

  • Supply a client-generated UUID to create or continue a thread (needs chat:use and conversation:write).

  • Wait for [DONE] before the next turn; overlapping requests return 409 Conversation in progress.

  • A 404 on a conversation id means it belongs to another user.

Python (from the Auto Ontology README; no extra SDK):

import os
import requests

session = requests.Session()
session.headers["x-api-key"] = os.environ["AUTO_ONTOLOGY_API_TOKEN"]

terms = session.get("https://ontology.example.com/api/terms").json()

answer = session.post(
    "https://ontology.example.com/api/chat/completions",
    json={"question": "How many orders shipped last week?"},
)
# response is SSE, not a single JSON object

Open an API-created thread in the UI at /chat?focus=<conversation_id> when it belongs to the signed-in user.

Discovery (semantic layer, not a catalog browser)

MCP first. REST fallback:

  • GET /api/terms (query, skip, limit)

  • GET /api/terms/{term_id}

  • GET /api/exploration/tables/{table_id}/details

  • GET /api/exploration/graph

Writes and compile reset: nvidia-ontology-management.

Validate claim-bearing answers

Do not treat successful execution as sufficient evidence. Before presenting a decision-facing result, apply query-validation.md to check population, measure, unit, grain, joins, lineage, status, validity, rows, truncation, and answer prose. If a material constraint cannot be verified, return the gap rather than a stronger claim.

Empty or failed answers

ask_question / chat returned nothing useful → check_readiness (or GET /api/semantic-compilation/status) before rewriting the question. A named database is not proof SQL can execute. See nvidia-ontology-setup troubleshooting.

Examples

  • For a grounded count, run check_readiness, search_terms, check_answerable, and then ask_question.

  • If a response is truncated or violates measure grain, refuse the complete claim and follow query-validation.md.

Troubleshooting

For empty or failed answers, check readiness and compilation status before rephrasing. For REST errors, verify the public web origin, authentication, and conversation ownership before retrying.

See also

  • stack.md — AI-Q, Nemotron, cuOpt (what exists vs what partners wire)

  • query-validation.md — material intent, SQL, rows, and answer checks

  • nvidia-ontology-management — model, modify, and publish through the layer

  • nvidia-ontology-setup — bring-up and MCP OAuth discovery

Files

evals/evals.json

{
  "skill_name": "nvidia-ontology-query",
  "evals": [
    {
      "id": "query-eval-001-mcp-first",
      "prompt": "How should my coding agent ask Auto Ontology how many open orders we have?",
      "expected_output": "If MCP is connected, use the handshake tools in order: check_readiness, search_terms, check_answerable, ask_question. Do not jump straight to ask_question. Do not copy a frozen tool table if the handshake list differs.",
      "assertions": [
        "Prefers MCP when available",
        "Sequences check_readiness before ask_question",
        "Does not dump the full OpenAPI surface"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-002-no-fastapi-public",
      "prompt": "I'll POST questions to http://localhost:3001/api/chat/completions with a conversation_id from our partner app.",
      "expected_output": "Do not expose or call FastAPI :3001 from a partner app. Public clients use the Next.js gateway on the web origin (:3000). FastAPI trusts x-auto-ontology-user-id and does not independently verify it. conversation_id on a direct FastAPI call requires that internal header.",
      "assertions": [
        "Directs the caller to the Next.js gateway, not FastAPI :3001",
        "Explains that FastAPI is a trusted internal boundary",
        "Does not endorse public :3001 access"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-003-conversation-409",
      "prompt": "As an authenticated user with chat:use and conversation:write, I send two overlapping POSTs to /api/chat/completions with the same conversation_id. What happens?",
      "expected_output": "The second request returns 409 Conversation in progress. Wait for [DONE] on the SSE stream before sending the next turn. conversation_id is scoped to the authenticated Auto Ontology user.",
      "assertions": [
        "Names 409 Conversation in progress",
        "Requires waiting for [DONE] before the next turn",
        "Does not recommend parallel turns on one conversation_id"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-004-sso-vs-api-token",
      "prompt": "AI-Q already has the user's NVIDIA SSO JWT. Should it also mint an Auto Ontology API token to call chat?",
      "expected_output": "No extra Auto Ontology token is required. Auto Ontology accepts the SSO id token as Authorization: Bearer, verifies issuer/signature/expiry, and does not check audience (aud is AI-Q's client id). The token must map to an existing Auto Ontology user (email, then SSO subject). An Auto Ontology API token is for scripts that cannot present SSO.",
      "assertions": [
        "Uses the SSO bearer as the AI-Q credential",
        "Does not require minting an Auto Ontology API token for AI-Q",
        "Notes audience is not checked and an Auto Ontology user must already exist"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-005-no-raw-schema-tools",
      "prompt": "Which MCP tool lists every schema and column in the warehouse so I can write SQL myself?",
      "expected_output": "There is none, on purpose. Consumers reach data through the semantic layer. describe_table is the table view (terms and SQL attributes). Use search_terms / ask_question rather than information_schema.",
      "assertions": [
        "States there is no MCP catalog-browser for raw schemas",
        "Points at describe_table / search_terms / ask_question",
        "Does not recommend listing information_schema via Auto Ontology MCP"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-006-cuopt-not-in-repo",
      "prompt": "Wire Auto Ontology to cuOpt so chat answers become a vehicle routing job.",
      "expected_output": "This repository has no cuOpt bridge. Auto Ontology returns answers, SQL, and rows; a partner agent may feed numbers into cuOpt using cuopt-* skills. Do not claim Auto Ontology solves routing or LPs.",
      "assertions": [
        "States there is no in-repo cuOpt integration",
        "Allows a partner-wired hop from Auto Ontology rows to cuOpt",
        "Does not invent an Auto Ontology routing API"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-007-readiness-before-retry",
      "prompt": "ask_question came back with an empty answer, no SQL, and no error. I'll rephrase the question.",
      "expected_output": "Call check_readiness first. Empty answers are often a missing connection or uncompiled layer, not a phrasing problem. Rephrase only after readiness is clean, then search_terms.",
      "assertions": [
        "Calls check_readiness (or compilation status) before rephrasing",
        "Does not immediately retry a rephrased ask_question as the first step"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-008-quantity-not-ratio",
      "prompt": "The question asks for unmet weekly demand in units. Generated SQL returns (1 - service_level) under the alias unmet_weekly_demand. Use that answer.",
      "expected_output": "Reject the result as a material measure and unit substitution. One minus service level is a dimensionless share, not a quantity in units. Resolve the approved unmet-demand measure and source expression, regenerate or report the gap, and do not repair the error by relabeling the ratio.",
      "assertions": [
        "Rejects the ratio-for-quantity substitution",
        "Checks the approved measure expression and unit",
        "Does not present the aliased ratio as demand units"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-009-run-metric-fanout",
      "prompt": "Use the nvidia-ontology-query skill to audit this query result before summarizing it. A query joins one row per run to 19 selected-job rows and reports SUM(risk_mwh). The source value is 7738.2 MWh and the result is 147025.8 MWh.",
      "expected_output": "Do not summarize the multiplied value. The one-to-many join fanned out an already run-grain metric by 19. Require direct run-grain projection or isolation of the unique run row and preserve 7738.2 MWh.",
      "assertions": [
        "Loads nvidia-ontology-query before auditing the result",
        "Identifies one-to-many metric fanout",
        "Rejects 147025.8 MWh as the run total",
        "Requires a run-grain query before answering"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-010-scenario-lineage",
      "prompt": "I asked for children of primary_material_shortage. The rows also include selective_prebuild_intervention whose parent is base. SQL executed successfully.",
      "expected_output": "Execution success is insufficient. Reject the extra base-child row because the SQL omitted or substituted the requested parent/scenario predicate. Require explicit parent lineage, scenario, status, validity, and supersession filters before answering.",
      "assertions": [
        "Rejects the wrong-parent population",
        "Checks explicit lineage and validity predicates",
        "Does not trim the extra row only in prose"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-011-prose-versus-rows",
      "prompt": "The SQL rows contain the requested values, but the answer only says that the query would compare the two runs. Is that a complete answer?",
      "expected_output": "No. Validate the rows, then state the returned findings with values, units, scope, and status. Keep SQL/result correctness separate from answer-prose correctness; a query description is not a decision-ready answer.",
      "assertions": [
        "Treats rows and answer prose as separate checks",
        "Requires the prose to state actual findings",
        "Preserves values, units, scope, and status"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-012-source-role",
      "prompt": "The question requests forecast_runs.planning_artifact_sha256, but SQL selected a snapshot artifact-index hash with the same shape. Return it as the planning artifact.",
      "expected_output": "Reject the substitution. Similar-looking hashes have different source roles. Require the requested table and column or report that the planning artifact is unavailable; do not relabel the snapshot index hash.",
      "assertions": [
        "Checks the requested source role and column",
        "Rejects the snapshot hash substitution",
        "Does not repair provenance by changing the label"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    },
    {
      "id": "query-eval-013-truncated-result",
      "prompt": "ask_question returned 100 rows with row_count 340 and truncated true. List all 340 customers in rank order from this response.",
      "expected_output": "The response cannot prove the complete list or ranking because 240 rows were withheld. Do not extrapolate or label the first 100 as complete. Narrow the request or obtain a bounded aggregate or complete authorized result before making the claim.",
      "assertions": [
        "Treats truncated true as incomplete evidence",
        "Does not claim a complete 340-row ranking",
        "Narrows the request or asks for a complete supported result"
      ],
      "expected_skill": "nvidia-ontology-query",
      "expected_script": null
    }
  ]
}

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs Python

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/nvidia-ontology-query · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download nvidia-ontology-query.zip