Skip to content
mcp-data-platform composable mcp data platform
v1.x part of txn2 ↗

Tools API Reference

Complete specification for all MCP tools provided by mcp-data-platform.

Empty lists

A list with nothing in it is [] in every tool result and every REST response, never null: an agent or a managed script can iterate a list field without first checking it for null. manage_asset action=get_collection on a collection whose section holds no assets returns "items": [], and on one with no sections "sections": []. Every platform tool result and REST body is encoded by one encoder that writes an empty list this way (#1832).

Error contract

Every failed tool call returns a uniform, self-describing error so an agent can tell a correctable mistake from a platform problem and act on it. A failure sets isError: true and carries both a human-readable text message and a machine-readable structuredContent.error object:

{
  "isError": true,
  "content": [
    { "type": "text", "text": "the \"asset_id\" parameter is required (code: missing_required_parameter) Hint: Supply \"asset_id\" and retry. This is a problem with the call's arguments, not a platform fault." }
  ],
  "structuredContent": {
    "error": {
      "code": "missing_required_parameter",
      "category": "client_input",
      "message": "the \"asset_id\" parameter is required",
      "hint": "Supply \"asset_id\" and retry. This is a problem with the call's arguments, not a platform fault."
    }
  }
}
Field Meaning
code Stable, machine-readable identifier the agent may branch on (for example missing_required_parameter, invalid_arguments, not_found, unauthorized, setup_required, internal_error).
category Broad class (see below) telling the agent whose fault the failure is.
message The specific failure.
hint The corrective action, when the caller can take one.

Categories

Category Whose fault What to do
client_input The call Fix the arguments and retry.
not_found The call The named resource does not exist; correct the reference.
authentication_failed The caller's identity Provide valid credentials.
authorization_denied The caller's identity The persona is not permitted; request access.
user_declined The user A consent prompt was declined.
setup_required Session state Call the required setup tool first.
feature_unavailable Deployment config The feature is not enabled on this deployment; do not present it as an outage.
internal The platform Not the caller's fault; do not retry with modified input.
tool_error Unclassified A tool failure that has not been given a finer category; the message is still descriptive.

The contract is uniform by construction: a normalization layer guarantees every error result carries this envelope even when an individual tool returns only a bare message, so an agent never receives an opaque, undifferentiated string. The category is also recorded on the audit log (error_category) for operators.

Unknown arguments are refused, not ignored

The platform's own tools publish input schemas that are closed to unknown top-level arguments ("additionalProperties": false). A misnamed argument fails at the tool boundary, before the handler runs, with code: invalid_arguments, category: client_input, and a message naming the offending property — for example, passing parameters to api_invoke_endpoint instead of query_params:

{
  "error": {
    "code": "invalid_arguments",
    "category": "client_input",
    "message": "validating \"arguments\": validating root: unexpected additional properties [\"parameters\"]",
    "hint": "The arguments do not match the tool's input schema. Read the tool's schema, correct or drop the named property, and retry. This is a problem with the call's arguments, not a platform fault."
  }
}

Nested maps stay open where they carry a foreign namespace: query_params, headers, and body on the api_* tools accept arbitrary keys, because those names belong to the upstream API rather than to the tool. Tools proxied from an upstream MCP server through a gateway connection keep the upstream's own schema, strict or not.

Trino Tools

trino_query

Execute a read-only SQL query against the Trino cluster. Write operations (INSERT, UPDATE, DELETE, CREATE, DROP, etc.) are rejected before reaching Trino. Annotated with ReadOnlyHint: true for MCP client auto-approval.

Parameters:

Parameter Type Required Default Description
query string Yes - SQL query to execute (read-only)
limit integer No 1000 Maximum rows to return (capped by max_limit config)
connection string No the kind's default: Trino connection name

Response Schema:

{
  "columns": [
    {"name": "column_name", "type": "varchar"}
  ],
  "rows": [
    ["value1", "value2"]
  ],
  "row_count": 100,
  "execution_time_ms": 250,
  "query_id": "20240115_123456_00001_xxxxx"
}

Enrichment (when enabled):

{
  "semantic_context": {
    "description": "Table description from the platform catalog",
    "owners": [{"name": "Team Name", "type": "group"}],
    "tags": ["tag1", "tag2"],
    "domain": {"name": "Domain Name"},
    "quality_score": 0.95,
    "deprecation": null
  }
}

Error Codes:

Code Cause
SYNTAX_ERROR Invalid SQL syntax
TABLE_NOT_FOUND Referenced table doesn't exist
PERMISSION_DENIED Insufficient privileges
TIMEOUT Query exceeded timeout
WRITE_REJECTED Write SQL rejected (use trino_execute instead)

trino_execute

Execute any SQL against the Trino cluster, including write operations (INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, etc.). Annotated with DestructiveHint: true so MCP clients prompt for confirmation.

read_only is set per instance, and the block applies to the connection the call names — or to the default connection when it names none. A call routed to an instance with read_only: true is refused; the other instances of the same toolkit still accept writes.

Parameters:

Parameter Type Required Default Description
query string Yes - SQL query to execute
limit integer No 1000 Maximum rows to return (capped by max_limit config)
connection string No the kind's default: Trino connection name

Response Schema: Same as trino_query.


trino_explain

Get the execution plan for a SQL query.

Parameters:

Parameter Type Required Default Description
query string Yes - SQL query to explain
connection string No the kind's default: Trino connection name

Response Schema:

{
  "plan": "Query Plan\n- TableScan[table = ...]\n  ...",
  "format": "text"
}

trino_browse

Browse the Trino catalog hierarchy. Omit all parameters to list catalogs. Provide catalog to list schemas. Provide catalog and schema to list tables.

Parameters:

Parameter Type Required Default Description
catalog string No - Catalog name. Omit to list all catalogs
schema string No - Schema name. Requires catalog. Omit to list schemas
pattern string No - LIKE pattern to filter tables (only when listing tables)
connection string No the kind's default: Trino connection name

Response Schema (list catalogs):

{
  "catalogs": ["hive", "iceberg", "memory"]
}

Response Schema (list schemas):

{
  "catalog": "hive",
  "schemas": ["default", "sales", "marketing"]
}

Response Schema (list tables):

{
  "catalog": "hive",
  "schema": "sales",
  "tables": [
    {"name": "orders", "type": "TABLE"},
    {"name": "customers", "type": "TABLE"},
    {"name": "daily_revenue", "type": "VIEW"}
  ]
}

trino_describe_table

Get table schema and metadata.

Parameters:

Parameter Type Required Default Description
table string Yes - Table name (can be catalog.schema.table)
connection string No the kind's default: Trino connection name

Response Schema:

{
  "table": {
    "catalog": "hive",
    "schema": "sales",
    "name": "orders"
  },
  "columns": [
    {
      "name": "order_id",
      "type": "bigint",
      "nullable": false,
      "comment": "Unique order identifier"
    }
  ],
  "partitioning": ["order_date"],
  "properties": {
    "format": "PARQUET"
  }
}

trino_list_connections

List configured Trino connections.

Parameters: None

Response Schema:

{
  "connections": [
    {
      "name": "primary",
      "display_name": "Production",
      "host": "trino.example.com",
      "catalog": "hive",
      "schema": "default"
    }
  ]
}

Catalog Reads

The platform's catalog is read with search and fetch, and curated with apply_knowledge; no catalog toolkit is registered. fetch returns {found, reference, document}, and a catalog read fills the document's content with the shapes below.

A fetched dataset (fetch mcp:dataset:(trino,warehouse,sales.orders)):

{
  "id": "6c0f7a8e-0b1a-4f8e-9c51-7e2f3d4a5b6c",
  "reference": "mcp:dataset:(trino,warehouse,sales.orders)",
  "name": "orders",
  "type": "table",
  "columns": [
    {"name": "order_id", "data_type": "bigint", "ordinal": 1, "nullable": false,
     "aspects": {"description": "Unique order identifier"}},
    {"name": "customer_id", "data_type": "bigint", "ordinal": 2, "nullable": true,
     "aspects": {"tags": ["pii"], "glossary_terms": ["mcp:glossary_term:3b9e"]}}
  ],
  "aspects": {
    "description": "One row per order",
    "tags": ["financial"],
    "glossary_terms": ["mcp:glossary_term:7d21"],
    "owners": [{"owner": "[email protected]", "type": "technical_owner"}],
    "domain": "mcp:domain:4f1c",
    "curated_queries": [{"name": "completed orders", "sql": "SELECT * FROM sales.orders WHERE status = 'complete'"}],
    "context_documents": [{"id": "d1", "title": "Orders runbook", "content": "...", "category": "runbook"}]
  },
  "created_at": "2026-10-01T09:00:00Z",
  "updated_at": "2026-10-12T14:30:00Z",
  "upstream": [
    {"source": "mcp:dataset:(trino,warehouse,raw.orders)", "target": "mcp:dataset:(trino,warehouse,sales.orders)",
     "writer_kind": "query", "written_by": "[email protected]", "written_at": "2026-10-12T02:00:00Z", "depth": 1}
  ],
  "downstream": [],
  "query_availability": {"available": true, "query_table": "sales.orders", "connection": "warehouse", "estimated_rows": 1500000}
}

A dataset reference whose path stops above a dataset lists what is under it (fetch mcp:dataset:(trino,warehouse,sales)):

{
  "connection_kind": "trino",
  "connection": "warehouse",
  "path": ["sales"],
  "entries": [
    {"name": "orders", "reference": "mcp:dataset:(trino,warehouse,sales.orders)", "datasets": 0, "type": "table"}
  ]
}

fetch mcp:connection:(trino,warehouse) lists the top of the connection's catalog in the same entries form under catalog.

A fetched glossary term, node, tag, domain or data product (fetch mcp:glossary_term:7d21):

{
  "reference": "mcp:glossary_term:7d21",
  "kind": "glossary_term",
  "name": "Revenue",
  "description": "Gross sales before returns and discounts",
  "parent": "mcp:glossary_node:1a02",
  "carriers": [
    {"reference": "mcp:dataset:(trino,warehouse,sales.orders)", "dataset": "mcp:dataset:(trino,warehouse,sales.orders)",
     "name": "orders", "connection": "warehouse"}
  ]
}

A glossary node carries children (the terms and nodes under it) instead of carriers. more_carriers, carriers_withheld and notice report a list cut at 25 and the carriers on connections the caller's persona does not reach.

The datahub_* tools are not registered under any name; see Tools for what replaces each kind of read and write.

S3 Tools

Two tools (#1591): s3_list lists buckets or one bucket's objects, s3_object performs one action over a (bucket, key). Both are registered on every connection; put, copy, delete and presign with method: PUT on a connection configured read_only: true are refused with an error naming the connection.

s3_list

List the buckets of a connection, or the objects in one bucket.

Parameters:

Parameter Type Required Default Description
bucket string No - Bucket to list objects in; omit to list buckets
prefix string No - Key prefix filter
delimiter string No - Delimiter for hierarchy (typically /)
max_keys integer No 1000 Objects per page (1-1000)
continuation_token string No - Token from the previous page
connection string No first configured S3 connection name

Response Schema (no bucket):

{
  "buckets": [
    {
      "name": "data-lake",
      "creation_date": "2024-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

Response Schema (bucket named):

{
  "bucket": "data-lake",
  "prefix": "sales/orders/",
  "delimiter": "/",
  "objects": [
    {
      "key": "sales/orders/2024/01/data.parquet",
      "size": 52428800,
      "last_modified": "2024-01-15T10:30:00Z",
      "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
      "storage_class": "STANDARD"
    }
  ],
  "common_prefixes": ["sales/orders/2024/02/"],
  "count": 1,
  "is_truncated": false
}

s3_object

Act on one object.

Parameters:

Parameter Type Required Default Description
action string Yes - get, metadata, put, copy, delete, presign
bucket string Yes - Bucket name
key string Yes - Object key
content string for put - Content as text, or base64 with is_base64
content_type string No application/octet-stream MIME type (put)
is_base64 boolean No false content is base64-encoded binary (put)
metadata object No - Custom metadata (put; on copy replaces the source's)
dest_bucket string No same bucket Destination bucket (copy)
dest_key string for copy - Destination key (copy)
method string No GET GET or PUT (presign)
expires_in integer No 3600 Seconds until the URL expires, max 604800 (presign)
connection string No first configured S3 connection name

Response Schema (get):

{
  "bucket": "data-lake",
  "key": "config/settings.json",
  "size": 25,
  "content_type": "application/json",
  "last_modified": "2024-01-15T10:30:00Z",
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "content": "{\"setting\": \"value\"}",
  "is_base64": false
}

Note: get is limited by max_get_size; binary content is returned base64-encoded with is_base64: true.

Response Schema (metadata):

{
  "bucket": "data-lake",
  "key": "sales/orders/data.parquet",
  "size": 52428800,
  "content_type": "application/octet-stream",
  "content_length": 52428800,
  "last_modified": "2024-01-15T10:30:00Z",
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "metadata": {
    "created-by": "etl-pipeline"
  }
}

Response Schema (put):

{
  "bucket": "data-lake",
  "key": "uploads/file.json",
  "size": 1024,
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
}

Note: put is limited by max_put_size.

Response Schema (copy):

{
  "source_bucket": "data-lake",
  "source_key": "original/file.json",
  "dest_bucket": "data-lake",
  "dest_key": "backup/file.json",
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "last_modified": "2024-01-15T10:30:00Z"
}

Response Schema (delete):

{
  "bucket": "data-lake",
  "key": "uploads/file.json",
  "deleted": true
}

Response Schema (presign):

{
  "bucket": "data-lake",
  "key": "uploads/file.json",
  "url": "https://bucket.s3.amazonaws.com/key?X-Amz-...",
  "method": "GET",
  "expires_in_seconds": 3600,
  "expires_at": "2024-01-15T11:00:00Z"
}

Read-only refusal: on a connection configured read_only: true, put, copy and delete return an error result:

Error: connection "archive" is read-only: s3_object action "delete" is not permitted on it

A presign with method: PUT is refused there too, because the URL it returns uploads to the key until it expires; a GET presign is still issued:

Error: connection "archive" is read-only: s3_object action "presign" with method PUT is not permitted on it; presign with method GET is

Knowledge Tools

For the full governance workflow, see Knowledge Capture.

memory_capture

Record domain knowledge shared during a session (memory toolkit). Available to all personas when the memory layer is enabled (memory defaults on when a database is configured; memory.enabled: false disables capture).

Parameters:

Parameter Type Required Default Description
type string Yes - Sink-class. Live: personal_preference, episodic_event. Reviewed (creates a pending insight): business_knowledge, schema_entity, operational_rule
content string Yes - The knowledge to record (10-4000 characters)
confidence string No medium Confidence level: high, medium, low
entity_urns array No [] Catalog references this knowledge relates to (mcp:dataset:(kind,connection,path), max 10)
related_columns array No [] Columns related to this knowledge (max 20)
suggested_actions array No [] Proposed catalog changes (max 5)

Suggested Action Schema:

Field Type Required Description
action_type string Yes One of: update_description, add_tag, add_glossary_term, flag_quality_issue, add_documentation, add_curated_query
target string Yes Target of the change (entity name, column name, or URL)
detail string Yes Change detail (new description, tag name, term name, query name, etc.)
query_sql string Conditional SQL statement (required for add_curated_query)
query_description string No Optional description for add_curated_query

Response Schema:

{
  "insight_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "status": "pending",
  "message": "Insight captured. It will be reviewed by a data catalog administrator."
}

apply_knowledge

Review, synthesize, and apply captured insights to the platform catalog. Admin-only. Requires knowledge.apply.enabled: true.

Parameters:

Parameter Type Required Description
action string Yes One of: bulk_review, review, synthesize, apply, approve, reject, rollback, list_changesets, bulk_untag
entity_urn string Conditional Required for review, synthesize, apply, list_changesets; optional for rollback (validates the changeset belongs to this entity). A catalog reference (mcp:dataset:(kind,connection,path), mcp:column:(...), mcp:glossary_term:<id>, mcp:glossary_node:<id>, mcp:domain:<id>, mcp:data_product:<id>, mcp:tag:<name>). Any other form is refused
tag_urn string Conditional Required for bulk_untag; the tag (a name or mcp:tag:<name>) to remove from every dataset and column that carries it
insight_ids array Conditional Required for approve, reject; optional for synthesize, apply
changes array Conditional Required for apply with sink: "catalog"
sink string No Where an apply writes: catalog (default, writes changes to entity_urn in the platform catalog), knowledge_page (promotes to a canonical page via page), or agent_instructions (promotes an operating rule into the deployment's own instructions via instructions). The capture-time sink_class is a hint, not a binding
page object Conditional Required for sink: "knowledge_page": {slug, title, summary, body, tags, references, force_new}. Found-or-created by slug, so a repeat promotion consolidates. The response carries portal_url, where the page is read, so the address handed to a person is one the platform composed rather than one the caller guessed
instructions object Conditional Required for sink: "agent_instructions" (see below)
changeset_id string Conditional Required for rollback
confirm bool No Required when require_confirmation is enabled (for apply and rollback)
review_notes string No Notes for approve/reject actions
itemize bool No With bulk_review, also return the pending insights themselves (full insight_text body, captured_by, sink_class, created_at, suggested_actions_count, ...; full suggested_actions omitted, fetch for it), paginated by offset/limit. The insights window is byte-budgeted (page_size_capped: true flags a short page, continue with next_offset) and by_entity is capped (by_entity_truncated: true) so the response stays under the output limit
limit int No Page size for itemized bulk_review (default 20, max 100)
offset int No Page start for itemized bulk_review; pass the previous next_offset to continue

Instructions Schema (for sink: "agent_instructions"):

Field Type Required Description
section string Yes Heading the rule lives under, and the find-or-create key. One line, no #, at most 120 characters
body string Yes The rule text. Over 1,500 bytes it is written to a knowledge page and the section keeps a one-line mcp:knowledge_page:<slug> index entry pointing at it; the response then carries the page's page_id and its portal_url
slug string No Slug for the page a diverted body lands on (default: a slug derived from section)
title string No Title for the page a diverted body lands on (default: section)
summary string No One line saying what reading the page answers; it becomes the index entry the instructions keep
tags array No Tags for the page a diverted body lands on; the origin sink-class is added automatically
references array No Entity references to attach to that page, in the forms page.references accepts

The promotion writes only its own section, leaving every other section byte-identical; records a changeset under target ai:<section> that list_changesets lists and rollback reverts; is refused when it names a tool the deployment does not register; and is refused when it would push the layer past its byte limit. It needs a database-backed config store. See Knowledge.

Change Schema (for apply action):

Field Type Required Description
change_type string Yes One of: update_description, add_tag, remove_tag, add_glossary_term, flag_quality_issue, add_documentation, add_curated_query, set_structured_property, remove_structured_property, raise_incident, resolve_incident, add_context_document, update_context_document, remove_context_document, delete_tag, set_custom_property, remove_custom_property
target string Yes Target of the change (see below)
detail string Yes Change detail (see below)
query_sql string Conditional SQL statement (required for add_curated_query). For update_context_document, the new title
query_description string No Optional description for add_curated_query. For add_context_document/update_context_document, the document category

Target and detail by change type:

A dataset and its columns carry every kind of curation; curated queries, incidents and context documents are dataset-only; a glossary term, glossary node, domain, data product or tag carries a description, owners, custom properties and documentation links.

Change Type Target Detail
update_description column:<name> for a column, empty for the entity Description text
add_tag / remove_tag column:<name> for a column, empty for the entity Tag name (an mcp:tag: prefix is read as the name)
add_glossary_term column:<name> for a column, empty for the entity Term reference or name; a name the catalog does not hold creates the term
flag_quality_issue Ignored Quality issue description (sets the QualityIssue tag; on a dataset with a detail, also opens an incident carrying it)
add_documentation URL Link description
add_curated_query Ignored Query name
set_structured_property Property name Value or JSON array
remove_structured_property Property name Ignored
raise_incident Incident title Description
resolve_incident Incident id (from created_ids) Resolution message
add_context_document Document title Document content
update_context_document Document id (from created_ids) New content
remove_context_document Document id Ignored
delete_tag Ignored (entity_urn is mcp:tag:<name>) Ignored
set_custom_property Key Value
remove_custom_property Key Ignored

delete_tag takes the tag off every dataset and column carrying it. The changes of one apply are written in one transaction, and every change type is undone by rollback.

Actions:

Action Description Required Params
bulk_review Counts of all pending insights; pass optional itemize: true (with limit/offset) to enumerate the queue, each with its full insight_text body, captured_by, sink_class, and suggested_actions_count (response bounded per page; page_size_capped/by_entity_truncated flag any cut) None
review Insights for a specific entity with its current catalog curation entity_urn
approve Transition insights to approved status insight_ids
reject Transition insights to rejected status insight_ids
synthesize Structured change proposals from approved insights entity_urn
apply Write to the sink sink selects, with changeset tracking entity_urn + changes (catalog), page (knowledge_page), or instructions (agent_instructions)
list_changesets List a target's changesets (id, timestamp, actor, change type, rollback status). The target is a catalog URN, kp:<slug> for a page, or ai:<section> for an instruction section entity_urn
rollback Restore every aspect a changeset wrote to the value it replaced changeset_id, confirm
bulk_untag Remove a tag from every dataset and column carrying it, up to 500 per call, recording one changeset that rollback undoes tag_urn, confirm

rollback restores, in one transaction, every aspect the changeset wrote to the value it replaced, returns the source insights to the review queue, and marks the changeset rolled back. It is refused, and reverts nothing, if the changeset is already rolled back, if an aspect it wrote has been written again since, if it created a prompt, or if it was written before the platform catalog held its entities (an apply from a release that wrote to DataHub).

Response Schema (apply):

{
  "changeset_id": "cs_x1y2z3a4b5c6d7e8f9a0b1c2d3e4f5a6",
  "entity_urn": "mcp:dataset:(trino,warehouse,hive.sales.orders)",
  "changes_applied": 2,
  "catalog_changes": 2,
  "insights_marked_applied": 1,
  "revertible": true,
  "resulting_state": {
    "description": "Order records with gross margin amounts (before returns)",
    "tags": ["gross-margin"],
    "glossary_terms": [],
    "owners": []
  },
  "message": "Changes written to the platform catalog. Roll back with action=rollback changeset_id=cs_x1y2z3a4b5c6d7e8f9a0b1c2d3e4f5a6."
}

revertible is true for every catalog changeset except one that created a prompt; then unrevertible_change_types names add_prompt. created_ids lists the ids of the incidents and context documents the apply opened and the references of the glossary terms it created. list_changesets entries carry the same two fields (and report false once a changeset has been rolled back, or for a changeset applied before the platform catalog held its entities).

See Governance Workflow for detailed examples of each action.


Portal Tools

The portal toolkit persists AI-generated assets to S3 with PostgreSQL metadata. Requires portal.enabled: true.

save_asset

Save AI-generated content (JSX dashboard, HTML report, SVG chart, etc.) to the asset portal as a versioned asset. Captures provenance: the calls the asset was built from, read from the audit log at write time. See Provenance.

Parameters:

Parameter Type Required Default Description
name string Yes - Display name (max 255 chars)
content string Yes - Artifact content
content_type string Yes - MIME type: text/html, text/jsx, image/svg+xml, text/markdown, application/json, application/x-ndjson, text/csv, text/tab-separated-values, application/xml, application/yaml, application/sql, text/plain

A generic content_type (text/plain or application/octet-stream) is replaced by the type detected from the content, so a JSON payload saved under a catch-all type still opens in the JSON viewer. A specific declaration is always honored. Detection can only reclassify content into passive families: it never promotes a payload to text/html, text/jsx or image/svg+xml. See Content Types and Viewers. | description | string | No | "" | Description (max 2000 chars) | | tags | array | No | [] | Tags for categorization (max 20 tags, each max 100 chars) | | sources | array | No | session window | The calls this asset was built from, as the call_id (or mcp:call:<id> reference) each query and API invocation returns. Replaces the default window; only the caller's own calls resolve (max 100) |

Response Schema:

{
  "asset_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "portal_url": "https://portal.example.com/portal/assets/a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "message": "Artifact saved successfully.",
  "provenance_captured": true,
  "calls_recorded": 5
}

Storage layout:

Content is stored in S3 at {s3_prefix}{user_id}/{asset_id}/content.{ext} where the extension is derived from the content type.


manage_asset

List, retrieve, update, delete, or share saved assets. All mutations enforce ownership: users can only modify their own assets.

Parameters:

Parameter Type Required Default Description
action string Yes - One of: list, get, update, delete, search, share, list_shares, revoke_share
asset_id string Conditional - Required for get, update, delete, share, list_shares
content string No - New content (for update — replaces S3 object)
name string No - New name (for update)
description string No - New description (for update)
tags array No - New tags (for update)
content_type string No - New content type (for update, only when replacing content)
sources array No session window The calls behind a content edit (update, patch), as call_id values or mcp:call:<id> references. Recorded as a new capture alongside the ones earlier versions carry
query string Conditional - Free-text relevance query (required for search)
limit integer No 50 Max results for list (max 200); ranked search defaults to 20 (max 100)
recipient string No - Who to share with (share): an email address, or a name resolved against the known-users directory. Omit for a link share
permission string No viewer viewer or editor (share). A link share is always viewer
access_mode string No authenticated Who a link share admits (share, no recipient): authenticated or public
expires_in string Conditional - Duration bounding a public link (24h). Required for access_mode: public, refused for every other share
share_id string Conditional - Share to end (required for revoke_share)

Actions:

Action Description Required Params
list Show current user's assets None
get Retrieve full asset metadata asset_id
update Change metadata or replace content asset_id
delete Soft-delete an asset asset_id
search Rank the caller's own assets by relevance to query (hybrid vector + lexical, lexical-only fallback). Returns each match with a score plus a ranking field; scoped server-side to the caller's own assets by owner_id (the library's ownership key) and fails closed without an identity. query
share Grant access to an asset you own. With recipient: a restricted share addressed to that person, who is emailed the link. Without: a link, authenticated by default. Owner (or admin) only; anonymous callers refused. asset_id
list_shares The shares that currently grant access to the asset — revoked and expired ones excluded — with recipient, permission, access mode, view URL, and access count asset_id
revoke_share End one share by ID. Its token stops opening the asset immediately share_id

Registering an asset as a queryable table is the separate manage_table tool, which serves an uploaded resource through the same action.

Response Schema (list):

{
  "assets": [
    {
      "id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
      "owner_id": "[email protected]",
      "name": "Revenue Dashboard",
      "description": "Monthly revenue breakdown",
      "content_type": "text/html",
      "s3_bucket": "portal-assets",
      "s3_key": "artifacts/user/asset-id/content.html",
      "size_bytes": 4096,
      "tags": ["dashboard", "revenue"],
      "provenance": {
        "user_id": "[email protected]",
        "session_id": "dps_abc123",
        "captures": [
          {
            "tool": "save_asset",
            "captured_at": "2026-01-15T10:05:00Z",
            "version": 1,
            "session_id": "dps_abc123",
            "event_ids": ["8kQ2f1uVQ2S1p0aT4Hn2Zw"],
            "calls": [
              {
                "event_id": "8kQ2f1uVQ2S1p0aT4Hn2Zw",
                "kind": "sql",
                "tool": "trino_query",
                "connection": "warehouse",
                "statement": "SELECT region, revenue FROM sales.quarterly",
                "purpose": "Totalling Q4 revenue by region for the board deck.",
                "outcome": "success",
                "duration_ms": 1840,
                "timestamp": "2026-01-15T10:00:00Z"
              }
            ]
          }
        ]
      },
      "created_at": "2024-01-15T10:05:00Z",
      "updated_at": "2024-01-15T10:05:00Z"
    }
  ],
  "total": 1
}

Response Schema (update/delete):

{
  "asset_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "message": "Asset updated successfully."
}

Error Codes:

Condition Error Message
Missing asset_id asset_id is required for {action} action
Asset not found asset not found: ...
Wrong owner you can only {action} your own assets
Invalid action invalid action "...": must be one of: list, get, update, delete

manage_table

Make a stored CSV, JSON-lines or Parquet file readable as a query-engine table over the directory the file already sits in, so trino_query can join it to warehouse tables. Nothing is copied or ingested. A CSV's columns are all VARCHAR; a JSON-lines file's are typed from its values and a Parquet file's are the types its footer declares (Registered Tables).

The file is named by its reference, the string a search hit and a fetch document carry, so one action serves every kind of stored file and no argument names the kind.

Parameters:

Parameter Type Required Default Description
action string Yes - One of: register, list, unregister
reference string Conditional - The file: mcp:resource:<id> (uploaded reference material) or mcp:asset:<id> (saved asset). Required for register and list
connection string Conditional - Trino connection whose scratch schema holds the table (required for register)
table_name string No filename slug Name for the registered table; persona-prefixed either way
follow boolean No true Whether the table follows the file: each revision or version written over it moves the table onto the new contents. false pins the table to the version it is registered over
repair boolean No false Save a corrected version of a file that cannot be read as a table the way it is stored, and register that. The choice is kept on the registration: a following table corrects each later version carrying the same kind of defect and moves onto the corrected version
registration_id string Conditional - Registration to drop (required for unregister), read off a row of table_registrations

Actions:

Action Description Required Params
register Create an external table over the file. The response carries each column's declared type in column_types, and a sample statement: for a CSV, whose columns are all VARCHAR, it shows the CAST a typed join needs reference, connection
list The registrations over this file, under table_registrations: each with its registration_id, columns and column_types, whether it follows the file (follow), whether the file has moved on since (stale), and why a following table is behind (follow_error). Check here before registering: registering the same name again replaces the row and changes its id reference
unregister Drop one registered table. The file itself is unchanged registration_id

Response Schema (register):

{
  "reference": "mcp:resource:res_01HK7R9F",
  "registration_id": "reg_9f2c1d4b8a3e5602",
  "connection": "scratch",
  "query_table": "scratch.uploads.analyst_vendor_keys",
  "columns": ["store_id", "vendor_code", "rebate_pct"],
  "column_types": [
    {"name": "store_id", "type": "VARCHAR"},
    {"name": "vendor_code", "type": "VARCHAR"},
    {"name": "rebate_pct", "type": "VARCHAR"}
  ],
  "sample_sql": "SELECT ... CAST(u.store_id AS integer) ...",
  "registered_by": "[email protected]",
  "stale": false,
  "follow": true,
  "format": "csv",
  "message": "Registered as scratch.uploads.analyst_vendor_keys on connection scratch. Every column of a CSV is VARCHAR, so a join to a typed column needs a CAST. The table follows the file: each revision or version written moves it onto the new contents. Register with follow=false for a table pinned to this version."
}

Response Schema (list):

{
  "reference": "mcp:resource:res_01HK7R9F",
  "table_registrations": [
    {
      "registration_id": "reg_9f2c1d4b8a3e5602",
      "connection": "scratch",
      "query_table": "scratch.uploads.analyst_vendor_keys",
      "columns": ["store_id", "vendor_code", "rebate_pct"],
      "sample_sql": "SELECT ... CAST(u.store_id AS integer) ...",
      "registered_by": "[email protected]",
      "stale": false,
      "follow": true,
      "repair": false
    }
  ],
  "total": 1
}

The same registrations reach a search hit and a fetch document under tables, projected for the caller who only wants to write the query rather than change a registration. table_changes, which a content write reports, is neither: it is one sentence per table saying what that write did to it. See Registered Tables.

Error Codes:

Condition Error Message
Missing reference reference is required for {action}: pass the mcp:resource: or mcp:asset: reference from a search hit, verbatim.
Missing connection connection is required for register: ...
Missing registration_id registration_id is required for unregister: ...
Not a stored-file reference reference "..." is not a reference to a stored file: ...
Missing, deleted, or not yours that reference names no stored file you can register
No signed-in identity Registering a table needs a signed-in identity. ...
Deployment cannot register This deployment cannot register tables: it needs a Trino connection with a scratch catalog and schema configured. ...

Who may register is authority to change the file, not to read it: an asset by its owner or an administrator, a resource by its uploader or an administrator of its scope. See Registered Tables.


manage_resource

Manage a file in the managed resource library. A managed resource is the only kind of file a saved asset can reference, so this is what makes the data half of a referencing asset refreshable by the platform rather than only by a person at an upload form: a scheduled script rewrites the CSV a dashboard reads, and the dashboard is not touched.

Two of the five actions write content, and three round out the lifecycle around them: get answers what is filed at an address, list reports a folder, and delete removes a file. Without them a caller had to remember the id of everything it ever wrote, because create refuses an address that is already taken, replace_content needs a reference, and search is relevance-ranked rather than a lookup.

Content crosses the wire in one of two fields. content carries text — CSV, JSON, Markdown, SVG — and content_base64 carries base64-encoded bytes for a binary file such as a PNG or a PDF. Exactly one is given, and both are capped at the deployment's portal.max_content_size (10 MB by default), the same cap save_asset applies.

A create declares what the bytes are in content_type; a create that does not is refused. The type is not detected on this path, because the families an agent writes most cannot be named from content: SVG, HTML, JSX and Markdown are all stored text/plain when nothing is declared, and text/plain under nosniff is a broken image or an unrendered document wherever an asset references the file. A replace_content keeps the type the resource already carries unless it declares a new one, so a refresh cannot reclassify a file under every reference to it. The types the platform stores are listed on the built-in knowledge page mcp:knowledge_page:platform-content-types-for-stored-files and in Content Types and Viewers.

Parameters:

Parameter Type Required Default Description
action string Yes - One of: create, replace_content, get, list, delete
reference string Conditional - The resource to act on: mcp:resource:<id>, from a search hit, a fetch document, or a create. Required for replace_content; for get and delete it is the alternative to naming the address
if_exists string No fail What a create does when the address already holds a file: fail refuses it, replace records the next version of what is there
force boolean No false Delete a file even though something still points at it
limit integer No 100 How many files one page of a list holds; 100 is also the largest page
offset integer No 0 How many files to skip before a list's page
content string Conditional - The file as text. This or content_base64
content_base64 string Conditional - The file as base64-encoded bytes. This or content
content_type string Conditional - Media type the bytes are (required for create). Not detected: SVG, HTML, JSX and Markdown all read as plain text to a byte sniffer. replace_content keeps the type the resource already carries when it is omitted; a file stored under a generic type is re-detected from its bytes
filename string Conditional - Name of the file, normalized to lowercase with spaces replaced. Required for create, and for a get or delete that names the address. replace_content ignores it
display_name string Conditional - Name shown in the resource library (required for create)
path string Conditional - The folder path the file is filed under inside its library, for example datasets or datasets/media-manager/shows. Required for create, and for a get or delete that names the address; for list it is the folder the listing is rooted at, and everything beneath it is included. Slash-separated; each folder name is lowercase letters, digits and hyphens starting with a letter or digit, at most 31 characters; at most 8 folders deep and 200 characters overall
description string Conditional - What the file is and what reads it (required for create)
tags string[] No [] Tags for filtering in the library
scope string No user user, persona, or global. For list, omitting it means every library you can see rather than only your own
scope_id string No you Persona name for scope=persona; must be empty for scope=global
change_summary string No Content replaced via manage_resource Why the content changed, shown in the version history beside the revision
size_bytes integer Conditional - For upload_link: the most the file may be, in bytes, at most the deployment's upload limit
ttl_seconds integer No 900 For upload_link: how long the link lives, at most 3600

Actions:

Action Description Required Params
create File new content as a managed resource and report its mcp:// URI and its mcp:resource: reference. With if_exists=replace it records the next version of whatever is already at that address instead of refusing filename, display_name, path, description, content_type, content
replace_content Write new content over an existing resource, keeping its id, URI and filename, and record the change as its next version reference, content
get Report what is filed at an address, or what a reference names, without the bytes. Nothing there is found: false rather than an error, on either branch path + filename, or reference
list Report the files under a folder, newest first, with the total the page was cut from -
delete Remove a file and its version history, refusing while something still points at it path + filename, or reference
upload_link Issue a single-use link on the platform's own origin that a file larger than a tool call is PUT to from a shell (curl -T), filed at the address as the caller with the checks a portal upload gets (#2639). The answer carries upload_url, method (PUT), expires_at, max_bytes and an example curl; the PUT answers 201 with the resource's reference. The link is good for one PUT, expires after ttl_seconds, refuses a body past size_bytes (413), and an unknown, used or expired link answers 404. A saved script's run cannot ask for one filename, display_name, path, description, content_type, size_bytes

Response Schema (create):

{
  "resource_id": "a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "reference": "mcp:resource:a1b2c3d4e5f67890a1b2c3d4e5f67890",
  "uri": "mcp://user/550e8400-e29b-41d4-a716-446655440000/datasets/weather-daily.csv",
  "filename": "weather-daily.csv",
  "display_name": "Daily Weather",
  "scope": "user",
  "scope_id": "550e8400-e29b-41d4-a716-446655440000",
  "category": "datasets",
  "content_type": "text/csv",
  "size_bytes": 2481,
  "message": "Created. Reference it from an asset by passing the uri above in save_asset's 'references', ..."
}

get returns found, what it looked up -- the uri for an address, the reference for a reference, each reported whether or not anything answers it -- and a resource record carrying everything a fetch of the reference would except the bytes. Finding nothing is an answer and not a failure on both branches: an empty address and a reference naming a file that is gone or outside what the caller can see are each found: false, the same way fetch answers a dangling reference, so a script deciding between replace_content and create reads a deleted file as absent rather than as a failed call. A read that failed stays a tool error, because creating on a failed read files a second copy of a file that is already there. list returns path, resources as that same record shape, total and offset. delete returns deleted, and on a refusal the holds counts and the table_registrations that stopped it, in the shape manage_table action=list reports.

replace_content returns the same shape plus version, the number the content was recorded as, and table_changes when a table is registered over the file: one sentence per table, saying it followed onto the new version (scratch.uploads.analyst_stores on scratch now reads version 7.) or is pinned and now behind it, with the same sentences appended to message. A create reports no version: it records version 1 only where the deployment keeps a version trail, and a number the history may not hold is worse than none. See Following the file.

Error Codes:

Condition Error Message
Missing content type on a create content_type is required for create: name the media type the bytes are ...
Missing content content is required: pass the file as text in 'content', or as base64-encoded bytes in 'content_base64' ...
Both content fields pass content or content_base64, not both: ...
Malformed base64 content_base64 is not valid base64: ...
Over the size cap content size N exceeds maximum M bytes. A file this large has to be uploaded through the portal's resource library ...
Scope refused you cannot write to the global scope, which is administrators only: managed-resource write refused
Missing reference reference is required for replace_content: pass the mcp:resource:<id> reference ...
Reference of another kind reference "..." names a target of type "asset", not "resource". ...
Missing, deleted, or not visible (replace_content and delete; get answers found: false instead) there is no managed resource "<id>" you can see: no such managed resource
No version trail this deployment keeps no version history for managed resources, so content cannot be replaced: managed-resource write unavailable
No signed-in identity Writing a managed resource needs a signed-in identity. ...
No managed-resource layer This deployment has no managed-resource library to write to: ... Nothing was saved.
Neither a reference nor an address name the file to act on: either its mcp:resource:<id> reference, or the address it is filed at as scope, path and filename. Nothing was changed
An if_exists the tool does not take if_exists "overwrite" is not one this tool takes: pass "fail" ... or "replace" ...
Delete refused by what points at the file Not deleted: 2 assets reference this file, 1 prompt attaches this file. ... call this again with force=true to delete it and break them.
Delete whose dependency check failed could not establish what depends on this file, so it was not deleted. Try again, or pass force=true ...
Delete refused by scope you cannot delete a file in the "analyst" persona scope, which is that persona's administrators only: managed-resource write refused

Creating is scope authority — your own user scope, a persona you administer, or the global scope as a platform administrator — and a refusal names the scope rather than the file, because where it was filed is what the caller has to change. Replacing and deleting are the authority to change that file: its uploader, or an administrator of its scope. Deleting is not a stronger authority than overwriting, because a replacement already leaves nothing of the previous content beyond the version trail a delete takes with it.

A delete is refused while an asset references the file, a prompt attaches it, or a query-engine table is registered over it. Neither of the first two is a foreign key — deleting the file deliberately leaves the row behind so the thing that depended on it reports the material as missing — so nothing in the database stops the delete and the tool does. A knowledge page is not among them: the platform refuses an mcp:resource: citation on a shared page, because a resource is visibility-scoped, so no page can point at one. The refusal counts each kind rather than naming them, because each of those records carries an audience the caller is not necessarily in; the portal's Used-by panel on the file resolves those audiences. The tables are reported as table_registrations, the rows manage_table action=list answers with, because manage_table already names them to the same caller. force: true deletes anyway and drops any table over the file. A resource you cannot see is answered as absent, whether it is missing, deleted, or somebody else's. A managed-script run is judged as the person it acts for: it authenticates as a principal that owns no file, so a create with no scope named files into its version author's library and a replacement reaches what that person uploaded (Script security). See Asset References.