// Use when a task needs capabilities BEYOND basic tools (Read/Grep/Glob/Bash) - semantic search, AI analysis, research, image generation, etc.
| 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:
| Task | Use This | NOT This |
|---|---|---|
| Read a file | Read tool | MCP |
| Search for literal string | Grep tool | MCP |
| Find files by pattern | Glob tool | MCP |
| Run shell commands | Bash tool | MCP |
| Semantic code search | MCP (Serena) | Grep |
| Refactor/rename symbols | MCP (Serena) | Edit |
| Deep research | MCP (Gemini) | WebSearch |
| AI-powered analysis | MCP (Gemini) | - |
| Generate images/video | MCP (Gemini) | - |
| Library documentation | MCP (Context7) | WebFetch |
| Multi-step reasoning | MCP (Sequential) | - |
Basic tools are great for basic tasks. MCP is for capabilities that don't exist in basic tools.
**When you DO use tool-executor, you MUST follow the workflow.**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.
EVERY tool-executor interaction follows this sequence:
1. search_tools(query) → Find relevant tools
2. get_tool_schema(name) → Get exact parameters
3. execute_code(code) → Run the tool
digraph 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";
}
| Category | Server | Capabilities |
|---|---|---|
| code-nav | Serena (28 tools) | Symbol search, refactoring, code analysis, persistent memory |
| knowledge | Context7, NotebookLM | Library docs lookup, notebook Q&A, research |
| ai-models | Gemini (37 tools) | Deep research, brainstorming, image gen, video gen, structured output |
| reasoning | Sequential-thinking | Multi-step reasoning with thought chains |
| ui | shadcn | Component search, examples, implementation |
| web | Apify | Web scraping, RAG browser, data extraction |
When deciding WHETHER to use MCP:
| Thought | Reality |
|---|---|
| "I'll use Serena to read this file" | Just use Read tool. Serena is for semantic search. |
| "I need MCP to search for 'TODO'" | Grep is fine for literal strings. |
| "Let me use Gemini to check the file" | Read it yourself. Gemini is for analysis/research. |
When you ARE using MCP:
| Thought | Reality |
|---|---|
| "I remember the tool name" | Tool names change. Search first. |
| "I know the schema" | Schemas evolve. Get fresh schema. |
| "Let me just try execute_code" | Without search/schema = guaranteed failure. |
| "I'll console.log the result" | Large outputs truncate. Use workspace. |
| "Let me Read that _savedTo path" | Workspace isn't filesystem. Use workspace.readJSON(). |
| "search_tools is overhead" | search_tools prevents 10x more overhead from failures. |
Large MCP responses are auto-saved to workspace. You receive:
{ _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:
const data = await workspace.readJSON("mcp-results/123.json");
console.log(JSON.stringify(data, null, 2));
Best practice - save your own outputs too:
const 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
}
Use basic tools for:
ReadGrepGlobBashEditUse MCP for (via search_tools first!):
find_symbol)rename_symbol)query-docs)gemini-deep-research)gemini-brainstorm)gemini-analyze-code)gemini-generate-image)search_components)call-actor)Before ANY tool-executor usage:
search_tools → get_tool_schema → execute_code
Every. Single. Time.
No exceptions. No shortcuts. No guessing.
Use this skill when users ask "add MCP server", "remove MCP", "configure tool executor", "add new tool", "environment variables for tool executor", "regenerate registry", or need to modify which MCP servers are available in the sandbox.
Use this skill when users say "tool executor not working", "diagnose tool executor", "check MCP health", "run tool executor tests", "debug search_tools", "execute_code failing", or need to troubleshoot issues with the Tool Executor.
Use this skill when users ask "how does tool executor work", "how to use execute_code", "workspace API", "MCP client examples", "search_tools examples", "context-efficient patterns", or need guidance writing code for the Tool Executor sandbox.