feat: append custom description to ClickHouse type in parameter details

Co-authored-by: aider (gemini/gemini-3-pro-preview) <[email protected]>

Author: Slach

docs/dynamic_tools.md

@@ -112,6 +112,8 @@ COMMENT '{"analytics.user_sessions:description": "Get user session data", "user_
 
 If the comment is not valid JSON, it is treated as a plain string description for the tool.
 
+When a parameter description is provided via JSON, it is appended to the ClickHouse type in the tool's parameter description (e.g., "UInt64, The user ID to filter by").
+
 ## Type Mapping
 
 ClickHouse types are automatically mapped to JSON Schema types for the MCP tool interface:

pkg/server/server.go

@@ -549,7 +549,7 @@ func (s *ClickHouseJWEServer) EnsureDynamicTools(ctx context.Context) error {
 		for _, p := range meta.Params {
 			desc := p.CHType
 			if p.Description != "" {
-				desc = p.Description
+				desc = fmt.Sprintf("%s, %s", p.CHType, p.Description)
 			}
 			switch p.JSONType {
 			case "boolean":
@@ -1033,7 +1033,7 @@ func (s *ClickHouseJWEServer) ServeOpenAPISchema(w http.ResponseWriter, r *http.
 				prop["format"] = p.JSONFormat
 			}
 			if p.Description != "" {
-				prop["description"] = p.Description
+				prop["description"] = fmt.Sprintf("%s, %s", p.CHType, p.Description)
 			} else {
 				prop["description"] = p.CHType
 			}

pkg/server/server_test.go

@@ -1661,3 +1661,52 @@ func TestLazyLoading_MCPTools(t *testing.T) {
 	require.True(t, ok)
 	s.dynamicToolsMu.RUnlock()
 }
+
+func TestDynamicTool_ParamDescriptionFormat(t *testing.T) {
+	ctx := context.Background()
+	chConfig := setupClickHouseContainer(t)
+
+	// Create view with JSON comment
+	client, err := clickhouse.NewClient(ctx, *chConfig)
+	require.NoError(t, err)
+	defer func() { require.NoError(t, client.Close()) }()
+	_, _ = client.ExecuteQuery(ctx, "DROP VIEW IF EXISTS default.v_desc")
+	comment := `{"id": "The ID"}`
+	query := fmt.Sprintf("CREATE VIEW default.v_desc AS SELECT * FROM default.test WHERE id={id:UInt64} COMMENT '%s'", comment)
+	_, err = client.ExecuteQuery(ctx, query)
+	require.NoError(t, err)
+
+	cfg := config.Config{
+		ClickHouse: *chConfig,
+		Server: config.ServerConfig{
+			JWE: config.JWEConfig{Enabled: false},
+			DynamicTools: []config.DynamicToolRule{
+				{Regexp: "default\\.v_desc"},
+			},
+		},
+	}
+
+	s := NewClickHouseMCPServer(cfg, "test")
+	err = s.EnsureDynamicTools(ctx)
+	require.NoError(t, err)
+
+	// Verify OpenAPI schema description
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest("GET", "/openapi", nil)
+	s.ServeOpenAPISchema(rr, req)
+
+	var schema map[string]interface{}
+	require.NoError(t, json.Unmarshal(rr.Body.Bytes(), &schema))
+	paths := schema["paths"].(map[string]interface{})
+	path := paths["/{jwe_token}/openapi/default_v_desc"].(map[string]interface{})
+	post := path["post"].(map[string]interface{})
+	reqBody := post["requestBody"].(map[string]interface{})
+	content := reqBody["content"].(map[string]interface{})
+	jsonContent := content["application/json"].(map[string]interface{})
+	schemaObj := jsonContent["schema"].(map[string]interface{})
+	props := schemaObj["properties"].(map[string]interface{})
+	idProp := props["id"].(map[string]interface{})
+
+	// Check that description contains both type and custom description
+	require.Equal(t, "UInt64, The ID", idProp["description"])
+}