docs: document mcp_catalog toolset and reorganize RAG reference

[dgageot]

The built-in toolsets reference had two gaps: mcp_catalog was completely undocumented, and RAG was filed under features instead of tools despite being declared as a toolset via type: rag.

This PR adds comprehensive documentation for mcp_catalog and moves RAG under the tools section where it belongs. The mcp_catalog documentation covers the meta-tools (search_remote_mcp_servers, enable_remote_mcp_server, list_remote_mcp_servers, disable_remote_mcp_server, reset_remote_mcp_server_auth), auth flavors (oauth, api_key, none), lazy-connect behavior, and relevant limitations. Both toolsets are now wired into the built-in tools reference tables and navigation.

Docs-only change; no runtime code modifications.

[docker-agent]

Assessment: 🟡 NEEDS ATTENTION

[docker-agent]

[MEDIUM] Model version in inline example (claude-sonnet-4-5) does not match the linked canonical example (claude-sonnet-4-6)

The inline YAML snippet uses anthropic/claude-sonnet-4-5, but the examples/mcp_catalog.yaml file linked on line 79 as "a complete, runnable configuration" uses anthropic/claude-sonnet-4-6.

A reader comparing the two will see a mismatch. The inline example should be updated to match the canonical file:

model: anthropic/claude-sonnet-4-6

[docker-agent]

Assessment: 🟢 APPROVE

This is a clean, well-executed docs-only PR. The primary changes — moving RAG from /features/rag/ to /tools/rag/, updating all cross-references, adding new mcp_catalog toolset documentation, and updating nav.yml — are consistently applied across all changed files.

No broken links, no dead references, no factual inaccuracies found.

All five meta-tools are correctly named, all three auth flavors are correctly described, and the navigation updates are consistent with the new file locations. The drafter surfaced only low-severity observations (minor wording nuances and nav ordering preferences), none of which rise to the level of bugs or actionable issues.

[aheritier]

Review: docs: document mcp_catalog toolset and reorganize RAG reference

Verdict: ✅ Approve — All CI checks pass. This is a well-executed, accurate docs-only PR that fills a genuine gap (mcp_catalog was undocumented) and fixes a real misclassification (RAG filed under Features instead of Built-in Tools). All technical claims verified against source code in pkg/tools/builtin/mcpcatalog/.

---

✅ What's correct

• All five meta-tool names match the ToolName* constants exactly.
• The disable / reset_remote_mcp_server_auth visibility condition ("After first enable") is accurate — gated by if len(enabled) > 0 in Tools().
• Lazy-connect behavior and OAuth deferral on startup are accurately described and match the code path in Tools() → mcp.IsAuthorizationRequired.
• Auth flavors (oauth / api_key / none) match the Auth.Type values in servers.go.
• "Frozen at build time" is accurate — servers.json is embedded via //go:embed.
• "No prompt discovery" limitation matches the package-level comment in mcpcatalog.go.
• All cross-references to the moved /features/rag/ URL are updated consistently across every affected file (README, nav.yml, concepts/tools, configuration/tools, docs/index.md).
• The new page follows the project's callout conventions, relative URL filters, and Jekyll front matter pattern correctly.

---

⚠️ Observations (non-blocking)

Three inline comments cover the specific line locations. Summary of all findings:

1. search_remote_mcp_servers return-value description is incomplete (inline) — the SearchResult struct also returns title, description, category, tags, and an enabled bool. The enabled field is especially useful so callers can see which servers are already active.

2. Empty-query truncation is undocumented (inline) — handleSearch caps empty queries at 25 of the current 45 servers (emptyQuerySearchLimit = 25). The SearchArgs jsonschema tag even says "Leave empty to list every catalog server", which contradicts the implementation. A one-line note would prevent user confusion.

3. docker-agent in prose should be Docker Agent (inline) — per docs/STYLE.md: "Talking about the product? → 'Docker Agent'". One instance in the Notes section.

4. RAG title drops the acronym expansion — # RAG Tool replaces # RAG (Retrieval-Augmented Generation). Consistent with the other <Name> Tool pages, but removes the only heading-level expansion for readers unfamiliar with the abbreviation. Worth considering # RAG (Retrieval-Augmented Generation) Tool.

5. No redirect for the moved /features/rag/ URL — the site has no jekyll-redirect-from plugin (confirmed in _config.yml). Existing external bookmarks/links will 404. Consider a stub page or adding the plugin.

6. Model discrepancy between the inline example and the linked file — the doc correctly uses anthropic/claude-sonnet-4-5 (per STYLE.md), but the linked examples/mcp_catalog.yaml uses claude-sonnet-4-6. Out of scope for this PR; worth a follow-up.

[aheritier]

Incomplete return-value description. The SearchResult struct (confirmed in source) returns id, title, description, category, tags, auth, url, and an enabled bool — but this description only lists id, auth requirements, and URL. The enabled field is especially actionable for users (shows which servers are already active).

The tool's own Description string in code says: "Returns id, title, description, auth requirements and category for each hit."

Suggested wording: "Case-insensitive fuzzy search over id, title, description, category and tags. Returns id, title, description, category, tags, auth flavour (oauth / api_key / none), URL, and whether the server is currently enabled."

[aheritier]

Empty-query truncation is undocumented. handleSearch caps empty-query results at emptyQuerySearchLimit = 25 (currently 45 servers in the catalog). The SearchArgs jsonschema tag says "Leave empty to list every catalog server" — which contradicts the actual behaviour.

A reader who calls search_remote_mcp_servers with an empty string expecting a full catalog listing will silently get only the first 25 entries. Suggest adding a note here or in the Workflow section, e.g.: "An empty query returns the first 25 servers; use a keyword to see the full matching set."

[aheritier]

Prose naming: docker-agent → Docker Agent. Per docs/STYLE.md: "Talking about the product? → 'Docker Agent'".

Suggested: "…the catalog is embedded in the Docker Agent binary and refreshed with each release."