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

# Tool reference

> Every tool the Human Intelligence MCP server exposes, what it does, and what it can reach.

This page describes the tools available over the [MCP server](/mcp/overview), written for people evaluating or integrating it rather than for the model consuming it. The descriptions the server actually sends to a client are longer and tuned to steer agent behavior; these are the plain-language equivalents.

Every tool runs as the connected user, and every tool is subject to the same server-side [permission enforcement](/mcp/overview#identity-and-permissions) as the product itself.

## At a glance

| Tool                       | What it does                                                 | Effects   | Reaches outside HI |
| -------------------------- | ------------------------------------------------------------ | --------- | ------------------ |
| `whoami`                   | Reports the session's identity, roles, and permissions       | Read-only | No                 |
| `check_narrative_policies` | Evaluates the user's intent against your governance policies | Read-only | No                 |
| `search_people_datasets`   | Semantic search across your data catalog                     | Read-only | No                 |
| `list_people_datasets`     | Enumerates every dataset available to the org                | Read-only | No                 |
| `describe_people_dataset`  | Returns a dataset's schema                                   | Read-only | No                 |
| `explain_people_dataset`   | Returns metric methodology and governance context            | Read-only | No                 |
| `query_people_dataset`     | Runs a governed analytical query                             | Read-only | No                 |
| `get_query_result_rows`    | Pages through a previous query's cached result               | Read-only | No                 |
| `notify_slack`             | Sends a Slack DM to a colleague                              | **Write** | **Yes**            |

Eight of the nine tools are strictly read-only and cannot reach any system outside Human Intelligence. `notify_slack` is the sole exception, and it is only present for organizations that have connected Slack.

## Identity

### `whoami`

Returns the authenticated user's identity, roles, permissions, and organization for the current session.

This is the tool to reach for when diagnosing an access question. If a harness is returning less data than someone expects, `whoami` establishes which account and which roles the session is actually operating under — which usually resolves the question of whether you're looking at a bug or at access control working correctly.

## Governance

### `check_narrative_policies`

Evaluates a synthesized description of what the user is trying to do against the narrative policies your organization has configured, before any data tool runs.

Narrative policies let a governance team express rules about *how* data may be discussed and analyzed, not just which rows are visible. Where your organization has configured them, the tool contract requires the client to call this first and to carry the resulting token into its data calls, so a policy decision cannot be skipped by a client that simply chooses not to ask.

<Note>
  This is a governance gate, not a data tool. It returns a policy decision, not
  people data.
</Note>

## Discovery

### `search_people_datasets`

Semantic search over your organization's catalog of datasets and their queryable members — metrics, dimensions, time dimensions, and segments.

Takes a natural-language description of what the user is looking for and returns the most relevant catalog entries with their identifiers and short descriptions. This is the normal entry point for an analytical question: it's targeted, and far cheaper in context than enumerating the whole catalog.

Results are scoped to what the connected user is permitted to see. Members they don't have access to are not returned.

### `list_people_datasets`

Enumerates every dataset available to the organization.

Intended for genuine discovery questions — "what data do we have?" — rather than as a first step toward an analytical answer. For anything analytical, `search_people_datasets` is the intended path.

## Schema and methodology

### `describe_people_dataset`

Returns the schema for one or more datasets, split into metrics, dimensions, time dimensions, segments, and related datasets.

Each entry carries a name, title, description, and type where applicable. The related-datasets section describes which other datasets a given one joins to, one hop at a time, which is how a client discovers that a question spanning two entities can be answered in a single query.

### `explain_people_dataset`

Returns methodology and governance context for metrics: how a metric is calculated, what population it applies to, and any organization-specific customization your data team has configured.

This is what makes "why does this number look different than I expected?" answerable. It surfaces your data team's own guidance and the governed default population for a metric, so a client explains a figure using your definitions rather than inferring meaning from column names.

<Tip>
  If your team has written metric definitions in Human Intelligence, this is the
  tool that carries them into every connected AI tool. Definitions you maintain
  in one place show up everywhere.
</Tip>

## Querying

### `query_people_dataset`

Runs an analytical query against your people, HR, and talent data using identifiers taken from `describe_people_dataset`.

This is the tool that returns actual figures, and it's where governance is most visible. Responses carry disclosures alongside the data:

* **Access scope.** When access rules limited which rows the query could see, the response says so, and the contract instructs the client to describe the result as scoped rather than org-wide.
* **Population scope.** When a metric has a governed default population and the query didn't apply it, the response discloses that the figures reflect the full, unscoped population.
* **Data completeness.** Where records are missing an attribute, the response reports how many, so a breakdown can be presented with its gaps stated rather than silently omitted.
* **Resolved date ranges.** Relative ranges resolve to absolute windows, and the response reports the exact window it executed.

Results are capped at a page of rows returned to the model, with the full result cached for paging.

### `get_query_result_rows`

Fetches a page of rows from the cached result of a prior `query_people_dataset` call, addressed by the handle that call returned.

Reads a frozen snapshot, so paging through a large result is both cheap and internally consistent — a client pages a result rather than re-running the query and risking rows shifting underneath it.

## Notifications

### `notify_slack`

Sends a Slack direct message to a person, addressed by email, through your organization's connected Slack workspace.

This is the only tool that writes anything or reaches a system outside Human Intelligence, and it warrants two specific notes for a security review:

* **It is conditionally registered.** The tool is only advertised to clients for organizations that have completed the Slack install. If your organization has not connected Slack, it does not appear in the tool list at all and cannot be called.
* **It cannot message arbitrary destinations.** Delivery is resolved through your connected workspace, so an email that isn't a member of that workspace returns an error rather than sending anywhere.

Its intended use is delivering a report or completion notice when a user explicitly asks to notify a colleague.

<Note>
  If your organization would rather not expose an outbound action to AI clients
  at all, leaving Slack disconnected is sufficient — the tool is never
  registered.
</Note>

## Tool availability

The exact set of tools a client sees depends on two things: the [contract version](/mcp/overview#versioning) it connects to, and your organization's configuration. Newly connected integrations can take a few minutes to be reflected in the tool list.

A client should always read the live `tools/list` response rather than assuming a fixed set.