Optimizer Overview

The Optimizer replaces the full tool catalog with two meta-tools -- find_tool and call_tool -- to reduce token consumption and improve LLM tool selection when a server exposes hundreds or thousands of tools.

How It Works

The Problem

When an MCP server aggregates tools from many backends, the list_tools response can contain hundreds of tool definitions. Sending all of them to an LLM in every request:

• Wastes tokens (tool schemas are verbose JSON)
• Confuses the LLM (too many choices leads to worse tool selection)
• Increases latency (larger prompts = slower inference)

The Solution

With the Optimizer enabled, list_tools returns only:

Plus any tools listed in keep_tools (tools the LLM should always see).

The LLM workflow becomes:

1. LLM calls find_tool("send email", limit=3)
2. Argus MCP searches the ToolIndex, returns top 3 matches
3. LLM picks the best match, calls call_tool("gmail.send", {to: ..., body: ...})
4. Argus MCP dispatches to the real backend

Token Savings

The optimized token count is roughly constant regardless of catalog size (2 meta-tool schemas of approximately 600 tokens + keep-list tools).

Search Index

The ToolIndex supports two scoring backends:

TF-IDF + Cosine Similarity (scikit-learn)

When scikit-learn is installed, the index builds a TF-IDF matrix from tool names and descriptions, then computes cosine similarity between the query vector and the document matrix.

Pros: High-quality semantic matching, handles multi-word queries well.

Cons: Requires scikit-learn (~30 MB dependency).

Word-Overlap Fallback

When scikit-learn is not installed, the index falls back to a simple scorer:

• Exact token match: 1.0 weight
• Partial substring match: 0.5 weight
• Contained in document text: 0.25 weight

Normalized by query token count. Good enough for most catalogs.

Configuration

optimizer:
  enabled: true
  keep_tools:
    - essential-tool-1
    - essential-tool-2

When to Enable

Enable the optimizer when:

• Your Argus instance aggregates 100 or more tools across backends
• LLM context cost for tool schemas is high (long prompts = slower, more expensive inference)
• The LLM is making poor tool selections due to too many choices

Do not enable for small catalogs. The two-step find/call pattern adds latency and the meta-tool schemas themselves consume tokens.

The keep_tools list is for tools the LLM must always have access to without needing to search first (e.g., a conversation tool, a help tool).

Meta-Tool Definitions

find_tool

{
  "name": "find_tool",
  "description": "Search across all available tools by keyword or description. Returns the top matching tool definitions with their schemas. Use this first to discover relevant tools before calling them.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query — keywords matching tool names or descriptions."
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of results to return (default: 5).",
        "default": 5
      }
    },
    "required": ["query"]
  }
}

call_tool

{
  "name": "call_tool",
  "description": "Call any tool by its exact name with the given arguments. Use find_tool first to discover the tool name and required arguments.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "The exact name of the tool to call."
      },
      "arguments": {
        "type": "object",
        "description": "Arguments to pass to the tool.",
        "default": {}
      }
    },
    "required": ["name"]
  }
}

TUI Integration

The Operations > Optimizer tab displays:

• Status: Enabled/disabled, tool count, index backend (sklearn or fallback)
• Token Savings: Progress bar showing estimated token reduction
• Meta-Tools: Description of find_tool and call_tool
• Test Search: Input field + results table for testing queries against the index

Implementation Status