Compact Mode Guide

Compact mode exposes only 4-5 core tools instead of 1000+ tools, reducing context window usage by ~99% while maintaining full functionality.

What is Compact Mode?

Compact mode is a context window optimization that exposes only 4-5 core discovery tools instead of listing all 1000+ tools. All tools remain accessible through the execute_tool function.

Why Use Compact Mode?

The Problem: AI assistants have limited context windows. Listing 1000+ tools consumes significant context space, leaving less room for:

  • Your research questions

  • Tool outputs and data

  • Conversation history

  • Analysis and reasoning

The Solution: Compact mode exposes only 4-5 discovery tools. The AI uses these to find and execute the specific tools it needs.

Impact:

  • 99% reduction in exposed tools (4-5 vs 1000+)

  • Full functionality - All 1000+ tools still accessible via execute_tool

  • Better AI reasoning - More context available for analysis

  • Faster responses - Less token processing overhead

When to use:

✅ Always recommended for MCP integration with Claude, Cursor, ChatGPT ✅ AI agent workflows with long conversations ✅ Complex multi-step research tasks ✅ Working with large datasets or outputs

When to skip:

❌ Python API usage (context windows don’t apply) ❌ Single-use scripts or batch processing ❌ When you need to see all available tools at once

Core Tools

Compact mode exposes 4 core discovery tools, plus optionally find_tools if search is enabled (default):

  1. ``list_tools`` - List available tools (names, categories, etc.)

  2. ``grep_tools`` - Search tools by text/regex pattern

  3. ``get_tool_info`` - Get tool information (description or full definition)

  4. ``execute_tool`` - Execute any ToolUniverse tool by name

  5. ``find_tools`` - AI-powered tool discovery using natural language queries (optional, enabled by default via search_enabled=True)

Quick Start

Command Line

# STDIO mode (for Claude Desktop)
tooluniverse-smcp-stdio --compact-mode

# HTTP mode
tooluniverse-smcp-server --compact-mode --port 8000

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tooluniverse-compact": {
      "command": "python",
      "args": [
        "-m", "tooluniverse.smcp_server",
        "--transport", "stdio",
        "--compact-mode"
      ],
      "env": {
        "FASTMCP_NO_BANNER": "1",
        "PYTHONWARNINGS": "ignore"
      }
    }
  }
}

Gemini CLI Configuration

Add to ~/.gemini/settings.json or project .gemini/settings.json:

{
  "mcpServers": {
    "tooluniverse": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/tooluniverse-env",
        "run",
        "tooluniverse-smcp-stdio",
        "--compact-mode"
      ]
    }
  }
}

Why Compact Mode for Gemini CLI?

  • 500 tool limit: Gemini CLI has a 500 tool limit per MCP server

  • Minimal context usage: Compact mode exposes only 4-5 tools, well within limits

  • Full functionality: All 1000+ tools still accessible via execute_tool

  • Progressive disclosure: Discover tools on demand using list_tools, grep_tools, and get_tool_info

Note

For Gemini CLI, you can also use the gemini-essential.yaml Space configuration which provides ~400-450 essential tools, staying within the 500 tool limit while providing direct access to commonly used tools. See building_ai_scientists/gemini_cli for details.

Usage

In Claude Desktop, just configure the server and start using tools. Claude will automatically discover and call them.

Typical workflow: 1. Use list_tools(mode="names") to see available tools 2. Use grep_tools(pattern="...") to search for tools 3. Use get_tool_info(tool_names="...") to get details 4. Use execute_tool(tool_name="...", arguments={...}) to execute tools

Comparison

Feature

Normal Mode

Compact Mode

Tools Exposed

~1000 tools

4-5 tools (4 core + find_tools if search enabled)

Context Usage

High

Low (99% reduction)

Functionality

Full

Full (via execute_tool)

When to Use

Use Compact Mode when: - Working with AI agents (Claude Desktop, Gemini CLI, etc.) - Context window is limited - Working with Gemini CLI (500 tool limit) - You want minimal context usage

Use Normal Mode when: - Context window is not a concern - You want direct access to all tools - Working with platforms without tool limits

Alternative for Gemini CLI: - Use gemini-essential.yaml Space configuration for ~400-450 essential tools - Provides direct tool access while staying within 500 tool limit - See building_ai_scientists/gemini_cli for configuration details

Examples

See examples/compact_mode/ for complete examples.