Add enabled tools management to ChatShell and SourceSidebar components. Update API to handle enabled tools in chat requests and adjust prompts accordingly. Enhance tool toggling functionality and improve UI for tool selection.

frontend/components/chat-shell.tsx

@@ -40,6 +40,7 @@ export function ChatShell() {
   const [availableModels, setAvailableModels] = useState<AvailableModel[]>([]);
   const [selectedModel, setSelectedModel] = useState<string>("");
   const [selectedSourceKeys, setSelectedSourceKeys] = useState<string[]>([]);
+  const [enabledToolKeys, setEnabledToolKeys] = useState<string[]>([]);
   const [sourceError, setSourceError] = useState<string | null>(null);
   const [input, setInput] = useState("");
   const [threadId, setThreadId] = useState("");
@@ -99,6 +100,11 @@ export function ChatShell() {
               .map((source) => source.key),
           );
         }
+        setEnabledToolKeys(
+          loadedTools
+            .filter((tool) => tool.kind === "toggle" && tool.active)
+            .map((tool) => tool.key),
+        );
         setSourceError(null);
       } catch (loadError) {
         if (controller.signal.aborted) {
@@ -133,6 +139,11 @@ export function ChatShell() {
           await fetchTools(controller.signal, selectedModel);
         setTools(loadedTools);
         setAvailableModels(models ?? []);
+        setEnabledToolKeys(
+          loadedTools
+            .filter((tool) => tool.kind === "toggle" && tool.active)
+            .map((tool) => tool.key),
+        );
       } catch (loadError) {
         if (controller.signal.aborted) {
           return;
@@ -254,6 +265,7 @@ export function ChatShell() {
       {
         body: {
           sourceKeys: selectedSourceKeys,
+          enabledTools: enabledToolKeys,
           includeReasoning: true,
           threadId,
           model: selectedModel,
@@ -331,6 +343,7 @@ export function ChatShell() {
       {
         body: {
           sourceKeys: selectedSourceKeys,
+          enabledTools: enabledToolKeys,
           includeReasoning: true,
           threadId,
           model: selectedModel,
@@ -360,13 +373,23 @@ export function ChatShell() {
     );
   }
 
+  function toggleTool(toolKey: string) {
+    setEnabledToolKeys((current) =>
+      current.includes(toolKey)
+        ? current.filter((key) => key !== toolKey)
+        : [...current, toolKey],
+    );
+  }
+
   return (
     <main className="min-h-screen p-2 lg:h-screen lg:overflow-hidden">
       <div className="flex min-h-[calc(100vh-1rem)] w-full flex-col gap-2 lg:h-[calc(100vh-1rem)] lg:min-h-0 lg:grid lg:grid-cols-[248px_minmax(0,1fr)]">
         <SourceSidebar
           onNewChat={handleNewChat}
           onToggleSource={toggleSource}
+          onToggleTool={toggleTool}
           selectedSourceKeys={selectedSourceKeys}
+          enabledToolKeys={enabledToolKeys}
           sourceError={sourceError}
           tools={tools}
         />

frontend/components/source-sidebar.tsx

@@ -15,11 +15,13 @@ import {
 } from "lucide-react";
 import {
   useEffect,
+  useLayoutEffect,
   useRef,
   useState,
   type ComponentType,
   type SVGProps,
 } from "react";
+import { createPortal } from "react-dom";
 import type { TutorSource, TutorTool } from "@/lib/api";
 import { COURSE_METADATA } from "@/lib/course-metadata";
 import { DOC_METADATA } from "@/lib/doc-metadata";
@@ -27,25 +29,42 @@ import { DOC_METADATA } from "@/lib/doc-metadata";
 type SourceSidebarProps = {
   onNewChat: () => void;
   onToggleSource: (sourceKey: string) => void;
+  onToggleTool: (toolKey: string) => void;
   selectedSourceKeys: string[];
+  enabledToolKeys: string[];
   sourceError: string | null;
   tools: TutorTool[];
 };
 
 type ToggleToolMeta = {
   icon: ComponentType<SVGProps<SVGSVGElement>>;
+  description?: string;
 };
 
 const TOGGLE_TOOL_META: Record<string, ToggleToolMeta> = {
-  web_search: { icon: Globe },
-  url_context: { icon: LinkIcon },
-  web_fetch: { icon: LinkIcon },
+  web_search: {
+    icon: Globe,
+    description:
+      "Live web search for recent events or facts outside the course corpus.",
+  },
+  url_context: {
+    icon: LinkIcon,
+    description:
+      "Reads a specific URL you paste in the chat so the tutor can answer from its content.",
+  },
+  web_fetch: {
+    icon: LinkIcon,
+    description:
+      "Reads a specific URL you paste in the chat so the tutor can answer from its content.",
+  },
 };
 
 export function SourceSidebar({
   onNewChat,
   onToggleSource,
+  onToggleTool,
   selectedSourceKeys,
+  enabledToolKeys,
   sourceError,
   tools,
 }: SourceSidebarProps) {
@@ -59,8 +78,31 @@ export function SourceSidebar({
   );
   const activeCount =
     (retrievalTool && selectedSourceKeys.length > 0 ? 1 : 0) +
-    toggleTools.filter((tool) => tool.active).length;
+    toggleTools.filter((tool) => enabledToolKeys.includes(tool.key)).length;
   const totalCount = (retrievalTool ? 1 : 0) + toggleTools.length;
+  const [openToolInfoKey, setOpenToolInfoKey] = useState<string | null>(null);
+  const toggleToolsRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (openToolInfoKey === null) return;
+    function onDocMouseDown(event: MouseEvent) {
+      if (
+        toggleToolsRef.current &&
+        !toggleToolsRef.current.contains(event.target as Node)
+      ) {
+        setOpenToolInfoKey(null);
+      }
+    }
+    function onKey(event: KeyboardEvent) {
+      if (event.key === "Escape") setOpenToolInfoKey(null);
+    }
+    document.addEventListener("mousedown", onDocMouseDown);
+    document.addEventListener("keydown", onKey);
+    return () => {
+      document.removeEventListener("mousedown", onDocMouseDown);
+      document.removeEventListener("keydown", onKey);
+    };
+  }, [openToolInfoKey]);
 
   return (
     <aside className="glass-panel relative overflow-hidden rounded-[1.5rem] p-2.5 lg:flex lg:min-h-0 lg:max-h-[calc(100vh-1rem)] lg:min-h-[calc(100vh-1rem)] lg:flex-col">
@@ -106,7 +148,7 @@ export function SourceSidebar({
             </span>
           </div>
           <p className="text-[11px] leading-[1.4] text-[var(--muted)]">
-            Choose which sources the tutor searches.
+            Toggle tools, pick sources.
           </p>
         </div>
 
@@ -118,8 +160,21 @@ export function SourceSidebar({
               onToggleSource={onToggleSource}
             />
           ) : null}
+        </div>
+        <div ref={toggleToolsRef} className="relative z-10 space-y-2 pr-0.5">
           {toggleTools.map((tool) => (
-            <ToggleToolRow key={tool.key} tool={tool} />
+            <ToggleToolRow
+              key={tool.key}
+              tool={tool}
+              enabled={enabledToolKeys.includes(tool.key)}
+              onToggle={() => onToggleTool(tool.key)}
+              infoOpen={openToolInfoKey === tool.key}
+              onInfoToggle={() =>
+                setOpenToolInfoKey((current) =>
+                  current === tool.key ? null : tool.key,
+                )
+              }
+            />
           ))}
         </div>
 
@@ -160,6 +215,7 @@ function RetrievalTool({
   const [isOpen, setIsOpen] = useState(true);
   const courseSources = tool.sources.filter((source) => source.group === "courses");
   const docSources = tool.sources.filter((source) => source.group === "docs");
+  const enabled = selectedSourceKeys.length > 0;
 
   return (
     <section className="space-y-1">
@@ -167,12 +223,34 @@ function RetrievalTool({
         type="button"
         onClick={() => setIsOpen((current) => !current)}
         aria-expanded={isOpen}
-        className="flex w-full items-center gap-2 rounded-[0.75rem] px-2 py-1.5 text-left transition hover:bg-[var(--surface-soft)]"
+        title="Expand to pick sources. On when at least one source is selected."
+        className={clsx(
+          "flex w-full items-center gap-2 rounded-[0.9rem] border px-2 py-2 text-left transition",
+          enabled
+            ? "border-[var(--line-strong)] bg-[var(--accent-faint)] hover:border-[var(--accent)]"
+            : "border-[var(--line)] bg-[var(--surface-subtle)] hover:border-[var(--line-strong)]",
+        )}
       >
-        <Library className="h-3.5 w-3.5 shrink-0 text-[var(--accent)]" />
-        <span className="min-w-0 flex-1 truncate text-[12.5px] font-semibold tracking-[-0.01em] text-[var(--ink)]">
+        <Library
+          className={clsx(
+            "h-3.5 w-3.5 shrink-0",
+            enabled ? "text-[var(--accent)]" : "text-[var(--muted)]",
+          )}
+        />
+        <span className="min-w-0 flex-1 truncate text-[12.5px] font-medium tracking-[-0.01em] text-[var(--ink)]">
           {tool.label}
         </span>
+        <span
+          aria-hidden
+          className={clsx(
+            "inline-flex items-center rounded-full px-1.5 py-0.5 text-[9.5px] font-semibold uppercase tracking-[0.1em]",
+            enabled
+              ? "bg-[var(--accent-faint)] text-[var(--accent)]"
+              : "bg-[var(--muted)]/15 text-[var(--muted)]",
+          )}
+        >
+          {enabled ? "on" : "off"}
+        </span>
         <ChevronDown
           className={clsx(
             "h-3.5 w-3.5 shrink-0 text-[var(--muted)] transition-transform",
@@ -226,10 +304,13 @@ function SourceGroup({
   useEffect(() => {
     if (openPopoverKey === null) return;
     function onDocMouseDown(event: MouseEvent) {
-      if (
-        groupRef.current &&
-        !groupRef.current.contains(event.target as Node)
-      ) {
+      const target = event.target as Node | null;
+      const insideGroup = !!groupRef.current && !!target && groupRef.current.contains(target);
+      const insidePortaledDialog =
+        !!target &&
+        target instanceof Element &&
+        !!target.closest('[data-source-popover="true"]');
+      if (!insideGroup && !insidePortaledDialog) {
         setOpenPopoverKey(null);
       }
     }
@@ -325,9 +406,35 @@ function SourceRow({
 }) {
   const isCourse = source.group === "courses";
   const popover = getPopoverInfo(source);
+  const rowRef = useRef<HTMLDivElement>(null);
+  const [dialogPos, setDialogPos] = useState<
+    { top: number; left: number; width: number } | null
+  >(null);
+
+  useLayoutEffect(() => {
+    if (!popoverOpen || !rowRef.current) {
+      setDialogPos(null);
+      return;
+    }
+    function recompute() {
+      if (!rowRef.current) return;
+      const row = rowRef.current.getBoundingClientRect();
+      const estimatedHeight = 140;
+      const spaceBelow = window.innerHeight - row.bottom;
+      const openAbove = spaceBelow < estimatedHeight + 16 && row.top > spaceBelow;
+      setDialogPos({
+        top: openAbove ? row.top - estimatedHeight - 4 : row.bottom + 4,
+        left: row.left,
+        width: row.width,
+      });
+    }
+    recompute();
+    window.addEventListener("resize", recompute);
+    return () => window.removeEventListener("resize", recompute);
+  }, [popoverOpen]);
 
   return (
-    <div className="relative">
+    <div ref={rowRef} className="relative">
       <div
         className={clsx(
           "flex items-center gap-1 rounded-[0.75rem] border py-1.5 pl-2 pr-1 transition",
@@ -380,61 +487,128 @@ function SourceRow({
           <span className="h-5 w-5 shrink-0" aria-hidden />
         )}
       </div>
-      {popover && popoverOpen ? (
-        <div
-          role="dialog"
-          className="absolute left-0 right-0 top-full z-20 mt-1 rounded-[0.9rem] border border-[var(--line-strong)] bg-[var(--surface-strong)] p-3 shadow-[0_12px_32px_rgba(0,0,0,0.18)] backdrop-blur-md"
-        >
-          <p className="text-[12px] leading-[1.45] text-[var(--ink)]">
-            {popover.description}
-          </p>
-          {popover.meta ? (
-            <p className="mt-1.5 text-[11px] font-medium tracking-[-0.005em] text-[var(--muted)]">
-              {popover.meta}
-            </p>
-          ) : null}
-          <a
-            href={popover.linkUrl}
-            target="_blank"
-            rel="noreferrer"
-            className="mt-2 inline-flex items-center gap-1 text-[11.5px] font-semibold text-[var(--accent)] hover:underline"
-          >
-            {popover.linkLabel}
-            <ExternalLink className="h-3 w-3" />
-          </a>
-        </div>
-      ) : null}
+      {popover && popoverOpen && dialogPos && typeof document !== "undefined"
+        ? createPortal(
+            <div
+              role="dialog"
+              data-source-popover="true"
+              style={{
+                position: "fixed",
+                top: dialogPos.top,
+                left: dialogPos.left,
+                width: dialogPos.width,
+                zIndex: 50,
+              }}
+              className="rounded-[0.9rem] border border-[var(--line-strong)] bg-[var(--surface-strong)] p-3 shadow-[0_12px_32px_rgba(0,0,0,0.18)] backdrop-blur-md"
+            >
+              <p className="text-[12px] leading-[1.45] text-[var(--ink)]">
+                {popover.description}
+              </p>
+              {popover.meta ? (
+                <p className="mt-1.5 text-[11px] font-medium tracking-[-0.005em] text-[var(--muted)]">
+                  {popover.meta}
+                </p>
+              ) : null}
+              <a
+                href={popover.linkUrl}
+                target="_blank"
+                rel="noreferrer"
+                className="mt-2 inline-flex items-center gap-1 text-[11.5px] font-semibold text-[var(--accent)] hover:underline"
+              >
+                {popover.linkLabel}
+                <ExternalLink className="h-3 w-3" />
+              </a>
+            </div>,
+            document.body,
+          )
+        : null}
     </div>
   );
 }
 
 function ToggleToolRow({
   tool,
+  enabled,
+  onToggle,
+  infoOpen,
+  onInfoToggle,
 }: {
   tool: Extract<TutorTool, { kind: "toggle" }>;
+  enabled: boolean;
+  onToggle: () => void;
+  infoOpen: boolean;
+  onInfoToggle: () => void;
 }) {
   const meta = TOGGLE_TOOL_META[tool.key];
   const Icon = meta?.icon ?? Globe;
+  const description = meta?.description;
   return (
-    <div
-      className="flex items-center gap-2 rounded-[0.9rem] border border-[var(--line)] bg-[var(--surface-subtle)] px-2 py-2"
-      title={tool.active ? "Always on for this model" : "Unavailable"}
-    >
-      <Icon className="h-3.5 w-3.5 shrink-0 text-[var(--accent)]" />
-      <span className="min-w-0 flex-1 truncate text-[12.5px] font-medium tracking-[-0.01em] text-[var(--ink)]">
-        {tool.label}
-      </span>
-      <span
-        aria-label={tool.active ? "on" : "off"}
+    <div className="relative">
+      <div
         className={clsx(
-          "inline-flex items-center rounded-full px-1.5 py-0.5 text-[9.5px] font-semibold uppercase tracking-[0.1em]",
-          tool.active
-            ? "bg-[var(--accent-faint)] text-[var(--accent)]"
-            : "bg-[var(--muted)]/15 text-[var(--muted)]",
+          "flex items-center gap-1 rounded-[0.9rem] border pl-2 pr-1 py-2 transition",
+          enabled
+            ? "border-[var(--line-strong)] bg-[var(--accent-faint)]"
+            : "border-[var(--line)] bg-[var(--surface-subtle)]",
         )}
       >
-        {tool.active ? "on" : "off"}
-      </span>
+        <button
+          type="button"
+          onClick={onToggle}
+          aria-pressed={enabled}
+          title={enabled ? "Click to disable" : "Click to enable"}
+          className="flex min-w-0 flex-1 items-center gap-2 text-left"
+        >
+          <Icon
+            className={clsx(
+              "h-3.5 w-3.5 shrink-0",
+              enabled ? "text-[var(--accent)]" : "text-[var(--muted)]",
+            )}
+          />
+          <span className="min-w-0 flex-1 truncate text-[12.5px] font-medium tracking-[-0.01em] text-[var(--ink)]">
+            {tool.label}
+          </span>
+          <span
+            aria-hidden
+            className={clsx(
+              "inline-flex items-center rounded-full px-1.5 py-0.5 text-[9.5px] font-semibold uppercase tracking-[0.1em]",
+              enabled
+                ? "bg-[var(--accent-faint)] text-[var(--accent)]"
+                : "bg-[var(--muted)]/15 text-[var(--muted)]",
+            )}
+          >
+            {enabled ? "on" : "off"}
+          </span>
+        </button>
+        {description ? (
+          <button
+            type="button"
+            onClick={onInfoToggle}
+            aria-label={`About ${tool.label}`}
+            aria-expanded={infoOpen}
+            className={clsx(
+              "flex h-5 w-5 shrink-0 items-center justify-center rounded-full transition",
+              enabled
+                ? "text-[var(--accent)] hover:bg-[var(--accent-soft)]"
+                : "text-[var(--muted)] hover:bg-[var(--surface-hover)] hover:text-[var(--ink)]",
+            )}
+          >
+            <Info className="h-3.5 w-3.5" />
+          </button>
+        ) : (
+          <span className="h-5 w-5 shrink-0" aria-hidden />
+        )}
+      </div>
+      {description && infoOpen ? (
+        <div
+          role="dialog"
+          className="absolute left-0 right-0 bottom-full z-20 mb-1 rounded-[0.9rem] border border-[var(--line-strong)] bg-[var(--surface-strong)] p-3 shadow-[0_12px_32px_rgba(0,0,0,0.18)] backdrop-blur-md"
+        >
+          <p className="text-[12px] leading-[1.45] text-[var(--ink)]">
+            {description}
+          </p>
+        </div>
+      ) : null}
     </div>
   );
 }

scripts/api.py

@@ -45,6 +45,7 @@ class ApiChatRequest(BaseModel):
     history: list[ApiChatTurn] = Field(default_factory=list)
     messages: list[dict[str, Any]] | None = None
     sourceKeys: list[str] | None = None
+    enabledTools: list[str] | None = None
     model: str | None = None
     includeReasoning: bool = True
     threadId: str = ""
@@ -147,13 +148,32 @@ def build_chat_request(payload: ApiChatRequest) -> ChatRequest:
             key for key in requested_source_keys if key in allowed_source_keys
         )
     ) or DEFAULT_SELECTED_SOURCE_KEYS
+    model_name = (payload.model or DEFAULT_MODEL_NAME).strip()
+    if payload.enabledTools is None:
+        enabled_tools = tuple(
+            tool["key"]
+            for tool in _tool_catalog(model_name)
+            if tool["kind"] == "toggle"
+        )
+    else:
+        allowed_tool_keys = {
+            tool["key"]
+            for tool in _tool_catalog(model_name)
+            if tool["kind"] == "toggle"
+        }
+        enabled_tools = tuple(
+            dict.fromkeys(
+                key for key in payload.enabledTools if key in allowed_tool_keys
+            )
+        )
     return ChatRequest(
         query=query,
         history=history,
         source_keys=source_keys,
-        model_name=(payload.model or DEFAULT_MODEL_NAME).strip(),
+        model_name=model_name,
         include_reasoning=bool(payload.includeReasoning),
         thread_id=(payload.threadId or "").strip(),
+        enabled_tools=enabled_tools,
     )
 
 
@@ -378,7 +398,7 @@ def _source_entries() -> list[dict[str, Any]]:
 def _tool_catalog(model_name: str) -> list[dict[str, Any]]:
     retrieval_tool: dict[str, Any] = {
         "key": "retrieval",
-        "label": "Retrieval",
+        "label": "Knowledge base",
         "kind": "configurable",
         "active": True,
         "sources": _source_entries(),

scripts/chat_service.py

@@ -17,7 +17,7 @@ from langgraph.checkpoint.memory import InMemorySaver
 
 from .chat_types import ChatEvent, ChatRequest, ChatTurn, SourceMatch
 from .chroma_rag import LocalChromaRetriever, format_tool_payload, parse_tool_payload
-from .prompts import system_message_openai_agent
+from .prompts import build_system_prompt
 from .setup import (
     DOCUMENT_DICT_PATH,
     SOURCE_KEY_TO_LABEL,
@@ -383,34 +383,44 @@ class GeminiServerSideToolsMiddleware(AgentMiddleware):
         return await handler(self._inject(request))
 
 
-@lru_cache(maxsize=8)
-def build_agent(model_name: str, include_thoughts: bool = False):
+@lru_cache(maxsize=32)
+def build_agent(
+    model_name: str,
+    enabled_tools: tuple[str, ...] = (),
+    include_thoughts: bool = False,
+):
     model = build_chat_model(model_name, include_thoughts=include_thoughts)
     tools: list[Any] = [retrieve_tutor_context]
     middleware: list[AgentMiddleware] = []
+    enabled = set(enabled_tools)
     if is_google_genai_model(model_name):
-        tools.append({"google_search": {}})
-        tools.append({"url_context": {}})
-        middleware.append(GeminiServerSideToolsMiddleware())
+        if "web_search" in enabled:
+            tools.append({"google_search": {}})
+        if "url_context" in enabled:
+            tools.append({"url_context": {}})
+        if enabled & {"web_search", "url_context"}:
+            middleware.append(GeminiServerSideToolsMiddleware())
     elif is_anthropic_model(model_name):
-        tools.append(
-            {
-                "type": "web_search_20250305",
-                "name": "web_search",
-                "allowed_callers": ["direct"],
-            }
-        )
-        tools.append(
-            {
-                "type": "web_fetch_20260209",
-                "name": "web_fetch",
-                "allowed_callers": ["direct"],
-            }
-        )
+        if "web_search" in enabled:
+            tools.append(
+                {
+                    "type": "web_search_20250305",
+                    "name": "web_search",
+                    "allowed_callers": ["direct"],
+                }
+            )
+        if "web_fetch" in enabled:
+            tools.append(
+                {
+                    "type": "web_fetch_20260209",
+                    "name": "web_fetch",
+                    "allowed_callers": ["direct"],
+                }
+            )
     return create_agent(
         model=model,
         tools=tools,
-        system_prompt=system_message_openai_agent,
+        system_prompt=build_system_prompt(model_name, enabled_tools),
         context_schema=AppContext,
         checkpointer=CHECKPOINTER,
         middleware=middleware,
@@ -604,7 +614,11 @@ async def stream_chat(request: ChatRequest) -> AsyncIterator[ChatEvent]:
     google_search_match_count = 0
 
     logfire.info("Running query", query=request.query)
-    agent = build_agent(request.model_name, include_thoughts=include_reasoning)
+    agent = build_agent(
+        request.model_name,
+        enabled_tools=tuple(request.enabled_tools),
+        include_thoughts=include_reasoning,
+    )
     active_thread_id = sync_thread_with_history(
         agent,
         request.thread_id.strip() or new_thread_id(),

scripts/chat_types.py

@@ -28,6 +28,7 @@ class ChatRequest:
     model_name: str = ""
     include_reasoning: bool = False
     thread_id: str = ""
+    enabled_tools: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True, slots=True)

scripts/prompts.py

@@ -1,17 +1,69 @@
-system_message_openai_agent = """You are an AI teacher for applied AI, LLM, RAG, and Python topics.
-
-Your job is to answer student questions clearly and accurately. You have
-three tools available:
-
-- `retrieve_tutor_context` — retrieval over the course and documentation
-  corpus. Use this for anything that depends on course content.
-- `google_search` (Gemini built-in, when available) — live web search for
-  current events, recent library releases, or facts outside the corpus.
-- `url_context` (Gemini built-in, when available) — read a specific URL
-  in depth when the user provides one or when a search result needs to be
-  inspected closely.
-
-## When to use the retrieval tool
+from __future__ import annotations
+
+
+BASE_PROMPT_HEADER = """You are an AI teacher for applied AI, LLM, RAG, and Python topics.
+
+Your job is to answer student questions clearly and accurately."""
+
+RETRIEVAL_TOOL_LINE = (
+    "- `retrieve_tutor_context` — retrieval over the course and documentation\n"
+    "  corpus. Use this for anything that depends on course content."
+)
+
+WEB_TOOL_LINES = {
+    "google-genai": {
+        "web_search": (
+            "- `google_search` (Gemini built-in) — live web search for current\n"
+            "  events, recent library releases, or facts outside the corpus."
+        ),
+        "url_context": (
+            "- `url_context` (Gemini built-in) — read a specific URL in depth when\n"
+            "  the user provides one or when a search result needs to be inspected\n"
+            "  closely."
+        ),
+    },
+    "anthropic": {
+        "web_search": (
+            "- `web_search` (Claude built-in) — live web search for current events,\n"
+            "  recent library releases, or facts outside the corpus."
+        ),
+        "web_fetch": (
+            "- `web_fetch` (Claude built-in) — read a specific URL in depth when the\n"
+            "  user provides one or when a search result needs to be inspected closely."
+        ),
+    },
+}
+
+WEB_USAGE_SECTIONS = {
+    "google-genai": {
+        "web_search": (
+            "USE `google_search` for:\n"
+            "- Questions about recent events, releases, or API changes that may\n"
+            "  post-date the corpus.\n"
+            "- Facts the corpus likely does not cover (product pricing, news, etc.)."
+        ),
+        "url_context": (
+            "USE `url_context` for:\n"
+            "- Any URL the user pastes in their question.\n"
+            "- A search result you need to read in detail to answer accurately."
+        ),
+    },
+    "anthropic": {
+        "web_search": (
+            "USE `web_search` for:\n"
+            "- Questions about recent events, releases, or API changes that may\n"
+            "  post-date the corpus.\n"
+            "- Facts the corpus likely does not cover (product pricing, news, etc.)."
+        ),
+        "web_fetch": (
+            "USE `web_fetch` for:\n"
+            "- Any URL the user pastes in their question.\n"
+            "- A search result you need to read in detail to answer accurately."
+        ),
+    },
+}
+
+RETRIEVAL_USAGE_SECTION = """## When to use the retrieval tool
 
 USE retrieval for:
 - Questions about course content, concepts, code examples, or documentation.
@@ -20,24 +72,9 @@ USE retrieval for:
 DO NOT use retrieval for:
 - Greetings or small talk.
 - Questions about your own role or capabilities in this app (answer directly).
-- Questions you can answer fully from general knowledge with no corpus dependency.
-
-## When to use web search / URL reading
-
-USE `google_search` for:
-- Questions about recent events, releases, or API changes that may post-date
-  the corpus.
-- Facts the corpus likely does not cover (product pricing, news, etc.).
-
-USE `url_context` for:
-- Any URL the user pastes in their question.
-- A search result you need to read in detail to answer accurately.
-
-Prefer `retrieve_tutor_context` first when the question is clearly about
-course material. Combine tools when it helps (e.g. retrieve corpus context,
-then search the web for the latest update).
+- Questions you can answer fully from general knowledge with no corpus dependency."""
 
-## How to call the retrieval tool
+RETRIEVAL_CALL_STRATEGY = """## How to call the retrieval tool
 
 You have two strategies. Pick one per turn:
 
@@ -55,9 +92,9 @@ You have two strategies. Pick one per turn:
    Start with one focused query. If the results are off-topic, too sparse,
    or miss a key aspect of the question, call the tool again with a
    refined query (different keywords, more specific, or targeting the gap).
-   Stop after at most 2 sequential calls.
+   Stop after at most 2 sequential calls."""
 
-## Answering rules
+ANSWERING_RULES = """## Answering rules
 
 - Ground factual claims about the corpus in the retrieved results.
 - If retrieval results are weak or missing, say the topic is not well
@@ -69,5 +106,51 @@ You have two strategies. Pick one per turn:
 - Include complete, runnable code blocks when code is relevant.
 - End with a short invitation for a follow-up question.
 
-The retrieval tool returns JSON with matched passages and source metadata.
-"""
+The retrieval tool returns JSON with matched passages and source metadata."""
+
+
+def _provider_key(model_name: str) -> str:
+    normalized = (model_name or "").strip()
+    if ":" in normalized:
+        return normalized.split(":", 1)[0]
+    if normalized.startswith("gpt-"):
+        return "openai"
+    if normalized.startswith("claude"):
+        return "anthropic"
+    if normalized.startswith("gemini"):
+        return "google-genai"
+    return ""
+
+
+def build_system_prompt(model_name: str, enabled_tools: tuple[str, ...]) -> str:
+    provider = _provider_key(model_name)
+    enabled = set(enabled_tools)
+    tool_lines = [RETRIEVAL_TOOL_LINE]
+    usage_sections: list[str] = []
+    provider_web_tools = WEB_TOOL_LINES.get(provider, {})
+    provider_web_usage = WEB_USAGE_SECTIONS.get(provider, {})
+    for key in ("web_search", "url_context", "web_fetch"):
+        if key in enabled and key in provider_web_tools:
+            tool_lines.append(provider_web_tools[key])
+            usage_sections.append(provider_web_usage[key])
+
+    if len(tool_lines) == 1:
+        intro = "You have one tool available:"
+    else:
+        intro = f"You have {len(tool_lines)} tools available:"
+
+    parts = [
+        BASE_PROMPT_HEADER,
+        f"{intro}\n\n" + "\n".join(tool_lines),
+        RETRIEVAL_USAGE_SECTION,
+    ]
+    if usage_sections:
+        parts.append("## When to use web search / URL reading\n\n" + "\n\n".join(usage_sections))
+        parts.append(
+            "Prefer `retrieve_tutor_context` first when the question is clearly about\n"
+            "course material. Combine tools when it helps (e.g. retrieve corpus\n"
+            "context, then search the web for the latest update)."
+        )
+    parts.append(RETRIEVAL_CALL_STRATEGY)
+    parts.append(ANSWERING_RULES)
+    return "\n\n".join(parts) + "\n"

tests/test_api.py

@@ -48,7 +48,7 @@ class ApiTestCase(unittest.TestCase):
         self.assertIn("web_search", tool_keys)
         self.assertIn("url_context", tool_keys)
 
-    def test_list_tools_for_non_gemini_model(self) -> None:
+    def test_list_tools_for_anthropic_model(self) -> None:
         with TestClient(app) as client:
             response = client.get(
                 "/api/tools", params={"model": "anthropic:claude-sonnet-4-6"}
@@ -57,7 +57,8 @@ class ApiTestCase(unittest.TestCase):
         self.assertEqual(response.status_code, 200)
         tool_keys = {tool["key"] for tool in response.json()["tools"]}
         self.assertIn("retrieval", tool_keys)
-        self.assertNotIn("web_search", tool_keys)
+        self.assertIn("web_search", tool_keys)
+        self.assertIn("web_fetch", tool_keys)
         self.assertNotIn("url_context", tool_keys)
 
     def test_chat_stream_returns_ai_sdk_parts(self) -> None:
@@ -66,6 +67,7 @@ class ApiTestCase(unittest.TestCase):
             self.assertEqual(request.history[0].role, "assistant")
             self.assertEqual(request.history[0].content, "Previous answer")
             self.assertEqual(request.source_keys, ("langchain", "transformers"))
+            self.assertEqual(request.enabled_tools, ("web_search",))
             self.assertEqual(request.thread_id, "thread_0")
             yield ChatEvent("thread_started", {"thread_id": "thread_1"})
             yield ChatEvent("message_started", {"message_id": "message_1"})
@@ -127,6 +129,7 @@ class ApiTestCase(unittest.TestCase):
                 },
             ],
             "sourceKeys": ["langchain", "transformers"],
+            "enabledTools": ["web_search", "not_a_real_tool"],
             "threadId": "thread_0",
         }