Compact Mode Guide

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

What is Compact Mode?

When enabled, compact mode exposes only 4-5 essential tools instead of all 750+ tools. All tools are still accessible via execute_tool.

Benefits: - 99% reduction in exposed tools (4-5 vs 750+) - Full functionality maintained - Ideal for AI agents with limited context windows

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 750+ 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 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

~750 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 Gemini CLI for configuration details

Examples

See examples/compact_mode/ for complete examples.