Skip to main content

discover_context

discover_context answers the question "what is governed in this workspace?" It lists every governed asset — tables and columns — from the current deployment publication's deployed instruction decisions, with a per-asset instruction count and the canonical scenario keys under which instructions govern it. Results are filterable and paginated. It is an operationally pure read: it describes published governance state, changes nothing, and records nothing. Clients that present hyphenated tool names can call it as discover-context; the alias is accepted 1:1.

When to useDirect link to When to use

Call discover_context first, before any per-asset question:

  • To map the governed surface of a workspace before drilling into a specific table or column.
  • To collect the exact asset references (database, schema, table, column) and canonical scenario_key values that later calls to get_decision_context, inspect_governance_rules, and authorize_use accept.
  • To confirm that a workspace has a current publication at all — if nothing is published, this tool says so with a typed answer state instead of an empty list.

InputDirect link to Input

All parameters are optional. An empty input ({}) lists every governed asset visible to the workspace.

ParameterTypeRequiredDescription
databasestringNoFilter to one database, by exact normalized name (for example master).
schemastringNoFilter to one schema, by exact normalized name (for example public).
domainstringNoFilter by the domain declared on published business_context rules.
sensitivitystringNoOne of public, internal, confidential, restricted. Matches the published classification baseline.
piibooleanNoMatches the published classification baseline. true returns only explicitly-classified PII; false includes unclassified assets.
compliance_tagstringNoMatches published metadata tags, or the regulation named on published compliance rules.
limitintegerNoPage size, 1–200. Defaults to 100. Out-of-range values are rejected with invalid_parameters, never silently clamped.
cursorobjectNoThe next_cursor from the previous page, passed back verbatim.

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

Every filter is applied in the database against published serving state, and matching is exact byte equality — no case folding, no prefixes, no patterns. domain and compliance_tag match the exact asset: a table-level business_context domain does not implicitly qualify that table's columns.

PaginationDirect link to Pagination

An answered page carries next_cursor: an object when another page exists, null on the last page. Pass it back verbatim as cursor to continue.

Two rules matter:

  1. Resend the same filters on every page. The cursor pins the publication and your position in the walk — it does not carry the filter set. A cursor with different filters walks a different list.
  2. The cursor is opaque. Never construct one. Its contents are an implementation detail.

Because the cursor pins a publication, a publish that lands mid-walk invalidates it. That case is a single, deliberate error rather than silently mixed provenance:

  • A malformed cursor — a shape violation such as half a cursor, an invalid UUID, or an unparseable asset key — is invalid_parameters.
  • A well-formed cursor that is unknown, from another workspace, or pinned to a publication that is no longer current (including when there is no current publication at all) is the closed cursor_expired error, identical in all three cases: "The publication changed since this cursor was issued. Restart discovery without a cursor." No workspace or publication identifiers appear in it.

Restart the walk without a cursor when you see it. A single page is read in one publication-pinned pass, so a page can never mix rows from two publications.

OutputDirect link to Output

A successful call returns one JSON payload as the tool result's structured content (also serialized into the text content), discriminated by state.

When the state is answered:

FieldDescription
state"answered".
assetsArray of governed-asset summaries (may be empty after filtering).
assets[].refThe asset scope: database, schema, table, and column. column is always present and is null for a table-level entry. Table-level and column-level scopes appear as separate entries.
assets[].instruction_countHow many published instructions govern this exact scope.
assets[].scenario_keysThe canonical scenario keys under which instructions govern the scope — valid values for scenario_key in follow-up calls.
publicationProvenance of the current deployment publication: publication_id and published_at.
next_cursorThe cursor for the next page, or null on the last page.

Answer statesDirect link to Answer states

discover_context returns two of the three typed answer states — it never returns review_required:

  • answered — a current publication exists and carries instruction state; the governed-asset list is returned.
  • not_enough_published_state — with reason_code no_current_publication (no deployment publication is current) or no_published_instruction_state (a current publication exists but carries zero instruction decisions). The payload carries a fixed message, an unresolved_targets array (always empty for this tool), and next_actions guidance. A missing publication is never reported as an empty "nothing governed" list.

See Typed answer states for the full model.

ExampleDirect link to Example

Request arguments:

{
  "database": "master",
  "schema": "public"
}

Response (trimmed to three assets; a real answer lists every governed scope):

{
  "state": "answered",
  "assets": [
    {
      "ref": {
        "database": "master",
        "schema": "public",
        "table": "customers",
        "column": null
      },
      "instruction_count": 17,
      "scenario_keys": [
        "ai.inference",
        "ai.training",
        "purpose.allowed_use",
        "purpose.prohibited_use",
        "residency.cross_border_transfer"
      ]
    },
    {
      "ref": {
        "database": "master",
        "schema": "public",
        "table": "customers",
        "column": "email"
      },
      "instruction_count": 1,
      "scenario_keys": ["masking.display"]
    },
    {
      "ref": {
        "database": "master",
        "schema": "public",
        "table": "support_tickets",
        "column": null
      },
      "instruction_count": 14,
      "scenario_keys": ["ai.training", "purpose.prohibited_use", "sharing.internal"]
    }
  ],
  "publication": {
    "publication_id": "accef000-0000-4000-8000-000000000001",
    "published_at": "2026-07-16T00:00:00.000Z"
  },
  "next_cursor": null
}

Note that master.public.legacy_customer_backup — a table in the sample estate with no governing policy — does not appear: discover_context lists governed scopes from published instruction state, not the full catalog.

Limits and notesDirect link to Limits and notes

  • Filters are exact matches, evaluated in the database against published serving state. There is no pattern or prefix matching and no case folding. A filter that matches nothing returns answered with an empty assets array — distinct from not_enough_published_state, which means there is no publication or no instruction state at all.
  • This tool is deliberately validity-blind. It reports published coverage, not current effectiveness. An asset whose governing policy version is outside its validity window still appears here — ask a decision-bearing tool (which filters by the evaluation instant) if you need to know whether a rule is in force right now. This is why discover_context is the right tool for mapping an estate and the wrong tool for gating an action.
  • Metering. Every call that passes input validation consumes one MCP call from your plan's metered allowance before any read happens; over quota, the call fails with quota_exceeded. A call rejected with invalid_parameters is not metered. See Plans.
  • Error codes. Failures outside the typed answer states are redacted errors returned with isError: true and a body of the form {"error": {"code", "message"}}: invalid_parameters, cursor_expired, read_failed, unauthorized, auth_unavailable, rate_limited, quota_exceeded.
  • In-app preview differences. The Tools tab previews listing and paging by database / schema; the classification-fact filters (domain, sensitivity, pii, compliance_tag) are served by the deployed endpoint only and the preview refuses them explicitly rather than ignoring them. The preview's restart behaviour on a publication change matches the endpoint; its cursor anchoring is its own, and preview cursors never cross to the endpoint.
  • Current publication only. Draft policies, approved-but-unpublished changes, and pending deployment plans never appear. Publish a deployment to change what this tool reports; see Deployments.