At a glance
Three distinctions matter for a security review, and they are narrower than the table’s length suggests:
- Only two tools reach a system outside Human Intelligence.
search_docsqueries our public documentation search service, andnotify_slackdelivers through your connected Slack workspace. Every other tool is confined to your Human Intelligence tenant. - Only two tools write anything.
apply_access_changechanges your access configuration;notify_slacksends a message. Nothing in the tool surface can modify your people data. set_session_contextwrites only to the session. It changes what the current session can see for its remaining lifetime. It alters no configuration and leaves no trace on the next session.
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. In versions 0.4.0 to 0.10.0, 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.
Version 0.11.0 removes this tool. Policies are checked inside every data
query instead, against the query and the
intent the client sends with it.
See Migrating to 0.11.0.This is a governance gate, not a data tool. It returns a policy decision, not
people data.
Discovery
search_people_datasets
Semantic search over your organization’s catalog of datasets and their queryable fields — 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. Fields 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.
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.
intent: a plain statement of what the user is trying to find out and why. Your organization’s narrative policies are checked against the query and the intent before any data is returned, and the intent is required when those policies apply to the user.
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.
Access administration
These eight tools let a data admin read — and change — your organization’s own access configuration from an AI client: data categories, the category assignments on dataset fields, row-scope boundaries, allow and deny rules, and roles. They are configuration tools, not data tools. Every one of them describes or changes who can see what; none of them returns people data.search_access_boundary_org_units returns org-chart node identifiers for scoping rules, and get_dataset_access_governance returns category coverage — neither is a route to the underlying records.
Which of these tools a session gets follows your own permissions: the four
read tools require a Security & Access Control view permission,
preview_access_change and apply_access_change require manage
permissions, and the session-context pair requires permission to manage
roles. Tools you cannot use are absent from the tool list rather than failing
when called.get_access_config
Returns your current access configuration: the data categories in use and how many fields carry each, the row-scope boundaries, the allow and deny rules, the roles, the effective role-to-category map, and the org hierarchies available to anchor a boundary against.
It reports your organization’s own categories separately from the standard categories Human Intelligence suggests. Only your own — however each was created — can be assigned to a field or granted by a rule.
This is the starting point for any change. A plan built on a guessed category name or boundary identifier either fails validation or, worse, configures something adjacent to what was intended — so the contract steers a client to read the live state first.
search_access_boundary_org_units
Looks up nodes in one of your org hierarchies by name, returning the identifiers used to anchor a row-level boundary — “this role sees the Engineering subtree,” for example.
get_dataset_access_governance
Lists a dataset’s dimensions and measures alongside the access categories currently assigned to each, which is the inventory you work from when deciding what a role should reach.
check_role_access
Reports what a role — or the union of roles a named user actually holds — is effectively granted: the categories it reaches, the resolved row-level grants for that user, any grants that could not be resolved, and how many categories it mixes per dataset against the mixing cap.
Unresolvable grants are worth understanding, because they fail closed: a boundary that cannot be resolved for a user denies rows rather than releasing them. A role that suddenly returns nothing is often this, not a broken query.
This tool verifies the grants you wrote, not the whole surface they expose —
fields with no categories assigned are invisible to it. Before declaring a
restriction safe, query as the role;
set_session_context is how you do that.preview_access_change
Validates a complete planned change against your live configuration and reports what would happen. It writes nothing.
The response includes a role impact summary: the blast radius across every role in the organization — reach gained and lost per dataset, and any role newly gaining access to identifiers.
Every category a plan names must be one your organization already has, or one the plan itself creates. Creating a category is a single operation that works from either starting point: you can name one of the standard categories Human Intelligence suggests, which creates yours from that suggestion and carries its description over, or you can name a category of your own invention. Both are equally valid, and most organizations use a mix.
A suggestion governs nothing on its own — the catalog is the same list for every organization, and a category only exists for you once you have created it. A plan naming a category you do not have is rejected, and the error says whether a matching suggestion is available to create it from. Creating a category never applies field assignments of its own and never changes a category already on a field, so your own classification decisions stand.
A successful preview returns a single-use plan token. The plan itself is held on our side, keyed by that token. A plan that fails validation returns no token.
apply_access_change
Redeems a plan token and executes the plan. This is the step that changes live access enforcement for real users.
Because the plan is held server-side and addressed only by the token that a preview returned, applying a change that was never previewed is not a reachable state. Each operation is additionally re-checked against the specific permission it requires, at preview time and again at apply time.
Categories are re-checked too, against the configuration as it stands at apply time rather than when the plan was previewed. If one the plan names has been deleted in between, the whole plan is refused and nothing is applied — preview it again to see the current state.
set_session_context
Re-points the current session so that subsequent tool calls resolve against something other than the caller’s own access, until it is cleared or expires. It is the answer to “what will this role actually see?”
Each dial is independent:
roleSlugsadopts one or more data roles, so you see what their holders see — including what they are denied.emailadditionally adopts a member’s identity, so viewer-relative rules such as “own subtree” or “my reports” resolve as that person.planTokenresolves against a previewed-but-unapplied plan instead of the live configuration, which is how a drafted change is inspected before anything is committed.
whoami reports the context in effect and is the way to confirm one took hold.
clear_session_context
Drops any context set by set_session_context, returning the session to the operator’s own access from the next call. Safe to call when none is set.
Documentation
search_docs
Searches our public product documentation and returns matching excerpts with their page URLs, so a client can answer “how does Human Intelligence do X?” from our documentation rather than from guesswork.
Two notes for a security review:
- It is the only read tool that leaves our infrastructure. The query goes to the public documentation search service, which indexes exactly the pages any anonymous visitor can read. There is no per-role filtering to apply, because there is nothing non-public in the index.
- Nothing from your tenant is attached to the query. The tool sends the search text and nothing else — no organization identifier, no session context. The tool contract instructs clients to phrase queries as generic product questions and to keep employee names and values from your data out of them, and every query is logged on our side so that egress is auditable.
App building
get_artifact_sdk
Returns the Human Intelligence app SDK: versioned packages of the files needed to build your own dashboard or app on your Human Intelligence data — a sign-in module, a governed data-access layer, an app scaffold, the design system with neutral default styling, and written guides. A third, org-resolved brand package carries your organization’s own brand colors and platform guide, when one is published for you. Called with just a package name it returns that package’s manifest (version, content hash, file list); called with a file name it returns the file’s content, in chunks for large files.
Three notes for a security review:
- It serves our files, not your data. Every response is a fixed, versioned copy of client-side code and styles. The tool runs no queries against your organization’s data; its one organization-dependent behavior is using your organization’s identity to select which
brandpackage, if any, you receive. - No organization ever receives another organization’s content. The two core packages are identical for everyone and pass an automated build gate that rejects any customer-identifying content; a
brandpackage is only ever served to the organization it belongs to, and organizations without one get a clear not-found rather than a fallback. - It is registered only for enrolled organizations. The tool appears in
tools/listonly for organizations enrolled in the app SDK program; everyone else never sees 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.
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.
Tool availability
The exact set of tools a client sees depends on two things: the contract version it connects to, and your organization’s configuration.search_docs requires contract version 0.8.0 or later; the access-administration tools and get_artifact_sdk require 0.9.0 or later; check_narrative_policies is in versions 0.4.0 to 0.10.0. Versions has the full table, and each version’s reference lists its parameters. Newly connected integrations can take a few minutes to be reflected in the tool list.
Conditional registration is the mechanism we use to keep a capability off entirely rather than merely refusing it at call time. notify_slack appears only once Slack is connected, and the access-administration tools only for a user who holds the matching Security & Access Control permissions. A tool a session cannot use is not in its tools/list response at all, and the server instructions that describe it are withheld alongside it.
A client should always read the live tools/list response rather than assuming a fixed set.