manage_rag agent tool is advertised (TOOL_GROUPS) but never dispatched: do_manage_rag absent from TOOL_HANDLERS and builtin RAG MCP excluded from function schemas

[GothUncc]

Summary

The manage_rag agent tool is advertised to users and to the model, but is not wired into tool dispatch — so agents have no working path to manage the RAG index, and models reliably spiral trying to find one. Confirmed on v1.0.2 (docker) and on current dev HEAD.

What the agent experiences

Asked to "add /app/data/personal_docs/wiki to the RAG index", our agent (Qwen3.6-35B-A3B via an OpenAI-compatible local endpoint) correctly determined it had no RAG management tool, then looped for 10 rounds attempting workarounds (web_fetch against http://localhost:9812/api/v1/rag/..., correctly blocked by the localhost guard) before we interrupted it. Any model will do some version of this, because the tool is advertised but unreachable:

Evidence

1. UI advertises it — static/js/assistant.js TOOL_GROUPS lists manage_rag under Knowledge:
   'Knowledge': ['web_search', 'read_file', 'manage_memory', 'manage_rag', 'search_chats']
2. Handler exists but is orphaned — src/ai_interaction.py defines async def do_manage_rag(...) (list/add_directory/remove_directory), but it is not registered in the TOOL_HANDLERS registry (src/agent_tools/). GitHub code search for manage_rag on dev returns only: mcp_servers/rag_server.py, static/js/assistant.js, static/js/admin.js, src/ai_interaction.py, and two tests — no dispatch/registry site.
3. The MCP route is also closed — src/mcp_manager.py get_function_schemas() intentionally skips built-in Python MCP servers ("Skip builtin Python servers — they use the code-block tool format"), so "Built-in: RAG" registering at startup doesn't expose manage_rag to function calling either. Both paths dead-end.

Possibly related history

#1660 documented real data loss from manage_rag remove_directory (collection double-wipe). If the tool was unwired deliberately in response, then the remaining bug is the leftover surface: TOOL_GROUPS entry, orphaned do_manage_rag, and tests for a tool agents can't call. If it was unwired accidentally (e.g. in the TOOL_HANDLERS registry refactor, #4277), the fix is re-registration.

Suggested fix (either direction)

• If intentional: remove manage_rag from TOOL_GROUPS and delete/annotate do_manage_rag, so agents no longer believe the tool exists and can tell the user to use /rag add instead.
• If accidental: re-register the handler — given manage_rag remove_directory wipes the entire shared RAG collection (agent tool double-wipes it) — data loss #1660, plausibly with only list/add_directory (keep destructive remove_directory human-only via /rag + admin UI).

Environment

• Odysseus v1.0.2, docker compose (main branch), also verified unwired on dev HEAD as of 2026-07-15
• Model backend: llama.cpp llama-server (OpenAI-compatible), Qwen3.6-35B-A3B
• Workaround for other users hitting this: the human-side /rag add <dir> slash command and Admin → Knowledge both work (POST /api/personal/add_directory).