Implement Progressive Tool Disclosure for dynamic tool discovery

[up-guillaume]

Problem

When agents use search_tools to find relevant tools, the discovered tools are shown in the search results but are NOT available in the LLM's tool context. This creates a "Step-Two Blindspot" where:

1. Agent calls search_tools("docker containers")
2. Search returns mcp_ssh_bridge_ssh_docker_ps (score: 0.717)
3. Agent sees the tool in results but CANNOT call it because it's not in the 80 tools sent to LLM
4. Agent falls back to broken tools (Coolify) or execute_code

Current Workarounds (Insufficient)

• ✅ Marked 43 tools as essential (always included)
• ✅ Increased top_k from 50 to 100
• ✅ Improved tool descriptions with keywords
• ❌ LLM still doesn't choose SSH tools when it should

Proposed Solution: Progressive Tool Disclosure

Implement a system where search_tools can dynamically "unlock" tools for the LLM:

Option 1: Tool Result Injection

When search_tools returns results, inject the top 3-5 tools into the LLM's available tools for the next turn.

Option 2: Two-Step Tool Access

1. First call: search_tools returns tool names + descriptions
2. Second call: unlock_tool(tool_name) adds it to available tools
3. Third call: Agent can now use the unlocked tool

Option 3: Context-Aware Tool Loading

• Load essential tools (always available)
• Load tools based on conversation context (semantic filtering)
• Allow search_tools to temporarily expand the toolset

Benefits

• Solves the "Step-Two Blindspot" identified by Gemini
• More scalable than marking everything as essential
• Reduces context bloat (don't need 817 tools in context)
• Allows agents to discover tools dynamically

Implementation Complexity

Medium-High - Requires changes to:

• search_tools handler in agent_tools.py
• Tool context management in LLM caller
• Possibly tool result format to include "unlock" capability

References

• Anthropic: Building Effective Agents
• Gemini discussion on Progressive Tool Disclosure
• Current issue: LLM chooses Coolify (broken) over SSH MCP (working)

Acceptance Criteria

• Agent can discover tools via search_tools
• Discovered tools become callable in subsequent turns
• No context bloat (tools are loaded on-demand)
• Backward compatible with existing tool system
• Tested with "liste les containers docker" → uses mcp_ssh_bridge_ssh_docker_ps