Skip to main content

Ontology

The ontology tool lets you ask natural-language questions about the Carbon Arc knowledge graph. Explore how companies, brands, products, datasets, insights, events, topics, locations, and other entities connect across the platform.

Just ask a question in plain English. The tool translates it into a validated, read-only graph query and returns the results as a markdown table.

  • Tool: ontology
  • Cost: Free
  • Access: Available on both the public (/mcp/) and research (/mcp/research/) MCP endpoints

When to Use It

Use the Ontology tool anytime you want to understand how things connect across Carbon Arc.

Example questions:

  • What brands does Walmart own?
  • What apps does Nike have?
  • What sector is Walmart in?
  • What subcategories exist under Beverages?
  • What cities are in California?
  • What topics do Walmart and Costco share?
  • What tearsheets cover Walmart?
  • What insights are available for Walmart?
  • How many companies are in the graph?
  • What relationship types are supported?

When to Use Another Tool

The Ontology tool answers relationship questions. It does not return metrics, documentation, or dataset definitions.

Looking for...Use
Metrics, values, or trendstext_to_insight
Dataset documentation or field definitionsdata_library
Product documentationsearch_docs
Finding an entity or insight by namesearch_entities or search_insights

Parameters

ParameterRequiredDescription
questionYesYour natural-language question.
entity_idsNoPin a specific entity if you need to retry with an exact match. Only use IDs returned by Carbon Arc tools.
rerankerNoAdvanced option to override entity resolution. Most users can ignore this.

In most cases, all you need is the question parameter.

Ontology tool answering "what brands map to WMT?" with results grouped by brand type

Example

{
  "question": "What brands does Walmart own?"
}

Retrying With a Specific Entity

If the wrong entity was matched, retrieve the correct entity_id using search_entities or from a previous ontology response, then retry:

{
  "question": "What brands does Walmart own?",
  "entity_ids": [
    {
      "entity_id": 28368,
      "entity_representation": "retailer"
    }
  ]
}

Common entity representations include company, retailer, topic, subject, tearsheet, and insight.

Response

Each response includes three sections:

  • data: Results returned as a markdown table.
  • system_instructions: Guidance for displaying the results.
  • metadata: Additional information including row counts, summaries, returned columns, resolved entities, and suggested follow-up actions.

Troubleshooting

If your results look incorrect or come back empty:

  1. Check entity_resolution_metadata to see which entity your question matched.
  2. If needed, use search_entities to find the correct entity.
  3. Retry using the returned entity_id and entity_representation.

Never guess entity IDs.

How It Works

When you ask a question, the tool:

  1. Matches your request to a validated graph query.
  2. Resolves any entities referenced in your question.
  3. Executes a read-only query against the Carbon Arc knowledge graph.
  4. Returns the results as a markdown table.

The tool is read-only and cannot modify data. It simply helps you explore the relationships that already exist in the Carbon Arc knowledge graph.