Skip to content

fix: improve code_execution tool description for AI agents #339

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Dumbris merged 1 commit into from
Mar 11, 2026
Merged

fix: improve code_execution tool description for AI agents #339

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions internal/server/mcp.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -457,12 +457,12 @@ func (p *MCPProxyServer) registerTools(_ bool) {
// code_execution - JavaScript/TypeScript code execution for multi-tool orchestration (feature-flagged)
if p.config.EnableCodeExecution {
codeExecutionTool := mcp.NewTool("code_execution",
mcp.WithDescription("Execute JavaScript or TypeScript code that orchestrates multiple upstream MCP tools in a single request. Use this when you need to combine results from 2+ tools, implement conditional logic, loops, or data transformations that would require multiple round-trips otherwise.\n\n**When to use**: Multi-step workflows with data transformation, conditional logic, error handling, or iterating over results.\n**When NOT to use**: Single tool calls (use call_tool directly), long-running operations (>2 minutes).\n\n**Available in code**:\n- `input` global: Your input data passed via the 'input' parameter\n- `call_tool(serverName, toolName, args)`: Call upstream tools (returns {ok, result} or {ok, error})\n- Modern JavaScript (ES2020+): arrow functions, const/let, template literals, destructuring, classes, for-of, optional chaining (?.), nullish coalescing (??), spread/rest, Promises, Symbols, Map/Set, Proxy/Reflect (no require(), filesystem, or network access)\n\n**TypeScript support**: Set `language: \"typescript\"` to write TypeScript code with type annotations, interfaces, enums, and generics. Types are automatically stripped before execution.\n\n**Security**: Sandboxed execution with timeout enforcement. Respects existing quarantine and server restrictions."),
mcp.WithDescription("Execute JavaScript or TypeScript code that orchestrates multiple upstream MCP tools in a single request. Use this when you need to combine results from 2+ tools, implement conditional logic, loops, or data transformations that would require multiple round-trips otherwise.\n\n**When to use**: Multi-step workflows with data transformation, conditional logic, error handling, or iterating over results.\n**When NOT to use**: Single tool calls (use call_tool directly), long-running operations (>2 minutes).\n\n**Available in code**:\n- `input` global: Your input data passed via the 'input' parameter\n- `call_tool(serverName, toolName, args)`: Call upstream tools (returns {ok, result} or {ok, error})\n- Modern JavaScript (ES2020+): arrow functions, const/let, template literals, destructuring, classes, for-of, optional chaining (?.), nullish coalescing (??), spread/rest, Promises, Symbols, Map/Set, Proxy/Reflect (no require(), filesystem, or network access)\n\n**TypeScript support**: Set `language: \"typescript\"` to write TypeScript code with type annotations, interfaces, enums, and generics. Types are automatically stripped before execution.\n\n**Important runtime rules**:\n- `call_tool` is strictly SYNCHRONOUS. Do not use `await`.\n- Upstream tools usually return an MCP content array. To parse JSON results: `const data = JSON.parse(res.result.content[0].text);`\n- The last evaluated expression in your script is automatically returned as the final output.\n\n**Security**: Sandboxed execution with timeout enforcement. Respects existing quarantine and server restrictions."),
mcp.WithTitleAnnotation("Code Execution"),
mcp.WithDestructiveHintAnnotation(true),
mcp.WithString("code",
mcp.Required(),
mcp.Description("JavaScript or TypeScript source code (ES2020+) to execute. Supports modern syntax: arrow functions, const/let, template literals, destructuring, optional chaining, nullish coalescing. Use `input` to access input data and `call_tool(serverName, toolName, args)` to invoke upstream tools. Return value must be JSON-serializable. Example: `const res = call_tool('github', 'get_user', {username: input.username}); if (!res.ok) throw new Error(res.error.message); ({user: res.result, timestamp: Date.now()})`"),
mcp.Description("JavaScript or TypeScript source code (ES2020+) to execute. Supports modern syntax: arrow functions, const/let, template literals, destructuring, optional chaining, nullish coalescing. Use `input` to access input data and `call_tool(serverName, toolName, args)` to invoke upstream tools. call_tool is SYNCHRONOUS — do not use await. Return value is the last evaluated expression and must be JSON-serializable. Example: `const res = call_tool('github', 'get_user', {username: input.username}); const data = JSON.parse(res.result.content[0].text); ({user: data, timestamp: Date.now()})`"),
),
mcp.WithString("language",
mcp.Description("Source code language. When set to 'typescript', the code is automatically transpiled to JavaScript before execution. Type annotations are stripped, enums and namespaces are converted to JavaScript equivalents. Default: 'javascript'."),
Expand Down
31 changes: 25 additions & 6 deletions internal/server/mcp_routing.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -404,18 +404,37 @@ func (p *MCPProxyServer) buildCodeExecutionTool() []mcpserver.ServerTool {
}

codeExecutionTool := mcp.NewTool("code_execution",
mcp.WithDescription("Execute JavaScript code that orchestrates multiple upstream MCP tools in a single request. "+
"Use when you need to combine results from 2+ tools, implement conditional logic, loops, or data transformations.\n\n"+
"**Available in JavaScript**:\n"+
mcp.WithDescription("Execute JavaScript or TypeScript code that orchestrates multiple upstream MCP tools in a single request. "+
"Use this when you need to combine results from 2+ tools, implement conditional logic, loops, or data transformations "+
"that would require multiple round-trips otherwise.\n\n"+
"**When to use**: Multi-step workflows with data transformation, conditional logic, error handling, or iterating over results.\n"+
"**When NOT to use**: Single tool calls (use call_tool directly), long-running operations (>2 minutes).\n\n"+
"**Available in code**:\n"+
"- `input` global: Your input data passed via the 'input' parameter\n"+
"- `call_tool(serverName, toolName, args)`: Call upstream tools (returns {ok, result} or {ok, error})\n"+
"- ES5.1+ JavaScript (no require(), filesystem, or network access)\n\n"+
"Use `retrieve_tools` to discover available tools, then call them via `call_tool('serverName', 'toolName', {args})`."),
"- Modern JavaScript (ES2020+): arrow functions, const/let, template literals, destructuring, classes, for-of, "+
"optional chaining (?.), nullish coalescing (??), spread/rest, Promises, Symbols, Map/Set, Proxy/Reflect "+
"(no require(), filesystem, or network access)\n\n"+
"**TypeScript support**: Set `language: \"typescript\"` to write TypeScript code with type annotations, interfaces, enums, and generics. "+
"Types are automatically stripped before execution.\n\n"+
"**Important runtime rules**:\n"+
"- `call_tool` is strictly SYNCHRONOUS. Do not use `await`.\n"+
"- Upstream tools usually return an MCP content array. To parse JSON results: `const data = JSON.parse(res.result.content[0].text);`\n"+
"- The last evaluated expression in your script is automatically returned as the final output.\n\n"+
"**Security**: Sandboxed execution with timeout enforcement. Respects existing quarantine and server restrictions."),
mcp.WithTitleAnnotation("Code Execution"),
mcp.WithDestructiveHintAnnotation(true),
mcp.WithString("code",
mcp.Required(),
mcp.Description("JavaScript source code (ES5.1+) to execute. Use `input` to access input data and `call_tool(serverName, toolName, args)` to invoke upstream tools."),
mcp.Description("JavaScript or TypeScript source code (ES2020+) to execute. Supports modern syntax: arrow functions, const/let, template literals, destructuring, "+
"optional chaining, nullish coalescing. Use `input` to access input data and `call_tool(serverName, toolName, args)` to invoke upstream tools. "+
"call_tool is SYNCHRONOUS — do not use await. Return value is the last evaluated expression and must be JSON-serializable. "+
"Example: `const res = call_tool('github', 'get_user', {username: input.username}); const data = JSON.parse(res.result.content[0].text); ({user: data, timestamp: Date.now()})`"),
),
mcp.WithString("language",
mcp.Description("Source code language. When set to 'typescript', the code is automatically transpiled to JavaScript before execution. "+
"Type annotations are stripped, enums and namespaces are converted to JavaScript equivalents. Default: 'javascript'."),
mcp.Enum("javascript", "typescript"),
),
mcp.WithObject("input",
mcp.Description("Input data accessible as global `input` variable in code (default: {})"),
Expand Down
Loading