Skip to main content
When your agent is connected to many servers with dozens or hundreds of tools, choosing the right tool for a given task becomes a challenge. Tool Suggestions solve this by providing intelligent, intent-based tool discovery powered by vector similarity search.

​
What it does

When enabled, the Navigator exposes a suggest_tools MCP tool to your agent. Instead of scanning through a long list of tools, your agent describes what it wants to accomplish, and the Navigator returns a ranked list of the most relevant tools across all connected servers. For example, if your agent says “I want to create a new issue”, the Navigator might return:
  1. create_issue from Linear MCP (relevance: 0.94)
  2. create_issue from GitHub MCP (relevance: 0.91)
  3. create_task from Notion MCP (relevance: 0.78)
Your agent can then pick the right tool based on its context and proceed with the call.

​
How to enable

1

Navigate to Navigator Instance settings

Go to the Navigators page, select your navigator, and open the Navigator Instance for your project.
2

Enable Dynamic Suggestions

Toggle Dynamic Suggestions to on. This enables the suggest_tools tool for this Navigator Instance.
When Dynamic Suggestions is enabled, your agent’s MCP tool list includes suggest_tools alongside get_tool_schemas, invoke_tools, and optionally get_context_map.

​
How it works

The tool suggestion system uses RAG (Retrieval-Augmented Generation) with pre-computed vector embeddings:
  1. Embedding generation — when tools are added to a project, Caylex generates vector embeddings from each tool’s name, description, and input schema. These embeddings capture the semantic meaning of what each tool does.
  2. Historical enrichment — as tools are used over time, successful query-tool pairs are embedded and added to the search index. This means the system learns from real usage patterns and improves its recommendations.
  3. Intent matching — when your agent calls suggest_tools with an intent (e.g., “I want to list active incidents”), the Navigator embeds the intent and performs a vector similarity search against all available tools.
  4. Ranked results — tools are ranked by a weighted similarity score that considers:
    • Tool description similarity (primary signal)
    • Historical intent similarity (how similar intents were resolved before)
    • Bootstrap embeddings (initial seeding for new tools)
  5. Adaptive thresholds — if the initial search doesn’t return enough results, the system automatically retries with a lower similarity threshold to capture broader matches.

​
The suggest_tools interface

Your agent calls suggest_tools with a list of intents — each describing a specific action: 
{
  "tool_intents": [
    {
      "intent": "I want to create a new issue",
      "tag": "create_issue",
      "server_names": ["Linear", "GitHub"]
    },
    {
      "intent": "I want to list active incidents",
      "tag": "list_incidents",
      "server_names": ["Linear"]
    }
  ]
}
Each intent includes:
  • intent — a natural language description of the desired action
  • tag — a unique identifier for tracking which tools match which intent
  • server_names — optional filter to limit suggestions to specific servers
The response includes ranked tool recommendations with descriptions, server names, and relevance tags.
Intents should focus on the action, not specific parameter values. Write “I want to create a new issue” instead of “I want to create an issue titled ‘Fix login bug’”.

​
When to enable tool suggestions

ScenarioRecommendation
Agent connects to 3+ servers with many toolsEnable — helps the agent find the right tools efficiently
Agent has a focused set of 5-10 toolsOptional — the agent can manage a small tool set directly
Agent needs to handle diverse, unpredictable user requestsEnable — intent-based discovery handles open-ended queries well
Agent performs a fixed workflow with known toolsDisable — direct tool access is simpler for fixed workflows
When Dynamic Suggestions is disabled, your agent receives the full list of tools directly via the standard MCP tool discovery mechanism. This is the simpler mode and works well for agents with a small, known set of tools.