From 37944a0a7f62b6e82db35892cfa480ac7957374d Mon Sep 17 00:00:00 2001
From: duwenxin <duwenxin@google.com>
Date: Thu, 5 Mar 2026 11:49:57 -0500
Subject: [PATCH 1/2] add error doc

---
 DEVELOPER.md | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/DEVELOPER.md b/DEVELOPER.md
index 5055fe9087ee..5d48cc65674a 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -89,6 +89,44 @@ The following guidelines apply to tool types:
   `list-collections`).
 * Changes to tool type are breaking changes and should be avoided.
 
+### Tool Invocation & Error Handling
+
+To align with the Model Context Protocol (MCP) and ensure robust agentic workflows, Toolbox distinguishes between errors the agent can fix and errors that require developer intervention.
+
+#### Error Categorization
+
+When implementing `Invoke()` or `ParseParams()`, you must return the appropriate error type from `internal/util/errors.go`. This allows the LLM to attempt a "self-correct" for Agent Errors while signaling a hard stop for Server Errors.
+
+| Category | Description | HTTP Status | MCP Result |
+|---|---|---|---|
+| **Agent Error** (`ToolCallAgentError`) | Input/Execution logic errors (e.g., SQL syntax, missing records, invalid params). The agent can fix this. | 200 OK | `isError: true` |
+| **Server Error** (`ToolCallServerError`) | Infrastructure failures (e.g., DB down, auth failure, network failure). The agent cannot fix this. | 500 Internal Error | JSON-RPC Error |
+
+#### Implementation Guidelines
+
+**Use Typed Errors**: Refactor or implement the `Tool` interface methods to return `util.ToolboxError`.
+
+**In `Invoke()`:**
+*   **Agent Error**: Wrap database driver errors (syntax, constraint violations) in `AgentError`.
+*   **Server Error**: Wrap connection failures or internal logic crashes in `ClientServerError`.
+
+**In `ParseParams()`:**
+*   Return `ToolboxError` for missing required parameters or wrong types.
+*   Return `ClientServerError` for failures in resolving authenticated parameters (e.g., invalid tokens).
+
+**Example:**
+
+```go
+func (t *MyTool) Invoke(ctx context.Context, params parameters.ParamValues) (any, util.ToolboxError) {
+    res, err := t.db.Exec(ctx, params.SQL)
+    if err != nil {
+        // Driver error is likely a syntax issue the LLM can fix
+        return nil, &util.AgentError{"invalid or missing 'project' parameter; expected a non-empty string", err}
+    }
+    return res, nil
+}
+```
+
 ## Implementation Guides
 
 ### Adding a New Database Source or Tool

From 89ad4acc01c313c163003ada3b716ec8e53a1048 Mon Sep 17 00:00:00 2001
From: Wenxin Du <117315983+duwenxin99@users.noreply.github.com>
Date: Thu, 12 Mar 2026 15:34:05 -0400
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 DEVELOPER.md | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/DEVELOPER.md b/DEVELOPER.md
index 5d48cc65674a..03bb85c6a39a 100644
--- a/DEVELOPER.md
+++ b/DEVELOPER.md
@@ -99,8 +99,8 @@ When implementing `Invoke()` or `ParseParams()`, you must return the appropriate
 
 | Category | Description | HTTP Status | MCP Result |
 |---|---|---|---|
-| **Agent Error** (`ToolCallAgentError`) | Input/Execution logic errors (e.g., SQL syntax, missing records, invalid params). The agent can fix this. | 200 OK | `isError: true` |
-| **Server Error** (`ToolCallServerError`) | Infrastructure failures (e.g., DB down, auth failure, network failure). The agent cannot fix this. | 500 Internal Error | JSON-RPC Error |
+| **Agent Error** (`AgentError`) | Input/Execution logic errors (e.g., SQL syntax, missing records, invalid params). The agent can fix this. | 200 OK | `isError: true` |
+| **Server Error** (`ClientServerError`) | Infrastructure failures (e.g., DB down, auth failure, network failure). The agent cannot fix this. | 500 Internal Error | JSON-RPC Error |
 
 #### Implementation Guidelines
 
@@ -116,16 +116,14 @@ When implementing `Invoke()` or `ParseParams()`, you must return the appropriate
 
 **Example:**
 
-```go
-func (t *MyTool) Invoke(ctx context.Context, params parameters.ParamValues) (any, util.ToolboxError) {
+func (t *MyTool) Invoke(ctx context.Context, sp tools.SourceProvider, params parameters.ParamValues, token tools.AccessToken) (any, util.ToolboxError) {
     res, err := t.db.Exec(ctx, params.SQL)
     if err != nil {
         // Driver error is likely a syntax issue the LLM can fix
-        return nil, &util.AgentError{"invalid or missing 'project' parameter; expected a non-empty string", err}
+        return nil, util.NewAgentError("error executing SQL query", err)
     }
     return res, nil
 }
-```
 
 ## Implementation Guides