feat(mcp): minimal default tool set + on-demand tool_search to reduce startup context cost

[ajdelaguila]

Problem

The data-olympus MCP server exposes a large tool surface (kb_search, kb_get,
kb_list, kb_outline, kb_health, kb_consult, kb_gate_check, kb_propose_edit,
kb_propose_memory, kb_resolve_pending, kb_list_pending, kb_audit,
kb_bootstrap_project, kb_cleanup_plan, kb_compliance, kb_onboarding_status,
kb_record_event, kb_session_recap, ...). Every tool's full JSON schema is sent to the
model at session start, consuming a meaningful slice of the context window before any
work begins. In practice most sessions use only a handful (kb_consult, kb_search,
kb_get). Shipping the whole schema set by default is wasteful and dilutes attention.

Proposal

Send the smallest possible default tool set (only the most-used tools that meet a
strict business need — the fewer the better) and expose everything else on demand via
a discovery tool, so the model knows more capability exists without paying the context
cost up front.

• Default set (loaded at startup): a curated minimal set. Strawman: kb_consult (the
  enforcement gate), kb_search, kb_get, plus the discovery tool below. Exact set is a
  design decision; smaller is better, each inclusion justified against strict need.
• tool_search (new discovery tool): lists/searches ALL available MCP tools and
  returns, per tool, its name, a one-line description, and a "when to use" hint (optional
  keyword filter). The model uses it to learn which additional tools exist and to pull a
  deferred tool's full schema on demand, then invoke it. This mirrors the established
  deferred-tool / gateway pattern (cf. the fastmcp-gateway discover_tools/
  get_tool_schema/execute_tool flow, and Claude Code's own ToolSearch).

Rationale

• Cuts startup context cost substantially (schemas for the long tail of tools deferred).
• No silent hiding: the model is told more tools exist and how to reach them.
• Matches the emerging MCP pattern for large tool surfaces.

Design questions / acceptance criteria

• Minimal default set: decide the exact list and justify each entry against strict
  business need (strawman: kb_consult, kb_search, kb_get, tool_search).
• tool_search contract: returns tool name + short description + when-to-use, with an
  optional keyword filter; returns enough for the model to then fetch a full schema and
  call the tool.
• Deferred-tool invocation: confirm how a deferred tool is loaded/invoked after
  discovery. Investigate what fastmcp (>=3.x, already a dependency) supports for dynamic
  tool exposure / filtering vs. whether we need a generic get_tool_schema + execute
  shim.
• Config knob: e.g. KB_DEFAULT_TOOLS (or similar) so operators/prod can tune the
  default surface without a code change; sensible minimal default.
• Backward compatibility: an opt-out mode that exposes all tools eagerly for clients
  that do not support on-demand discovery.
• Tests: the default surface is exactly the minimal set; tool_search enumerates the
  full set; deferred tools remain discoverable and invokable end-to-end.

Notes

Consider for the next release (0.6.0 / backlog). Pairs naturally with any work on the MCP
serving layer. No behavior change to existing tools — only how they are surfaced.

[ajdelaguila]

Maintainer triage: accepted as a context cost improvement candidate. Keep open for design because default tool set changes affect compatibility and need careful migration.