using-tool-executor

---

name: using-tool-executor description: Use when a task needs capabilities BEYOND basic tools (Read/Grep/Glob/Bash) - semantic search, AI analysis, research, image generation, etc.

Use the right tool for the job:

Basic tools are great for basic tasks. MCP is for capabilities that don't exist in basic tools.

You don't know the exact tool names or schemas. You must discover them.

This is not negotiable. This is not optional. You cannot guess your way through MCP.

The Workflow

EVERY tool-executor interaction follows this sequence:

Copy1. search_tools(query)     → Find relevant tools
2. get_tool_schema(name)   → Get exact parameters
3. execute_code(code)      → Run the tool

Copydigraph tool_flow {
    "Need MCP capability" [shape=doublecircle];
    "Know exact tool name?" [shape=diamond];
    "search_tools(query)" [shape=box];
    "get_tool_schema(name)" [shape=box];
    "execute_code with tool" [shape=box];
    "Handle result" [shape=doublecircle];

    "Need MCP capability" -> "Know exact tool name?";
    "Know exact tool name?" -> "search_tools(query)" [label="NO (99% of cases)"];
    "Know exact tool name?" -> "get_tool_schema(name)" [label="YES (rare)"];
    "search_tools(query)" -> "get_tool_schema(name)";
    "get_tool_schema(name)" -> "execute_code with tool";
    "execute_code with tool" -> "Handle result";
}

Available MCP Categories

Red Flags

When deciding WHETHER to use MCP:

When you ARE using MCP:

Workspace Pattern (CRITICAL)

Large MCP responses are auto-saved to workspace. You receive:

Copy{ _savedTo: "mcp-results/123.json", _preview: "..." }

DO NOT try to Read("mcp-results/123.json") - that path doesn't exist on the filesystem!

DO use execute_code to access it:

Copyconst data = await workspace.readJSON("mcp-results/123.json");
console.log(JSON.stringify(data, null, 2));

Best practice - save your own outputs too:

Copyconst result = await gemini["gemini-deep-research"]({ query: "..." });
// If result has _savedTo, it's already saved
if (result._savedTo) {
  const full = await workspace.readJSON(result._savedTo);
  // Process full data...
  await workspace.writeJSON("my-analysis.json", processedData);
  console.log("Saved to my-analysis.json");  // Minimal console output
}

Quick Reference

Use basic tools for:

• Reading files → Read
• Literal text search → Grep
• Finding files by name → Glob
• Shell commands → Bash
• Simple file edits → Edit

Use MCP for (via search_tools first!):

• "Find where X is defined" → Serena (find_symbol)
• "Rename this function everywhere" → Serena (rename_symbol)
• "What's the API for library Y?" → Context7 (query-docs)
• "Research topic Z thoroughly" → Gemini (gemini-deep-research)
• "Help me brainstorm" → Gemini (gemini-brainstorm)
• "Analyse this code for issues" → Gemini (gemini-analyze-code)
• "Generate an image" → Gemini (gemini-generate-image)
• "Help me reason through this" → Sequential-thinking
• "Build a UI component" → shadcn (search_components)
• "Scrape data from website" → Apify (call-actor)

Checklist

Before ANY tool-executor usage:

• Did I search_tools first? (not guess)
• Did I get_tool_schema? (not assume)
• Am I saving large outputs to workspace? (not console.log)
• Am I using workspace.readJSON for _savedTo? (not Read tool)

The Rule

search_tools → get_tool_schema → execute_code

Every. Single. Time.

No exceptions. No shortcuts. No guessing.