mcp-trino-v0.4.0

Summary

This release adds customizable tool descriptions — a new API that lets consumers override the descriptions AI agents see for each tool. It also ships enhanced default descriptions with AI agent decision context, so agents make better tool selection choices out of the box.

New Features

Tool Description Override API

Tool descriptions were previously hardcoded. Now they can be customized at three levels, with a clear priority chain (highest wins):

1. Per-registration WithDescription() via RegisterWith()
2. Toolkit-level WithDescriptions() via NewToolkit()
3. Default built-in description

Library usage — bulk override:

toolkit := tools.NewToolkit(client, cfg,
    tools.WithDescriptions(map[tools.ToolName]string{
        tools.ToolQuery:   "Query the retail analytics warehouse",
        tools.ToolExplain: "Check query performance before running",
    }),
)

Library usage — per-registration override:

toolkit.RegisterWith(server, tools.ToolQuery,
    tools.WithDescription("Query the retail analytics warehouse"),
)

Config file (YAML/JSON):

toolkit:
  descriptions:
    trino_query: "Query the retail analytics data warehouse."
    trino_explain: "Check query performance before running."

Standalone server:

opts := server.Options{
    Descriptions: map[tools.ToolName]string{
        tools.ToolQuery: "Custom description",
    },
}

Read defaults programmatically:

desc := tools.DefaultDescription(tools.ToolQuery)

Enhanced Default Tool Descriptions

Production feedback from AI agents revealed that tool descriptions described what each tool does but not when to use it. The trino_explain tool was never used because nothing in the description triggered agents to consider checking query plans.

Updated descriptions for three tools:

• trino_query — Now includes catalog.schema.table path format guidance, limit parameter awareness, WHERE clause advice for large tables, and a nudge toward trino_explain for expensive queries
• trino_explain — Now provides concrete triggers: large tables (millions of rows), filter verification, slow query debugging, and join strategy analysis
• trino_describe_table — Now highlights include_sample=true for understanding data formats, positions it as the richest single-call for table structure, and cross-references trino_list_tables for discovery

Documentation

New documentation across all relevant guides:

• README — New "Customizing Tool Descriptions" section with library, config file, and programmatic examples
• Library Quickstart — New step showing description customization early in the composition walkthrough
• Extensibility Guide — New "Tool Description Overrides" section covering all override patterns
• Tools API Reference — New "Description Overrides" section with priority chain documentation
• Server Configuration — Updated YAML example with descriptions field

Dependency Updates

• github.com/modelcontextprotocol/go-sdk — Updated to latest
• github/codeql-action — Bumped in CI
• GitHub Actions group — Bumped in CI

Other Changes

• .goreleaser.yml — Removed draft: true so releases publish directly
• pkg/multiserver/config.go — Fixed prealloc lint issue in ConnectionNames()

Installation

Claude Desktop (macOS/Windows)

Download the .mcpb bundle for your platform and double-click to install:

• macOS Apple Silicon (M1/M2/M3/M4): mcp-trino_0.4.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.4.0_darwin_amd64.mcpb
• Windows: mcp-trino_0.4.0_windows_amd64.mcpb

Homebrew (macOS)

brew install txn2/tap/mcp-trino

Claude Code CLI

claude mcp add trino \
  -e TRINO_HOST=your-trino-host \
  -e TRINO_USER=your-user \
  -- mcp-trino

Docker

docker pull ghcr.io/txn2/mcp-trino:v0.4.0

Go Library

go get github.com/txn2/mcp-trino@v0.4.0

Verification

All release artifacts are signed with Cosign and include SLSA Level 3 provenance. Verify with:

cosign verify-blob --bundle mcp-trino_0.4.0_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.4.0_linux_amd64.tar.gz