refactor: update dynamic tools JSON comment format structure

Co-authored-by: aider (anthropic/claude-sonnet-4-5-20250929) <[email protected]>

Author: Slach

CHANGELOG.md

@@ -1,3 +1,7 @@
+# v1.3.3
+IMPROVEMENTS
+- change dynamic tools JSON comment format to `{"name":"tool_name", "description":"tool description", "params": {"param1":"param1 description","param2":"description"}}`
+
 # v1.3.2
 FEATURES
 - support JSON comments for rich dynamic tool descriptions

docs/dynamic_tools.md

@@ -96,9 +96,12 @@ You can provide richer descriptions for both the tool and its parameters by usin
 
 ```json
 {
-  "database.view_name:description": "Main tool description",
-  "param1": "Description for param1",
-  "param2": "Description for param2"
+  "name": "tool_name",
+  "description": "Main tool description",
+  "params": {
+    "param1": "Description for param1",
+    "param2": "Description for param2"
+  }
 }
 ```
 
@@ -107,12 +110,13 @@ Example:
 ```sql
 CREATE VIEW analytics.user_sessions AS
 SELECT ...
-COMMENT '{"analytics.user_sessions:description": "Get user session data", "user_id": "The user ID to filter by", "start_date": "Start of the period"}'
+COMMENT '{"name": "get_user_sessions", "description": "Get user session data", "params": {"user_id": "The user ID to filter by", "start_date": "Start of the period"}}'
 ```
 
-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").
+Notes:
+- The `name` field is optional and will override the auto-generated tool name if provided
+- 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
 

pkg/server/server.go

@@ -637,22 +637,18 @@ func parseComment(comment, db, table string) (string, map[string]string) {
 		return fmt.Sprintf("Tool to load data from %s.%s", db, table), nil
 	}
 
-	var commentMap map[string]string
-	if err := json.Unmarshal([]byte(comment), &commentMap); err == nil {
-		// It is valid JSON
-		descKey := fmt.Sprintf("%s.%s:description", db, table)
-		toolDesc := ""
-		if d, ok := commentMap[descKey]; ok {
-			toolDesc = d
-		} else if d, ok := commentMap["description"]; ok {
-			toolDesc = d
-		}
-
+	// Try to parse as new JSON format
+	var commentStruct struct {
+		Name        string            `json:"name"`
+		Description string            `json:"description"`
+		Params      map[string]string `json:"params"`
+	}
+	if err := json.Unmarshal([]byte(comment), &commentStruct); err == nil {
+		toolDesc := commentStruct.Description
 		if toolDesc == "" {
 			toolDesc = fmt.Sprintf("Tool to load data from %s.%s", db, table)
 		}
-
-		return toolDesc, commentMap
+		return toolDesc, commentStruct.Params
 	}
 
 	// Not JSON, return as is

pkg/server/server_test.go

@@ -1174,23 +1174,30 @@ func TestParseComment(t *testing.T) {
 	require.Equal(t, "Tool to load data from db.view", desc)
 	require.Nil(t, params)
 
-	// JSON with specific key
-	jsonComment := `{"db.view:description": "JSON Desc", "p1": "Param 1 desc"}`
+	// New JSON format with all fields
+	jsonComment := `{"name": "custom_tool", "description": "JSON Desc", "params": {"p1": "Param 1 desc", "p2": "Param 2 desc"}}`
 	desc, params = parseComment(jsonComment, "db", "view")
 	require.Equal(t, "JSON Desc", desc)
 	require.Equal(t, "Param 1 desc", params["p1"])
+	require.Equal(t, "Param 2 desc", params["p2"])
 
-	// JSON with generic description key
-	jsonComment2 := `{"description": "Generic Desc", "p1": "Param 1 desc"}`
+	// New JSON format with only description
+	jsonComment2 := `{"description": "Generic Desc"}`
 	desc, params = parseComment(jsonComment2, "db", "view")
 	require.Equal(t, "Generic Desc", desc)
-	require.Equal(t, "Param 1 desc", params["p1"])
+	require.Nil(t, params)
 
-	// JSON without description
-	jsonComment3 := `{"p1": "Param 1 desc"}`
+	// New JSON format without description
+	jsonComment3 := `{"params": {"p1": "Param 1 desc"}}`
 	desc, params = parseComment(jsonComment3, "db", "view")
 	require.Equal(t, "Tool to load data from db.view", desc)
 	require.Equal(t, "Param 1 desc", params["p1"])
+
+	// New JSON format with name only (name field is ignored in parseComment, used elsewhere)
+	jsonComment4 := `{"name": "my_tool"}`
+	desc, params = parseComment(jsonComment4, "db", "view")
+	require.Equal(t, "Tool to load data from db.view", desc)
+	require.Nil(t, params)
 }
 
 func TestSqlLiteral(t *testing.T) {
@@ -1316,8 +1323,8 @@ func TestDynamicTools_JSONComment(t *testing.T) {
 	defer func() { require.NoError(t, client.Close()) }()
 
 	_, _ = client.ExecuteQuery(ctx, "DROP VIEW IF EXISTS default.v_json")
-	// Escape quotes for SQL
-	comment := `{"default.v_json:description": "Main Desc", "id": "ID Param Desc"}`
+	// Escape quotes for SQL - new JSON format
+	comment := `{"name": "custom_v_json", "description": "Main Desc", "params": {"id": "ID Param Desc"}}`
 	query := fmt.Sprintf("CREATE VIEW default.v_json AS SELECT * FROM default.test WHERE id={id:UInt64} COMMENT '%s'", comment)
 	_, err = client.ExecuteQuery(ctx, query)
 	require.NoError(t, err)
@@ -1666,12 +1673,12 @@ func TestDynamicTool_ParamDescriptionFormat(t *testing.T) {
 	ctx := context.Background()
 	chConfig := setupClickHouseContainer(t)
 
-	// Create view with JSON comment
+	// Create view with JSON comment - new format
 	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"}`
+	comment := `{"params": {"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)