Tools API Reference

Complete parameter and response specifications for all mcp-trino tools.

Tool Annotations

All tools declare MCP behavioral annotations that help AI agents understand side effects:

Tool	ReadOnly	Destructive	Idempotent	OpenWorld
trino_query	false	false	false	false
trino_explain	true	—	true	false
trino_browse	true	—	true	false
trino_describe_table	true	—	true	false
trino_list_connections	true	—	true	false

Annotations can be overridden at the toolkit or per-registration level. See Extensibility: Tool Annotations.

Structured Outputs

All tools return typed structured output alongside the human-readable text response. This enables programmatic access to results without parsing text. Output types are documented in each tool's section below.

Each tool advertises an explicit JSON Schema for its structured output. The schemas are open — no top-level required list and no additionalProperties: false — so a host that composes mcp-trino and adds keys to structuredContent still produces results that validate. Schemas can be overridden at the toolkit or per-registration level. See Extensibility: Advertised Output Schemas.

---

trino_query

Execute SQL queries against Trino.

Parameters

Parameter	Type	Required	Default	Constraints	Description
sql	string	Yes	-	Non-empty	SQL query to execute
limit	integer	No	1000	1-10000	Maximum rows to return
format	string	No	json	json, csv, markdown	Output format
timeout_seconds	integer	No	120	1-300	Query timeout
connection	string	No	default	Valid connection name	Server connection

Response

JSON Format:

{
  "columns": ["id", "name", "created_at"],
  "rows": [
    [1, "Alice", "2024-01-15T10:00:00Z"],
    [2, "Bob", "2024-01-15T11:00:00Z"]
  ],
  "row_count": 2,
  "truncated": false
}

CSV Format:

id,name,created_at
1,Alice,2024-01-15T10:00:00Z
2,Bob,2024-01-15T11:00:00Z

Markdown Format:

| id | name | created_at |
|----|------|------------|
| 1 | Alice | 2024-01-15T10:00:00Z |
| 2 | Bob | 2024-01-15T11:00:00Z |

Errors

Code	Message	Cause
INVALID_SQL	SQL query is required	Empty sql parameter
LIMIT_EXCEEDED	Limit exceeds maximum	limit > 10000
TIMEOUT_EXCEEDED	Timeout exceeds maximum	timeout_seconds > 300
QUERY_ERROR	Query execution failed	Trino error
READ_ONLY	Write operation blocked	INSERT/UPDATE/DELETE in read-only mode

Structured Output (QueryOutput)

{
  "columns": [{"name": "id", "type": "bigint"}, {"name": "name", "type": "varchar"}],
  "rows": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}],
  "row_count": 2,
  "stats": {
    "row_count": 2,
    "truncated": false,
    "limit_applied": 1000,
    "duration_ms": 42
  }
}

---

trino_explain

Get query execution plan without running the query.

Parameters

Parameter	Type	Required	Default	Constraints	Description
sql	string	Yes	-	Non-empty	SQL query to explain
type	string	No	LOGICAL	See below	Explain type
connection	string	No	default	Valid connection name	Server connection

Explain Types

Type	Description	Use Case
LOGICAL	Logical query plan	Understand query structure
DISTRIBUTED	Physical execution plan	See worker distribution
IO	I/O statistics estimate	Estimate data scanned
VALIDATE	Syntax validation only	Check without planning

Response

{
  "type": "LOGICAL",
  "plan": "- Output[columnNames = [id, name]] => [[id, name]]\n    - TableScan[table = hive:default:users] => [[id, name]]"
}

Errors

Code	Message	Cause
INVALID_SQL	SQL query is required	Empty sql parameter
INVALID_TYPE	Invalid explain type	Unknown type value
PLAN_ERROR	Failed to generate plan	Invalid SQL syntax

Structured Output (ExplainOutput)

{
  "plan": "- Output[columnNames = [id, name]] => ...",
  "type": "LOGICAL"
}

---

trino_browse

Browse the Trino catalog hierarchy. The browsing level is determined by which parameters are provided.

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	default	Server connection

Modes

Parameters	Action
(none)	List all catalogs
catalog	List schemas in that catalog
catalog + schema	List tables in that schema

Pattern Syntax (tables mode)

Pattern	Matches
order%	Tables starting with "order"
%log	Tables ending with "log"
%event%	Tables containing "event"

Errors

Message	Cause
schema requires catalog	schema provided without catalog
pattern requires both catalog and schema	pattern provided without both catalog and schema

Structured Output (BrowseOutput)

{
  "level": "tables",
  "catalog": "hive",
  "schema": "sales",
  "items": ["customers", "orders", "order_items"],
  "count": 3,
  "pattern": "%order%"
}

The level field indicates which mode was used: "catalogs", "schemas", or "tables".

---

trino_describe_table

Get table structure and optional sample data.

Parameters

Parameter	Type	Required	Default	Description
catalog	string	Yes	-	Catalog name
schema	string	Yes	-	Schema name
table	string	Yes	-	Table name
include_sample	boolean	No	true	Include sample rows
connection	string	No	default	Server connection

Response

{
  "table": "hive.sales.customers",
  "columns": [
    {
      "name": "id",
      "type": "bigint",
      "nullable": false,
      "comment": "Primary key"
    },
    {
      "name": "name",
      "type": "varchar(255)",
      "nullable": true,
      "comment": null
    },
    {
      "name": "email",
      "type": "varchar(255)",
      "nullable": true,
      "comment": "Contact email"
    }
  ],
  "sample": [
    [1, "Alice Smith", "[email protected]"],
    [2, "Bob Jones", "[email protected]"]
  ],
  "sample_count": 2
}

Errors

Code	Message	Cause
CATALOG_REQUIRED	Catalog is required	Empty catalog
SCHEMA_REQUIRED	Schema is required	Empty schema
TABLE_REQUIRED	Table is required	Empty table
TABLE_NOT_FOUND	Table not found	Invalid table name

Structured Output (DescribeTableOutput)

{
  "catalog": "hive",
  "schema": "sales",
  "table": "customers",
  "columns": [
    {"name": "id", "type": "bigint", "nullable": "NO", "comment": "Primary key"},
    {"name": "name", "type": "varchar(255)", "nullable": "YES"},
    {"name": "email", "type": "varchar(255)", "nullable": "YES", "comment": "Contact email"}
  ],
  "column_count": 3
}

---

trino_list_connections

List all configured server connections.

Parameters

None.

Response

{
  "connections": [
    {
      "name": "default",
      "host": "prod.trino.example.com",
      "port": 443,
      "catalog": "hive",
      "ssl": true
    },
    {
      "name": "staging",
      "host": "staging.trino.example.com",
      "port": 443,
      "catalog": "hive",
      "ssl": true
    },
    {
      "name": "dev",
      "host": "localhost",
      "port": 8080,
      "catalog": "memory",
      "ssl": false
    }
  ],
  "default": "default"
}

Structured Output (ListConnectionsOutput)

{
  "connections": [
    {"name": "default", "host": "prod.trino.example.com", "port": 443, "catalog": "hive", "ssl": true, "is_default": true},
    {"name": "staging", "host": "staging.trino.example.com", "port": 443, "catalog": "hive", "ssl": true, "is_default": false}
  ],
  "count": 2
}

---

Common Parameters

connection

All tools accept an optional connection parameter to specify which Trino server to use:

{
  "tool": "trino_query",
  "arguments": {
    "sql": "SELECT * FROM users",
    "connection": "staging"
  }
}

If not specified, the default connection is used.

Error Response Format

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "sql": "SELECT * FROM nonexistent",
      "trino_error_code": 1
    }
  }
}

---

Rate Limits

The toolkit enforces these default limits:

Limit	Default	Maximum	Environment Variable
Rows per query	1000	10000	-
Query timeout	120s	300s	TRINO_TIMEOUT

Override in toolkit configuration:

cfg := tools.Config{
    DefaultLimit:   500,
    MaxLimit:       5000,
    DefaultTimeout: 60 * time.Second,
    MaxTimeout:     180 * time.Second,
}