Claudikins Tool Executor Guide

The Tool Executor wraps 7 MCP servers into 3 context-efficient tools. Master this workflow to reduce token consumption from ~50k to ~1.1k.

The Three-Tool Workflow

search_tools → get_tool_schema → execute_code

Step 1: Search for Tools

Find relevant tools with semantic search:

const result = await mcp__tool-executor__search_tools({
  query: "generate diagram",
  limit: 5
});
// Returns: { results: [{ name, server, description }], source, has_more }

Search tips:

• Use natural language: "create flowchart", "fetch webpage", "AI reasoning"
• Results are slim - just name, server, one-liner
• Use offset for pagination when has_more is true

Step 2: Get Full Schema

Before calling a tool, get its complete specification:

const schema = await mcp__tool-executor__get_tool_schema({
  name: "gemini_generateContent"
});
// Returns: { name, server, description, inputSchema, example, notes }

Why this step matters:

• inputSchema shows all parameters, types, and required fields
• example shows working code you can adapt
• notes contains gotchas and tips

Step 3: Execute Code

Run TypeScript in the sandbox with pre-connected MCP clients:

const result = await mcp__tool-executor__execute_code({
  code: `
    const response = await gemini.gemini_generateContent({
      prompt: "Create a flowchart description for user authentication"
    });
    console.log("Generated:", response._savedTo || "inline");
  `,
  timeout: 30000
});

Available MCP Clients

All clients are pre-connected and available as globals:

Client Usage Pattern

// All clients use the same pattern:
const result = await clientName.tool_name({ param: value });

// Examples:
await serena.find_symbol({ name_path: "MyClass" });
await gemini.query_gemini({ prompt: "Explain this code" });
await context7.resolve_library_id({ libraryName: "react" });

Workspace API

Persistent file storage scoped to ./workspace/. All paths are protected against traversal.

Text Operations

await workspace.write("notes.txt", "Hello world");
const content = await workspace.read("notes.txt");
await workspace.append("log.txt", "New line\n");
await workspace.delete("temp.txt");

JSON Operations

await workspace.writeJSON("data.json", { key: "value" });
const data = await workspace.readJSON("data.json");

Binary Operations

await workspace.writeBuffer("image.png", buffer);
const buffer = await workspace.readBuffer("image.png");

Directory Operations

const files = await workspace.list("subdir");
const matches = await workspace.glob("**/*.json");
await workspace.mkdir("nested/path");

Metadata

const exists = await workspace.exists("file.txt");
const stats = await workspace.stat("file.txt");
// stats: { size: number, mtime: Date, isDir: boolean }

MCP Results Cleanup

// Clean up auto-saved MCP responses older than 1 hour
const deleted = await workspace.cleanupMcpResults();

Context-Efficient Patterns

Auto-Save for Large Responses

MCP responses over 200 characters are automatically saved to workspace:

const response = await context7.get_library_docs({
  context7CompatibleLibraryID: "/react/react"
});

// If large, response becomes:
// { _savedTo: "mcp-results/1234.json", _size: 5000, _preview: "...", _hint: "..." }

// Read full result when needed:
const full = await workspace.readJSON(response._savedTo);

Console Output Summarisation

Total console output over 500 characters is summarised. Keep logs concise:

// Good - concise logs
console.log("Created 5 files");
console.log("Done");

// Avoid - verbose output that gets truncated
console.log(JSON.stringify(largeObject, null, 2));

Batch Operations

Minimise round-trips by batching work:

// Good - single execution with multiple operations
await mcp__tool-executor__execute_code({
  code: `
    const [lib1, lib2] = await Promise.all([
      context7.resolve_library_id({ libraryName: "react" }),
      context7.resolve_library_id({ libraryName: "vue" })
    ]);
    console.log("Resolved both");
  `
});

Common Patterns

Generate Content with Gemini

const response = await gemini.gemini_generateContent({
  prompt: `Create a detailed flowchart description:
    - User submits request
    - Search for relevant tools
    - Get tool schema
    - Execute code in sandbox
  `
});
await workspace.write("flowchart.md", response.content[0].text);
console.log("Saved flowchart.md");

Search Codebase with Serena

const results = await serena.find_symbol({ name_path: "executeCode" });
console.log("Found:", results.content[0].text);

AI-Assisted Analysis

const code = await workspace.read("analysis-target.ts");
const analysis = await gemini.query_gemini({
  prompt: `Analyse this code for potential issues:\n\n${code}`
});
await workspace.write("analysis.md", analysis.content[0].text);

Error Handling

Errors in execute_code return structured results:

const result = await mcp__tool-executor__execute_code({
  code: `throw new Error("Something broke")`
});
// result: { logs: [...], error: "Something broke", stack: "..." }

Common errors:

• Timeout: Increase timeout parameter or chunk work
• MCP connection failed: Check server is configured, try later
• Path traversal blocked: Workspace paths must stay within ./workspace/

Source Code Reference

For implementation details, see:

• ${CLAUDEPLUGINROOT}/src/sandbox/runtime.ts - Execution engine
• ${CLAUDEPLUGINROOT}/src/sandbox/workspace.ts - Workspace API
• ${CLAUDEPLUGINROOT}/src/sandbox/clients.ts - MCP client management
• ${CLAUDEPLUGINROOT}/src/search.ts - Tool search implementation