# Ontology MCP tools

> Arguments, results, limits, and errors for each read-only Ontology MCP tool

The Ontology MCP provides nine read-only tools. Each tool returns a JSON
object. Tools never change Datastruct data.

## Tools

| Tool | Required arguments | Optional arguments |
| --- | --- | --- |
| [`search_ontology`](#search_ontology) | `query` | None |
| [`browse_business_segments`](#browse_business_segments) | None | `parent` |
| [`get_business_segment`](#get_business_segment) | `segment_id` | None |
| [`find_sources_for_business_function`](#find_sources_for_business_function) | `business_function_id` | `concern` |
| [`get_concern`](#get_concern) | `concern` | None |
| [`get_subject`](#get_subject) | `subject` | None |
| [`get_data_provider`](#get_data_provider) | `provider` | None |
| [`get_data_source`](#get_data_source) | `source` | None |
| [`get_data_feature`](#get_data_feature) | `feature` | None |

All arguments are strings. Pass an `id` or slug returned by an earlier tool
result.

## Shared conventions

- Every item includes a `url` to its Datastruct Console page.
- Descriptions are shortened to 300 characters.
- `search_ontology` returns up to 10 items per result type, with a `total`
  count of all matches.
- Every other list returns up to 50 items. A list named `<name>` is followed
  by `<name>_truncated`, which is `true` when more items exist.
- `importance` is an integer from `1` to `4`. `fit` gives its label: `Low`,
  `Medium`, `High`, or `Very high`.
- Inactive business segments, data providers, data sources, and data features
  are omitted.

## Feature availability

Each tool follows the Ontology page that shows the same information in
Console. A tool returns the unavailable error when its page is unavailable to
your organization.

| Tool | Console page |
| --- | --- |
| `search_ontology` | Each result type follows its own page |
| `browse_business_segments` | Business Segments |
| `get_business_segment` | Business Segments |
| `find_sources_for_business_function` | Graph |
| `get_concern` | Concerns |
| `get_subject` | Subjects |
| `get_data_provider` | Providers |
| `get_data_source` | Sources |
| `get_data_feature` | Data Features |

`search_ontology` omits result types whose page is unavailable.

## `search_ontology`

Searches names and descriptions across the Ontology by keyword. Every word in
`query` must match the start of a word. The query must contain at least three
letters or numbers.

| Argument | Required | Description |
| --- | --- | --- |
| `query` | Yes | Search keywords |

```json
{
  "query": "flood",
  "results": {
    "business_segments": { "total": 1, "items": [] },
    "subjects": { "total": 0, "items": [] },
    "concerns": { "total": 2, "items": [] },
    "providers": { "total": 1, "items": [] },
    "sources": { "total": 3, "items": [] },
    "features": { "total": 4, "items": [] }
  }
}
```

Items are omitted from this example. Each item has `id`, `name`,
`description`, and `url`. Business segment and concern items also have
`kind`. Source items also have `provider`.

## `browse_business_segments`

Lists one tier of the business segment hierarchy: industry, line of business,
function group, then business function.

| Argument | Required | Description |
| --- | --- | --- |
| `parent` | No | Segment `id` whose children to list; omit for industries |

Returns `parent`, `items`, and `items_truncated`. `parent` is `null` when the
argument is omitted. Each item has `id`, `name`, `kind`, `description`, `url`,
and `child_count`. For a business function, `child_count` is its number of
concerns.

## `get_business_segment`

Returns one business segment with its position in the hierarchy.

| Argument | Required | Description |
| --- | --- | --- |
| `segment_id` | Yes | Business segment `id` |

| Field | Description |
| --- | --- |
| `id`, `name`, `kind`, `description`, `url` | The segment |
| `ancestors` | Parent segments, from the industry down |
| `children`, `children_truncated` | Active child segments |
| `decision` | Business functions only: `role`, `moment`, and `options` |
| `concerns`, `concerns_truncated` | Business functions only: concerns asked |

Each concern has `id`, `name`, `importance`, `why_this_role_asks`, and `url`,
most important first.

## `find_sources_for_business_function`

Follows a business function to its concerns, their sub-concerns, and the data
sources that cover them.

| Argument | Required | Description |
| --- | --- | --- |
| `business_function_id` | Yes | Business function `id` |
| `concern` | No | Concern `id` or slug that limits the result |

| Field | Description |
| --- | --- |
| `business_function` | The business function |
| `paths`, `paths_truncated` | Concern, sub-concern, and source paths |

Each path has `concern`, `sub_concern`, `sources`, and `sources_truncated`.
`sub_concern` includes its `question`. Each source has `id`, `name`,
`provider`, `importance`, `fit`, `capability_claim`, and `url`, best fit
first. Sub-concerns without an available source are omitted.

A segment that is not a business function returns an error.

## `get_concern`

Returns a concern or a sub-concern.

| Argument | Required | Description |
| --- | --- | --- |
| `concern` | Yes | Concern or sub-concern `id` or slug |

Both kinds return `id`, `name`, `url`, `kind`, `description`, `question`,
`aliases`, and `subject`.

| Kind | Additional fields |
| --- | --- |
| Concern | `sub_concerns`, `business_functions`, and their `_truncated` flags |
| Sub-concern | `parent_concerns`, `sources`, and their `_truncated` flags |

Sub-concern sources use the source shape from
[`find_sources_for_business_function`](#find_sources_for_business_function).

## `get_subject`

Returns a subject, its related subjects, and the sub-concerns about it.

| Argument | Required | Description |
| --- | --- | --- |
| `subject` | Yes | Subject `id` or slug |

| Field | Description |
| --- | --- |
| `id`, `name`, `url`, `description` | The subject |
| `parent`, `contained_by` | Related subjects, or `null` |
| `subtypes`, `subtypes_truncated` | Direct subtypes |
| `sub_concerns`, `sub_concerns_truncated` | Sub-concerns and their sources |

Sub-concerns include those about the subject and its direct subtypes.

## `get_data_provider`

Returns a data provider and the data sources it offers.

| Argument | Required | Description |
| --- | --- | --- |
| `provider` | Yes | Data provider `id` or slug |

| Field | Description |
| --- | --- |
| `id`, `name`, `url`, `description`, `sector` | The provider |
| `website_url`, `founded_year` | Provider facts, or `null` |
| `trust_url`, `privacy_policy_url` | Trust and privacy links, or `null` |
| `dpa_available`, `has_gdpr` | Data processing and GDPR indicators |
| `sources`, `sources_truncated` | Sources with `access_cost` |

## `get_data_source`

Returns a data source, the data features it outputs, and the sub-concerns it
covers.

| Argument | Required | Description |
| --- | --- | --- |
| `source` | Yes | Data source `id` or `provider_slug/source_slug` |

| Field | Description |
| --- | --- |
| `id`, `name`, `url`, `description`, `provider` | The source |
| `access_cost`, `coverage_scope`, `coverage_summary` | Access and coverage |
| `terms_summary`, `license` | Terms and license identifier |
| `delivery` | Booleans: `api`, `batch_enrich`, and `full_file` |
| `developer_portal_url` | Developer portal, or `null` |
| `features`, `features_truncated` | Data features and their `evidence` |
| `covers`, `covers_truncated` | Sub-concerns with `importance` and `fit` |

## `get_data_feature`

Returns a data feature and the data sources that provide it.

| Argument | Required | Description |
| --- | --- | --- |
| `feature` | Yes | Data feature `id` or slug |

Returns `id`, `name`, `description`, `url`, `sources`, and
`sources_truncated`. Each source has `id`, `name`, `provider`, `evidence`,
and `url`.

## Tool errors

A tool error is returned as a successful MCP result with one `error` field.

```json
{
  "error": "Concern not found. Use an id or slug from another tool result."
}
```

| Condition | `error` message |
| --- | --- |
| Unknown or inactive item | `<Item> not found. Use an id or slug from another tool result.` |
| Query too short | `Use at least 3 letters or numbers to search the Ontology.` |
| Page unavailable | `This part of the Ontology is not available to your organization.` |
| Not a business function | Names the segment kind and suggests `browse_business_segments` |

Authorization failures return HTTP errors before any tool runs. See
[Ontology MCP errors](/docs/api/ontology-mcp/overview/#errors).

## Related explanation

- [AI assistant access to the Ontology](/docs/topics/ontology-mcp/) explains
  how the Ontology graph and personal credentials fit together.