inspect_data_meaning

inspect_data_meaning answers "what is this data?" for one table or column: the tenant-authored catalog meaning, the governing classification (sensitivity, category, subcategory), whether it counts as PII, and any declared masking facts. It is read-only and advisory, and — unlike the other asset-scoped tools — it is not decision-bearing: it returns published facts, not a governance decision. Clients that present hyphenated tool names can call it as inspect-data-meaning.

When to use

• Before proposing a use of an asset: learn what a column means and how sensitive it is, so the agent can frame the right question to authorize_use or get_decision_context.
• To check whether a column is classified as PII and whether masking (with exempt roles) is declared for it.
• To ground generated SQL, documentation, or analysis in the catalog's own description of a field instead of guessing from its name.

Input

Parameter	Type	Required	Description
ref	object	Yes	Reference to a table or column.
ref.database	string	Yes	Normalized database name, as shown in the catalog.
ref.schema	string	Yes	Normalized schema name.
ref.table	string	Yes	Normalized table name.
ref.column	string	No	Normalized column name. Omit it for a table-level reference.

The schema is strict: unknown keys anywhere in the input are rejected with invalid_parameters.

Output

A successful call returns one flat JSON facts object — there is no state field (see the next section):

Field	Description
ref	The resolved asset scope: database, schema, table, column. column is always present and null for a table-level reference.
meaning	The tenant-authored catalog description or comment for the asset, or null when none is recorded.
data_type	The column's data type (for example text), or null — always null for table-level references.
classification	Classification facts from the governing policy, or null when no governing policy declares one. When present: sensitivity (public, internal, confidential, or restricted), category (a prefix-coded category such as pii.email), and subcategory (or null).
pii	Boolean. Derived from the classification category prefix (pii or phi); false when the asset is unclassified.
masking	Masking facts from the governing policy, or null when no masking is declared. When present: type (a prefix-coded masking type such as full or partial.last4) and exempt_roles (an array of role names).

Answer states

None. inspect_data_meaning is the one asset-scoped tool that is not decision-bearing, so it does not use the typed three-state answer model (answered / review_required / not_enough_published_state). What that means in practice:

• The output has no state discriminator and no reason codes — a resolvable reference always yields the flat facts object above.
• Absence of governance is expressed as explicit null fields (classification: null, masking: null, pii: false), not as a not_enough_published_state answer.
• A reference that does not resolve in the workspace's current catalog is an explicit asset_not_found error, never an empty facts object.

The tool resolves the asset in the current catalog first, then returns deployed catalog metadata and published context facts only. Draft taxonomy, collection, and policy state are never read, and no decision is derived. If you need a decision — is a use allowed, which rules apply — chain into get_decision_context, inspect_governance_rules, or authorize_use, which return the typed answer states.

Example

Request arguments:

{
  "ref": {
    "database": "acmecloud_demo",
    "schema": "public",
    "table": "customers",
    "column": "email"
  }
}

Response:

{
  "ref": {
    "database": "acmecloud_demo",
    "schema": "public",
    "table": "customers",
    "column": "email"
  },
  "meaning": "Primary contact email address for the customer.",
  "data_type": "text",
  "classification": {
    "sensitivity": "restricted",
    "category": "pii",
    "subcategory": null
  },
  "pii": true,
  "masking": {
    "type": "partial",
    "exempt_roles": ["DATA_STEWARD", "PRIVACY_ADMIN"]
  }
}

The same call without ref.column returns table-level facts for customers: column is null in the echoed ref, data_type is null, and meaning carries the table's catalog description.

Limits and notes

• Facts, not verdicts. A pii: true or masking fact here is descriptive. It does not say whether a given use is allowed — masking facts describe what the governing policy declares, and Metatate never applies masking itself. Use the decision-bearing tools for verdicts.
• No scenario parameter. Data meaning is scenario-independent; there is no scenario_key input on this tool.
• Published facts only. Classification and masking come from published governance state; edits that have not been published do not appear.
• Metering. Every call that passes input validation consumes one MCP call before any read; over quota, the call fails with quota_exceeded. Calls rejected with invalid_parameters are not metered.
• Error codes. Failures are redacted errors returned with isError: true: asset_not_found (the reference does not resolve in this workspace's catalog — a cross-workspace reference is indistinguishable from not found), invalid_parameters, read_failed, plus the shared unauthorized, auth_unavailable, rate_limited, quota_exceeded.

Related

• discover_context — find governed assets to inspect
• get_decision_context — the decision picture for the same asset
• inspect_governance_rules — the governing rules for the same asset
• Catalog — where meanings and classifications are curated
• Policy YAML — how classification and masking are declared
• MCP schemas — full input and output schema reference