Issue #30 - Enhance tool descriptions with AI agent decision context (#32)

* Issue #30 - Enhance tool descriptions with AI agent decision context

Add decision-making context to MCP tool descriptions so AI agents know
when to use each tool, not just what it does. Remove draft releases from
goreleaser config. Fix prealloc lint issue in multiserver config.

* Issue #30 - Add tool description override API

Add WithDescription() for per-registration overrides and
WithDescriptions() for toolkit-level bulk overrides, with
YAML/JSON config file support for standalone deployments.

Author: cjimti

.goreleaser.yml

@@ -170,7 +170,6 @@ release:
     name: mcp-trino
   name_template: "{{.ProjectName}}-v{{.Version}}"
   prerelease: auto
-  draft: true
   mode: append
   footer: |
     ## Installation

internal/server/server.go

@@ -32,6 +32,10 @@ type Options struct {
 	// ExtensionsConfig configures middleware, interceptors, and transformers.
 	ExtensionsConfig extensions.Config
 
+	// Descriptions provides custom tool descriptions that override defaults.
+	// Keys are tool names (e.g., tools.ToolQuery), values are description strings.
+	Descriptions map[tools.ToolName]string
+
 	// SemanticProvider is an optional semantic metadata provider.
 	// If nil and SEMANTIC_FILE env var is set, a static provider will be created.
 	SemanticProvider semantic.Provider
@@ -85,6 +89,11 @@ func New(opts Options) (*mcp.Server, *multiserver.Manager, error) {
 	// Build toolkit options from extensions configuration
 	toolkitOpts := extensions.BuildToolkitOptions(opts.ExtensionsConfig)
 
+	// Apply description overrides if provided
+	if len(opts.Descriptions) > 0 {
+		toolkitOpts = append(toolkitOpts, tools.WithDescriptions(opts.Descriptions))
+	}
+
 	// If unconfigured, add middleware that returns helpful error for all tools
 	if configErr != nil {
 		toolkitOpts = append(toolkitOpts, tools.WithMiddleware(

internal/server/server_test.go

@@ -258,6 +258,42 @@ func TestNew_MultipleConnections(t *testing.T) {
 	}
 }
 
+func TestDefaultOptions_DescriptionsNil(t *testing.T) {
+	opts := DefaultOptions()
+
+	if opts.Descriptions != nil {
+		t.Error("Descriptions should be nil by default")
+	}
+}
+
+func TestNew_WithDescriptions(t *testing.T) {
+	opts := Options{
+		MultiServerConfig: &multiserver.Config{
+			Default: "default",
+			Primary: client.Config{
+				Host: "localhost",
+				Port: 8080,
+				User: "admin",
+			},
+		},
+		ToolkitConfig: tools.DefaultConfig(),
+		Descriptions: map[tools.ToolName]string{
+			tools.ToolQuery:   "Custom query description",
+			tools.ToolExplain: "Custom explain description",
+		},
+	}
+
+	server, mgr, err := New(opts)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	defer func() { _ = mgr.Close() }()
+
+	if server == nil {
+		t.Error("server should not be nil")
+	}
+}
+
 func TestDefaultOptions_SemanticFields(t *testing.T) {
 	opts := DefaultOptions()
 

pkg/extensions/config_file.go

@@ -71,10 +71,11 @@ type TrinoConfig struct {
 
 // ToolkitConfig maps to tools.Config for file-based loading.
 type ToolkitConfig struct {
-	DefaultLimit   int      `json:"default_limit" yaml:"default_limit"`
-	MaxLimit       int      `json:"max_limit" yaml:"max_limit"`
-	DefaultTimeout Duration `json:"default_timeout" yaml:"default_timeout"`
-	MaxTimeout     Duration `json:"max_timeout" yaml:"max_timeout"`
+	DefaultLimit   int               `json:"default_limit" yaml:"default_limit"`
+	MaxLimit       int               `json:"max_limit" yaml:"max_limit"`
+	DefaultTimeout Duration          `json:"default_timeout" yaml:"default_timeout"`
+	MaxTimeout     Duration          `json:"max_timeout" yaml:"max_timeout"`
+	Descriptions   map[string]string `json:"descriptions,omitempty" yaml:"descriptions,omitempty"`
 }
 
 // ExtFileConfig maps to Config for file-based loading.
@@ -258,6 +259,19 @@ func (c ServerConfig) ToolsConfig() tools.Config {
 	return cfg
 }
 
+// DescriptionsMap converts the Toolkit.Descriptions string map to a tools.ToolName map.
+// Returns nil if no descriptions are configured.
+func (c ServerConfig) DescriptionsMap() map[tools.ToolName]string {
+	if len(c.Toolkit.Descriptions) == 0 {
+		return nil
+	}
+	m := make(map[tools.ToolName]string, len(c.Toolkit.Descriptions))
+	for k, v := range c.Toolkit.Descriptions {
+		m[tools.ToolName(k)] = v
+	}
+	return m
+}
+
 // ExtConfig converts the Extensions section to a Config.
 func (c ServerConfig) ExtConfig() Config {
 	cfg := DefaultConfig()

pkg/extensions/config_file_test.go

@@ -370,6 +370,67 @@ func TestEnvironmentVariableExpansion(t *testing.T) {
 	}
 }
 
+func TestFromBytes_YAML_WithDescriptions(t *testing.T) {
+	yamlConfig := `
+trino:
+  host: trino.example.com
+  user: admin
+
+toolkit:
+  default_limit: 1000
+  descriptions:
+    trino_query: "Query the retail analytics data warehouse."
+    trino_explain: "Check query performance before running."
+`
+
+	cfg, err := FromBytes([]byte(yamlConfig), ".yaml")
+	if err != nil {
+		t.Fatalf("FromBytes failed: %v", err)
+	}
+
+	if len(cfg.Toolkit.Descriptions) != 2 {
+		t.Fatalf("expected 2 descriptions, got %d", len(cfg.Toolkit.Descriptions))
+	}
+	if cfg.Toolkit.Descriptions["trino_query"] != "Query the retail analytics data warehouse." {
+		t.Errorf("unexpected query description: %q", cfg.Toolkit.Descriptions["trino_query"])
+	}
+	if cfg.Toolkit.Descriptions["trino_explain"] != "Check query performance before running." {
+		t.Errorf("unexpected explain description: %q", cfg.Toolkit.Descriptions["trino_explain"])
+	}
+}
+
+func TestDescriptionsMap(t *testing.T) {
+	cfg := ServerConfig{
+		Toolkit: ToolkitConfig{
+			Descriptions: map[string]string{
+				"trino_query":   "Custom query",
+				"trino_explain": "Custom explain",
+			},
+		},
+	}
+
+	m := cfg.DescriptionsMap()
+	if len(m) != 2 {
+		t.Fatalf("expected 2 entries, got %d", len(m))
+	}
+
+	if m["trino_query"] != "Custom query" {
+		t.Errorf("expected 'Custom query', got %q", m["trino_query"])
+	}
+	if m["trino_explain"] != "Custom explain" {
+		t.Errorf("expected 'Custom explain', got %q", m["trino_explain"])
+	}
+}
+
+func TestDescriptionsMap_Empty(t *testing.T) {
+	cfg := ServerConfig{}
+
+	m := cfg.DescriptionsMap()
+	if m != nil {
+		t.Errorf("expected nil for empty descriptions, got %v", m)
+	}
+}
+
 func TestDefaultServerConfig(t *testing.T) {
 	cfg := DefaultServerConfig()
 

pkg/multiserver/config.go

@@ -153,7 +153,8 @@ func (c Config) ClientConfig(name string) (client.Config, error) {
 // ConnectionNames returns the names of all available connections.
 // Always includes the primary connection name as the first entry.
 func (c Config) ConnectionNames() []string {
-	names := []string{c.Default}
+	names := make([]string, 1, 1+len(c.Connections))
+	names[0] = c.Default
 	for name := range c.Connections {
 		names = append(names, name)
 	}

pkg/tools/connections.go

@@ -40,10 +40,8 @@ func (t *Toolkit) registerListConnectionsTool(server *mcp.Server, cfg *toolConfi
 
 	// Register with MCP
 	mcp.AddTool(server, &mcp.Tool{
-		Name: "trino_list_connections",
-		Description: "List all configured Trino server connections. " +
-			"Use this to discover available connections before querying specific servers. " +
-			"Pass the connection name to other tools via the 'connection' parameter.",
+		Name:        string(ToolListConnections),
+		Description: t.getDescription(ToolListConnections, cfg),
 	}, func(ctx context.Context, req *mcp.CallToolRequest, input ListConnectionsInput) (*mcp.CallToolResult, any, error) {
 		return wrappedHandler(ctx, req, input)
 	})

pkg/tools/descriptions.go

@@ -0,0 +1,57 @@
+package tools
+
+// defaultDescriptions holds the default description for each built-in tool.
+// These are used when no override is provided via WithDescription or WithDescriptions.
+var defaultDescriptions = map[ToolName]string{
+	ToolQuery: "Execute a SELECT query against Trino and return results. Use the table path format " +
+		"catalog.schema.table. Results are limited to prevent excessive data transfer — use " +
+		"the limit parameter to control result size. For large tables, always include WHERE " +
+		"clauses to filter results. Consider using trino_explain first for expensive queries.",
+
+	ToolExplain: "Get the execution plan for a SQL query to understand performance characteristics " +
+		"before running expensive queries. Use this when querying large tables (millions of " +
+		"rows) to verify the query plan uses appropriate filters. Also useful for debugging " +
+		"slow queries or understanding join strategies.",
+
+	ToolListCatalogs: "List all available catalogs in the Trino cluster. Catalogs are the top-level " +
+		"containers for schemas and tables.",
+
+	ToolListSchemas: "List all schemas in a catalog. Schemas are containers for tables within a catalog.",
+
+	ToolListTables: "List all tables in a schema. Optionally filter by a LIKE pattern.",
+
+	ToolDescribeTable: "Get detailed table information with columns, types, and optional sample data. " +
+		"Set include_sample=true to see actual data values, which helps understand column " +
+		"meaning and data formats. This is the richest single-call way to understand a " +
+		"table's structure. Requires catalog, schema, and table name — use trino_list_tables " +
+		"to discover available tables if needed.",
+
+	ToolListConnections: "List all configured Trino server connections. " +
+		"Use this to discover available connections before querying specific servers. " +
+		"Pass the connection name to other tools via the 'connection' parameter.",
+}
+
+// DefaultDescription returns the default description for a tool.
+// Returns an empty string for unknown tool names.
+func DefaultDescription(name ToolName) string {
+	return defaultDescriptions[name]
+}
+
+// getDescription resolves the description for a tool using the priority chain:
+// 1. Per-registration override (cfg.description) — highest priority
+// 2. Toolkit-level override (t.descriptions) — medium priority
+// 3. Default description — lowest priority.
+func (t *Toolkit) getDescription(name ToolName, cfg *toolConfig) string {
+	// Per-registration override (highest priority)
+	if cfg != nil && cfg.description != nil {
+		return *cfg.description
+	}
+
+	// Toolkit-level override (medium priority)
+	if desc, ok := t.descriptions[name]; ok {
+		return desc
+	}
+
+	// Default description (lowest priority)
+	return defaultDescriptions[name]
+}

pkg/tools/descriptions_test.go

@@ -0,0 +1,121 @@
+package tools
+
+import "testing"
+
+func TestDefaultDescription(t *testing.T) {
+	tests := []struct {
+		name    ToolName
+		wantNon bool // expect non-empty
+	}{
+		{ToolQuery, true},
+		{ToolExplain, true},
+		{ToolListCatalogs, true},
+		{ToolListSchemas, true},
+		{ToolListTables, true},
+		{ToolDescribeTable, true},
+		{ToolListConnections, true},
+		{ToolName("unknown_tool"), false},
+	}
+
+	for _, tt := range tests {
+		t.Run(string(tt.name), func(t *testing.T) {
+			desc := DefaultDescription(tt.name)
+			if tt.wantNon && desc == "" {
+				t.Errorf("expected non-empty description for %s", tt.name)
+			}
+			if !tt.wantNon && desc != "" {
+				t.Errorf("expected empty description for %s, got %q", tt.name, desc)
+			}
+		})
+	}
+}
+
+func TestDefaultDescriptions_AllToolsCovered(t *testing.T) {
+	for _, name := range AllTools() {
+		if DefaultDescription(name) == "" {
+			t.Errorf("tool %s has no default description", name)
+		}
+	}
+}
+
+func TestGetDescription_Priority(t *testing.T) {
+	tests := []struct {
+		name         string
+		toolkitDescs map[ToolName]string
+		cfgDesc      *string
+		toolName     ToolName
+		wantDesc     string
+	}{
+		{
+			name:         "default only",
+			toolkitDescs: nil,
+			cfgDesc:      nil,
+			toolName:     ToolQuery,
+			wantDesc:     defaultDescriptions[ToolQuery],
+		},
+		{
+			name:         "toolkit override",
+			toolkitDescs: map[ToolName]string{ToolQuery: "Toolkit override"},
+			cfgDesc:      nil,
+			toolName:     ToolQuery,
+			wantDesc:     "Toolkit override",
+		},
+		{
+			name:         "per-registration override",
+			toolkitDescs: nil,
+			cfgDesc:      strPtr("Per-reg override"),
+			toolName:     ToolQuery,
+			wantDesc:     "Per-reg override",
+		},
+		{
+			name:         "per-registration beats toolkit",
+			toolkitDescs: map[ToolName]string{ToolQuery: "Toolkit override"},
+			cfgDesc:      strPtr("Per-reg override"),
+			toolName:     ToolQuery,
+			wantDesc:     "Per-reg override",
+		},
+		{
+			name:         "toolkit override for one tool, default for another",
+			toolkitDescs: map[ToolName]string{ToolQuery: "Custom query desc"},
+			cfgDesc:      nil,
+			toolName:     ToolExplain,
+			wantDesc:     defaultDescriptions[ToolExplain],
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			tk := &Toolkit{
+				descriptions: make(map[ToolName]string),
+			}
+			if tt.toolkitDescs != nil {
+				tk.descriptions = tt.toolkitDescs
+			}
+
+			var cfg *toolConfig
+			if tt.cfgDesc != nil {
+				cfg = &toolConfig{description: tt.cfgDesc}
+			}
+
+			got := tk.getDescription(tt.toolName, cfg)
+			if got != tt.wantDesc {
+				t.Errorf("getDescription() = %q, want %q", got, tt.wantDesc)
+			}
+		})
+	}
+}
+
+func TestGetDescription_NilConfig(t *testing.T) {
+	tk := &Toolkit{
+		descriptions: make(map[ToolName]string),
+	}
+
+	got := tk.getDescription(ToolQuery, nil)
+	if got != defaultDescriptions[ToolQuery] {
+		t.Errorf("expected default description, got %q", got)
+	}
+}
+
+func strPtr(s string) *string {
+	return &s
+}

pkg/tools/explain.go

@@ -40,9 +40,8 @@ func (t *Toolkit) registerExplainTool(server *mcp.Server, cfg *toolConfig) {
 
 	// Register with MCP using typed handler that calls wrapped handler
 	mcp.AddTool(server, &mcp.Tool{
-		Name: "trino_explain",
-		Description: "Get the execution plan for a SQL query. " +
-			"Use this to understand how Trino will execute a query and identify potential performance issues.",
+		Name:        string(ToolExplain),
+		Description: t.getDescription(ToolExplain, cfg),
 	}, func(ctx context.Context, req *mcp.CallToolRequest, input ExplainInput) (*mcp.CallToolResult, any, error) {
 		return wrappedHandler(ctx, req, input)
 	})