Skip to main content

authorize_use

authorize_use answers the central governance question: is this proposed use of a governed asset allowed? You name an asset, describe the use, and optionally state a transfer destination; the tool derives an advisory decision from the current deployment publication's deployed instruction decisions, cites every instruction that applied, and returns a decision_id you can chain into explain_why. Like every Metatate MCP tool it is read-only and advisory — it describes the decision your published policies produce, it never enforces, approves, masks, or blocks anything. Protocol alias: authorize-use.

When to useDirect link to When to use

Call authorize_use before an agent acts on data for a stated purpose — training a model, exporting rows to a CRM, building a marketing segment, quoting a value in a support reply. It is the purpose-level counterpart of validate_query_context: authorize a use when the question is "may I do this with that asset," validate a query when you hold actual SQL. Use discover_context first to find governed assets and their valid scenario_key values, and inspect_governance_rules when you want every rule rather than one effective decision.

InputDirect link to Input

FieldTypeRequiredDescription
assetobjectYesThe governed asset to authorize against.
asset.databasestringYesNormalized database name (1–255 chars).
asset.schemastringYesNormalized schema name.
asset.tablestringYesNormalized table name.
asset.columnstringNoColumn name; omit for a table-level question.
scenario_keystringNoCanonical scenario key (the 65-key library). Preferred; non-canonical values are rejected with invalid_parameters.
usestringYesFree-text description of the proposed use (1–2,000 chars).
operationstringNoTransfer operation token, for example export (1–64 chars, letters, digits, spaces, _, ., -).
destinationobjectNoTransfer destination. When present, at least one of system or jurisdiction is required.
destination.systemstringNoDestination system token, for example SALESFORCE.
destination.jurisdictionstringNoDestination jurisdiction token, for example US.
consumer_jurisdictionstringNoJurisdiction of the data consumer, for example EU.

Inputs are strict — unknown keys are rejected. The scenario resolves in a fixed order: an explicit canonical scenario_key always wins; otherwise the use text is mapped deterministically onto exactly one canonical key; otherwise, when transfer context is present, the question defaults to residency.cross_border_transfer; anything still ambiguous returns the typed scenario_unresolved answer. The mapper never guesses, and free text never becomes a runtime key.

An operation alone is not transfer context — transfer rules activate only when a destination or consumer_jurisdiction is present. A context-less call answers with each transfer rule set's collapsed published verdict.

OutputDirect link to Output

Every response is one of the three typed answer states, discriminated on state, and always carries advisory: true. An answered payload contains:

FieldDescription
decisionThe effective decision: allow, deny, mask_full, mask_partial, require_review, conditional, retain, or log_only.
decision_idThe winning instruction's serving-row UUID — pass it to explain_why as {"kind": "decision", "decision_id": ...}.
reasonThe winning instruction's decision reason.
scenario_key, scenario_laneThe resolved canonical scenario and its lane (platform, agent, or human).
assetThe asset scope; column is explicitly null for table-level answers.
instructionsEvery applicable instruction record, ranked winner first, each with its own decision_id, key and family, decision and reason, policy provenance, resolution paths, and conflict fields.
context_factsAllow-listed published data-meaning facts (sensitivity, category, PII flag, masking), or null.
obligationsHandling steps derived from mask_full/mask_partial rows (a mask obligation with the published masking method) and retain rows.
conditionsFor a conditional decision only: the gates to satisfy — approval_required, anonymize_first, role_restricted, or ai_restriction, each with the required role, the requirement, how to satisfy it, and the policy behind it. Empty otherwise.
prohibitionsReasons derived from deny rows, tagged deny_decision, prohibited_use, or ai_governance by instruction family.
next_actionsFixed guidance strings matched to the decision.
can_proceed_nowtrue only when the decision is allow; false for conditional until the conditions are satisfied.
publicationThe publication_id and published_at of the current deployment publication.

When multiple instructions apply, the effective decision is deterministic: specificity first (column-level beats table-level; within a level, selector beats collection beats taxonomy), then priority, then restrictiveness (deny > mask_full > mask_partial > require_review > conditional > retain > log_only > allow), then a stable key tiebreak.

With transfer context present, each transfer-governance row's verdict is re-derived at read time from its published rule parameters: rules are checked in authored order, and the first rule whose present constraints (operations, destination systems, destination jurisdictions, consumer jurisdictions) all match wins; matching is case-insensitive, and a constraint the context cannot answer never matches. No matching rule falls to the authored default effect. A matched conditional rule emits its specific conditions — approval and anonymize-first can both come from one rule.

Answer statesDirect link to Answer states

StateReason codesWhen
answered—Published rows are sufficient; any of the eight decisions, with citations.
review_requireddecision_requires_review, conflicted_published_stateThe winner is an explicit require_review, or applicable rows conflict. The compatibility decision field is pinned to require_review, can_proceed_now is false, and a conflicted answer carries the conflict group with every opposing source — conflicts are never ranked away.
not_enough_published_stateno_current_publication, no_published_instruction_state, unresolved_published_target, scenario_unresolvedNo current publication, zero applicable rows, unresolved published targets relevant to this asset (listed in unresolved_targets), or an unresolvable scenario (scenario_key is then null).

Unknown assets are a typed asset_not_found error, not an answer state, and a cross-tenant reference is indistinguishable from not found.

ExampleDirect link to Example

Authorizing an AcmeCloud customer export to a specific destination:

{
  "asset": { "database": "acmecloud_demo", "schema": "public", "table": "customers" },
  "use": "sync approved customer fields to the CRM",
  "scenario_key": "residency.cross_border_transfer",
  "operation": "export",
  "destination": { "system": "SALESFORCE", "jurisdiction": "US" },
  "consumer_jurisdiction": "EU"
}

The transfer rules resolve this destination to a conditional decision with its exact gates:

{
  "state": "answered",
  "advisory": true,
  "decision": "conditional",
  "decision_id": "accef000-0000-4000-8000-000000000010",
  "reason": "Transfer to SALESFORCE (US) for consumer jurisdiction EU requires approval and anonymization and role PRIVACY_ADMIN (policy AcmeCloud transfer guardrails).",
  "scenario_key": "residency.cross_border_transfer",
  "scenario_lane": "platform",
  "asset": { "database": "acmecloud_demo", "schema": "public", "table": "customers", "column": null },
  "can_proceed_now": false,
  "conditions": [
    {
      "kind": "anonymize_first",
      "required_role": null,
      "requirement": "This data must be anonymized before the transfer.",
      "satisfied_by": "Anonymize or de-identify the columns in scope, then re-run authorize_use.",
      "required_by_policy": "AcmeCloud transfer guardrails"
    },
    {
      "kind": "approval_required",
      "required_role": "PRIVACY_ADMIN",
      "requirement": "Transfer to SALESFORCE (US) for consumer jurisdiction EU requires approval and anonymization and role PRIVACY_ADMIN (policy AcmeCloud transfer guardrails).",
      "satisfied_by": "Obtain approval from PRIVACY_ADMIN.",
      "required_by_policy": "AcmeCloud transfer guardrails"
    }
  ],
  "obligations": [],
  "prohibitions": [],
  "next_actions": [
    "You may proceed only after satisfying the stated condition(s) below (e.g. obtain the named approval, anonymize first, or act as a granted role).",
    "If the condition cannot be met, treat this use as denied."
  ],
  "context_facts": {
    "sensitivity": "restricted",
    "category": "pii",
    "subcategory": null,
    "pii": true,
    "masking": { "type": "partial", "exempt_roles": ["DATA_STEWARD", "PRIVACY_ADMIN"] }
  },
  "instructions": [
    {
      "decision_id": "accef000-0000-4000-8000-000000000010",
      "instruction_key": "transfer_governance:spec.transferGovernance",
      "instruction_family": "transfer_governance",
      "scenario_key": "residency.cross_border_transfer",
      "scenario_lane": "platform",
      "category": "advisory",
      "priority": 2,
      "weight": 1,
      "enforcement_mode": "enforce",
      "decision": "conditional",
      "decision_reason": "Transfer to SALESFORCE (US) for consumer jurisdiction EU requires approval and anonymization and role PRIVACY_ADMIN (policy AcmeCloud transfer guardrails).",
      "parameters": {
        "defaultEffect": "conditional",
        "rules": [
          {
            "operations": ["export"],
            "destinationSystems": ["SALESFORCE"],
            "destinationJurisdictions": ["US"],
            "consumerJurisdictions": ["EU"],
            "effect": "conditional",
            "requiresApproval": true,
            "requiresAnonymization": true,
            "requiredRole": "PRIVACY_ADMIN"
          },
          { "destinationSystems": ["ADS_PLATFORM"], "effect": "deny" },
          { "destinationSystems": ["EXTERNAL_LLM_VENDOR"], "effect": "deny" }
        ]
      },
      "scope": { "database": "acmecloud_demo", "schema": "public", "table": "customers", "column": null },
      "provenance": {
        "policy_id": "accef000-0000-4000-8000-000000000011",
        "policy_version_id": "accef000-0000-4000-8000-000000000012",
        "policy_name": "AcmeCloud transfer guardrails",
        "version_number": 1
      },
      "primary_resolution_source": "selector",
      "resolution_paths": [{ "source": "selector", "ref": null }],
      "conflict_status": "none",
      "conflict_group_id": null,
      "conflicts_with": []
    }
  ],
  "publication": {
    "publication_id": "accef000-0000-4000-8000-000000000001",
    "published_at": "2026-07-16T00:00:00.000Z"
  }
}

The same call with "system": "ADS_PLATFORM" answers deny, and an unmatched destination falls to the authored default effect — all from the same published instruction. Keys inside parameters are the authored policy DSL carried verbatim, the one documented exemption from the snake_case wire convention.

Limits and notesDirect link to Limits and notes

  • Answers read only the current deployment publication. Draft policies, approved-but-unpublished versions, and superseded publications never affect the decision.
  • The tool never mutates workspace state and never pushes anything to your data platforms; enforcement stays in your systems.
  • A non-canonical scenario_key or malformed input is invalid_parameters and is not metered; every accepted invocation consumes one metered MCP call before any read.
  • explain_why on a transfer decision_id explains the published row's collapsed verdict; destination-specific reasoning lives in this tool's reason and conditions, and the cited record's parameters carry the authored rules for audit.
  • Obligations, conditions, prohibitions, and next actions derive only from published instruction rows and allow-listed context facts — never from your use text.
  • Every response is schema-validated before it leaves the server; a violation returns output_validation_failed, never a partial answer.