perf: update error hint

Author: voocel

errors.go

@@ -103,6 +103,7 @@ type ValidationIssue struct {
 	Path     string
 	Expected string // for IssueType only
 	Received string // for IssueType only
+	Hint     string // optional fix hint, appended to the rendered message
 }
 
 const (
@@ -235,15 +236,22 @@ func formatValidationIssues(toolName string, issues []ValidationIssue) string {
 
 	lines := make([]string, 0, len(issues))
 	for _, it := range issues {
+		var line string
 		switch it.Kind {
 		case IssueMissing:
-			lines = append(lines, fmt.Sprintf("The required parameter `%s` is missing", it.Path))
+			line = fmt.Sprintf("The required parameter `%s` is missing", it.Path)
 		case IssueType:
-			lines = append(lines, fmt.Sprintf(
+			line = fmt.Sprintf(
 				"The parameter `%s` type is expected as `%s` but provided as `%s`",
 				it.Path, it.Expected, it.Received,
-			))
+			)
+		default:
+			continue
 		}
+		if it.Hint != "" {
+			line += ". " + it.Hint
+		}
+		lines = append(lines, line)
 	}
 
 	noun := "issue"

go.mod

@@ -3,6 +3,6 @@ module github.com/voocel/agentcore
 go 1.25.0
 
 require (
-	github.com/voocel/litellm v1.6.12
+	github.com/voocel/litellm v1.6.13
 	golang.org/x/image v0.41.0
 )

go.sum

@@ -1,4 +1,4 @@
-github.com/voocel/litellm v1.6.12 h1:C/JP/F6wKtN6t9c23CGIX9sSAQMKs4UCuUz3jd/mxsA=
-github.com/voocel/litellm v1.6.12/go.mod h1:6MBUu3I4DHm7h72Vl+3nqLruSwYmgqMf/I9BGoordJ4=
+github.com/voocel/litellm v1.6.13 h1:lig/RSTbZZBquatPCbO1G0WGEaQ1pt+Ra7sAVCG0QuA=
+github.com/voocel/litellm v1.6.13/go.mod h1:6MBUu3I4DHm7h72Vl+3nqLruSwYmgqMf/I9BGoordJ4=
 golang.org/x/image v0.41.0 h1:8wS72eGJMJaBxK6okTzd4WaXumUlTVlb753MlsSvTCo=
 golang.org/x/image v0.41.0/go.mod h1:uIc348UZMSvS5Z65CVZ7iDPaNobNFEPeJ4kbqTOszmA=

loop.go

@@ -1149,12 +1149,13 @@ func validateToolArgs(tool Tool, call ToolCall) error {
 			if expectedType == "" {
 				continue
 			}
-			if received, mismatch := typeMismatch(val, expectedType); mismatch {
+			if received, hint, mismatch := typeMismatch(val, expectedType); mismatch {
 				issues = append(issues, ValidationIssue{
 					Kind:     IssueType,
 					Path:     key,
 					Expected: expectedType,
 					Received: received,
+					Hint:     hint,
 				})
 			}
 		}
@@ -1168,37 +1169,62 @@ func validateToolArgs(tool Tool, call ToolCall) error {
 
 // typeMismatch reports whether val conflicts with the JSON Schema type. When it
 // does, the returned name is the user-facing JSON type name of the actual value
-// ("string" / "integer" / "number" / "boolean" / "array" / "object").
-func typeMismatch(val any, expected string) (string, bool) {
+// ("string" / "integer" / "number" / "boolean" / "array" / "object"). The hint
+// is non-empty only for known LLM mistake patterns — currently the
+// "JSON-encoded literal passed as a string" mistake that weaker models repeat
+// across turns without nudging.
+func typeMismatch(val any, expected string) (received string, hint string, mismatch bool) {
 	switch expected {
 	case "string":
 		if _, ok := val.(string); ok {
-			return "", false
+			return "", "", false
 		}
 	case "integer":
 		if f, ok := val.(float64); ok && f == float64(int64(f)) {
-			return "", false
+			return "", "", false
 		}
 	case "number":
 		if _, ok := val.(float64); ok {
-			return "", false
+			return "", "", false
 		}
 	case "boolean":
 		if _, ok := val.(bool); ok {
-			return "", false
+			return "", "", false
 		}
 	case "array":
 		if _, ok := val.([]any); ok {
-			return "", false
+			return "", "", false
 		}
 	case "object":
 		if _, ok := val.(map[string]any); ok {
-			return "", false
+			return "", "", false
 		}
 	default:
-		return "", false
+		return "", "", false
 	}
-	return jsonTypeName(val), true
+	return jsonTypeName(val), mismatchHint(val, expected), true
+}
+
+// mismatchHint catches the single most common LLM mistake: serializing an
+// array/object to a JSON string and passing the string. The hint nudges the
+// model to drop the surrounding quotes on the next turn. Other mismatches get
+// no hint to keep the error message terse.
+func mismatchHint(val any, expected string) string {
+	if expected != "array" && expected != "object" {
+		return ""
+	}
+	s, ok := val.(string)
+	if !ok {
+		return ""
+	}
+	trimmed := strings.TrimSpace(s)
+	if expected == "array" && strings.HasPrefix(trimmed, "[") {
+		return `Looks like a JSON-encoded array — pass the value directly (e.g. ["a","b"]), not wrapped in quotes.`
+	}
+	if expected == "object" && strings.HasPrefix(trimmed, "{") {
+		return `Looks like a JSON-encoded object — pass the value directly (e.g. {"k":"v"}), not wrapped in quotes.`
+	}
+	return ""
 }
 
 // jsonTypeName returns the JSON Schema type name for val.