Why tool count isn't the metric you think for Godot MCP servers

Deep dives · ~6 min read · 19 April 2026

godot-catalyst mcp meta

by Fireal Software · ~6 min read

Every MCP server ad leads with a number. “110 tools.” “169 tools.” Godot Catalyst has 240+. The implicit pitch: more tools means more capability.

That’s half true. The missing half is that every tool you expose to the agent costs context, and context is not free. A server with 240 tools that’s smart about when to show them beats a server with 80 tools that shoves them all into the session on every startup.

What a tool definition actually costs

When an MCP server registers a tool, the client loads the tool’s name, description, and parameter schema into the model’s context on every message. A tool like godot_create_node with its full Zod schema is roughly 150–300 tokens. 240 tools is 40,000–70,000 tokens before the model has seen a single message.

On Claude Code with a 200K context window, that’s 20–35% of your budget spent on tool descriptions. On Copilot Chat with a 32K context, 240 tools is over-budget before you start.

This is why the headline number matters less than you’d think. What matters:

1. Does your client support tool filtering?
2. Can you limit the surface without losing functionality?
3. Does the model know which tool to call without you having to describe all 240 of them?

The four tool modes

Godot Catalyst has a mode gate in src/tools/registry.ts. Set GODOT_TOOL_MODE to one of:

The mode system is hierarchical. Every minimal tool is also in lite and full. The categorization lives in a single TOOL_MODE_MAP record keyed by tool name, plus a shouldRegisterTool() check at registration time. No runtime filtering — tools not in the current mode are never registered, so the client never sees them.

cli is the interesting one. It’s not a subset of the other modes; it’s a sideways track for tools that work without Godot running at all. godot_parse_tscn, godot_docs_search, godot_create_gdscript (template generator) — these are pure TypeScript and run anywhere Node runs. They’re tagged cli in the map, which makes them available in every mode, including pure offline use.

Claude’s Tool Search changes the math

In late 2025 Claude started supporting a pattern called Tool Search — the client can defer tool schemas until they’re needed, based on a short description. Claude sees only the list of tool names up front; when it decides to call one, the full schema loads just-in-time.

The context saving is real. A Godot Catalyst session under Tool Search pays roughly 5% of the full-mode cost up front. A 240-tool server becomes as cheap as a 12-tool server for initial context. The full schemas only materialize when a tool is actually used.

If you’re on Claude Code or another client that supports this, set GODOT_TOOL_MODE=full and stop worrying. The client is doing the filtering for you and the size of the tool catalog is no longer a context-budget problem.

If you’re on a client that doesn’t defer schemas, pick lite or minimal and accept the cap. The minimal mode is designed to be a complete scene-editing surface in 30 tools: create/open/save scenes, CRUD on nodes, CRUD on scripts. You can build a whole game with just those.

What gets dropped at each level

Going from full to lite drops:

• Manipulation 2D/3D helpers (setup_collision2d, create_particles, setup_lighting)
• Animation tools (create_animation, set_keyframe, setup_animation_tree)
• Audio tools (add_audio_bus, add_audio_effect)
• Physics helpers beyond basic collision
• Shader tools
• Theme tools
• Tilemap cell manipulation
• Debug adapter tools
• Batch operations
• Input simulation
• Profiling
• Runtime eval
• Asset search and AI generation
• Spatial analysis
• Convention enforcement
• Visualization
• Testing

Most of these have workarounds: you can edit a shader by calling godot_update_script on a .gdshader file, create a particle system by hand with godot_create_node and godot_set_node_properties, etc. You lose convenience, not capability.

Going from lite to minimal drops resource tools, editor state, project settings, signals (!), build tools, LSP, and file operations. This leaves basic CRUD on scenes, nodes, scripts — enough for a focused task, too narrow for a full session. Use minimal when your client literally cannot handle more than 30 tool definitions.

The practical rule

Pick the smallest mode that fits your client and give the agent the freedom to do its job. For Claude Code with Tool Search: full. For Cursor without Tool Search: lite. For Copilot Chat or a constrained setup: minimal. For CI scripts that parse Godot files without opening the editor: cli.

The 240+ number is there because the surface of the Godot editor is large. Animations, shaders, audio, navigation, physics, localization, networking — each category is a real domain with real tools. Cutting them down uniformly would make the server weaker at its best use case (driving a full project through Claude Code) without helping anyone with a smaller client, because those users can already pick a smaller mode.

Tool count is a feature if you can configure it. A 240-tool server with a minimal mode is strictly better than an 80-tool server with no filtering. More ceiling, same floor.