Attention-aware tool filtering for MCP surfaces.

Complex UIs can expose 100+ tools, but LLM tool selection degrades past ~20. FocusLens filters the full tool set to a manageable subset based on which widget has focus.

Modes

• :all -- the first :max_tools tools (default 15), unfiltered
• :focused -- return the session's tools for the focused widget + globals
• :hover -- return the session's tools for the focused widget + the hovered widget + globals

Derived tool names are "session_id.widget_id.action". In :focused and :hover modes a tool belongs to the session when the first . segment of its name is exactly :session_id, and to a widget when the second is exactly the widget ID, so another session's tools for a widget with the same ID never leak in. A session or widget ID never holds a . (Raxol.MCP.TreeWalker.id?/1). A global tool is one with no . in its name (a server-level tool such as raxol_list). With :registry given, the session's "session_id.discover_tools" meta-tool follows the widget tools, so agents can search the session's full set by keyword; without it, the meta-tool is not added. Every mode cuts its result to :max_tools.

Usage

all_tools = TreeWalker.derive_tools(view_tree, context)

# Headless: show everything
FocusLens.filter(all_tools, mode: :all)

# Interactive: show focused + globals
FocusLens.filter(all_tools,
  mode: :focused,
  session_id: "demo",
  focused_id: "search_input"
)

# Mouse tracking: anticipatory tool exposure
FocusLens.filter(all_tools,
  mode: :hover,
  session_id: "demo",
  focused_id: "search_input",
  hover_id: "submit_btn"
)