diff --git a/common/llm_services/base_llm.py b/common/llm_services/base_llm.py
index fe77ac1..38022ac 100644
--- a/common/llm_services/base_llm.py
+++ b/common/llm_services/base_llm.py
@@ -1013,7 +1013,7 @@ def select_retriever_prompt(self):
     _AGENTIC_AGENT_SYSTEM = """\
 You are a GraphRAG agent answering questions over a TigerGraph knowledge graph.
 
-You have a set of read-only tools (graph schema via graphrag__get_schema, structural query generation, several unstructured retrievers, raw GSQL via tg_run_query, neighbor expansion). The graph schema is NOT pre-loaded — fetch it with graphrag__get_schema when you need it.
+You have a set of read-only tools (graph schema via graphrag__get_schema, registered installed GSQL tools named graphrag__gsql__* when present, structural query generation, several unstructured retrievers, raw GSQL via tg_run_query, neighbor expansion). The graph schema is NOT pre-loaded — fetch it with graphrag__get_schema when you need it for structural or unstructured retrieval. Registered GSQL tools do not need the schema first.
 
 REASON, ACT, OBSERVE — repeat until you can give a complete, well-grounded answer.
 
@@ -1038,7 +1038,11 @@ def select_retriever_prompt(self):
     # Operator-customizable retrieval strategy for the react agent: the first
     # action, then each next action driven by what the previous result returned.
     _AGENTIC_AGENT_USER_DEFAULT = """\
-- For most questions, make your FIRST action a vector search (graphrag__hybrid_search or graphrag__contextual_search) — it gives the broadest grounding. Skip it only when you are highly confident the question is a pure structured-data request (an exact count, an attribute/id lookup, a relationship traversal, or an aggregation over typed graph data) that a generated graph query fully answers on its own.
+- Before calling any retrieval tool, check whether the question is self-contained: can it be fully understood without reading ## Conversation? If the subject, entity, or topic is not named explicitly in the question, look up the most recent relevant entity from ## Conversation and substitute its full name into every retrieval call. If ## Conversation contains multiple candidates and it is genuinely unclear which one the user means, ask one short clarifying question instead of guessing — do not call any retrieval tool until clarified.
+- When calling an unstructured retriever (hybrid, contextual, similarity, community), pass only the sub-question for that specific part as a standalone search query in the user's language. Do not pass the full multi-part question, a part already covered by another step, or an unresolved reference from conversation history.
+- If a graphrag__gsql__* tool is available and its description matches the question, you may call it. If none match, ignore those tools. Do not call a list/register tool first, and do not call a gsql tool first unless its description matches.
+- A description match on one clause is enough to call the GSQL tool. If the question has other parts that still need passages or typed graph facts, call hybrid/community/structural for those parts too — do not stop after the GSQL tool.
+- For most other questions, make your FIRST action a vector search (graphrag__hybrid_search or graphrag__contextual_search) — it gives the broadest grounding. Skip it only when you are highly confident the question is a pure structured-data request (an exact count, an attribute/id lookup, a relationship traversal, an aggregation over typed graph data, or a matching graphrag__gsql__* tool) that a graph query fully answers on its own.
 - Let each observation drive the next action: if the passages you got back name specific entities or relationships you still need hard facts about, follow up with a structural query; if a result is thin, empty, or off-target, widen its parameters (top_k, num_hops) or switch method rather than repeating the same call.
 - Before answering, check that every part of the question is covered with the specific facts and figures it asks for; if a required value, table, or entity is still missing, retrieve again (widen top_k / num_hops or switch method) rather than answering vaguely or partially.
 - For a specific value, row, total, ranking, or year-over-year comparison, use graphrag__hybrid_search or graphrag__contextual_search with top_k >= 10 (they return atomic table chunks that keep full row/column structure), and quote the exact label, column, year, or unit from the question so the retriever can match it."""
@@ -1067,13 +1071,15 @@ def agentic_agent_prompt(self):
 
 The graph schema is NOT provided here — the structural and unstructured query tools load it themselves at run time, so plan retrieval steps directly. A question that needs no graph data should not include any graph-retrieval step (plan only the final answer step, or the relevant non-graph tool).
 
-You have two kinds of retrieval:
+You have three kinds of retrieval:
+- INSTALLED (graphrag__gsql__*): a user-registered installed GSQL query. Use it only when that tool's description matches the question. Do not call one just because it is listed, and do not call a lookup/list tool first.
 - STRUCTURAL (graphrag__structural_retrieve): generates and runs a graph query. Best for counts, lookups by attribute/id, relationships, and aggregations over typed data. It depends on the LLM generating a correct query against the live schema — it can return nothing or the wrong rows when the question doesn't map cleanly to typed graph data, so it is NOT a safe sole source of context.
 - UNSTRUCTURED (graphrag__hybrid_search / similarity_search / contextual_search / community_search): vector search over document text. Best for "what/why/how/describe/summarize" questions answered from passages. community_search suits broad/overall questions.
 
 Plan mechanics (fixed):
 - A later step may depend on an earlier one: set depends_on and use arg_bindings to pull a value from a prior step's result, e.g. {"question": "S1.context.result"}.
 - Retrieval params (top_k, num_hops, community_level) are optional; omit them to use defaults, or set higher values when you expect a broad answer.
+- For each unstructured step, set args.question to a natural-language question covering that clause only, in the user's language — phrase it the way a person would ask it, not as a keyword list. Do not include the full multi-part question, any topic or term that belongs to a clause already assigned to another step (INSTALLED, STRUCTURAL, or a prior unstructured step), or an unresolved reference from conversation history.
 - The final step MUST have kind="answer" and tool="" (the orchestrator synthesizes the answer from gathered context); it should depend_on all retrieval steps.
 
 Decide which retrievals to include, how many, and in what order using the "Retrieval Strategy" below. Return ONLY the structured plan.
@@ -1088,8 +1094,14 @@ def agentic_agent_prompt(self):
     # Strategy (operator-customizable) — moved out of the fixed rules so it can
     # be tuned without touching the role / act model / plan mechanics.
     _AGENTIC_PLANNER_USER_DEFAULT = """\
-- Prioritize including at least one vector search step (graphrag__hybrid_search or graphrag__contextual_search) unless you are highly confident the question is a pure structured-data request — an exact count, an attribute/id lookup, a relationship traversal, or an aggregation over typed graph data — that a generated graph query fully answers on its own. Whenever the answer could plausibly live in document text (what/why/how/describe/summarize, definitions, explanations, figures), include a vector search step. When unsure, include vector search.
-- Use BOTH kinds when a question needs facts from the graph AND supporting text; you may run several of each, in any order. When you use STRUCTURAL, pair it with a vector search step unless the question is a pure structured-data request.
+- Before building the plan, check whether the question is self-contained: can it be fully understood without reading ## Conversation? If the subject, entity, or topic is not named explicitly in the question, find the most recent relevant entity from ## Conversation and substitute its full name in every step's args. If ## Conversation has multiple candidates and it is genuinely unclear which one the user means, plan only a final answer step (no retrieval) that asks the user one short clarifying question.
+- When a question has multiple clauses, assign each clause to its own retrieval step. If another clause still needs passages or typed graph facts after one is covered, plan hybrid/community/structural for that clause too.
+- If a graphrag__gsql__* tool is in the catalog and its description matches the question, include that tool. If none match, ignore them and plan hybrid/community/structural exactly as today. Do not call a list/register tool; do not call a gsql tool first unless its description matches.
+- If the entire question is fully answered by a matching graphrag__gsql__* tool, plan ONLY that tool + the answer step — do not add any vector search step.
+- You may pair a graphrag__gsql__* tool with a vector search step only when the question has a separate clause that requires document passages beyond what the GSQL tool returns.
+- A description match on one clause is enough. If another clause still needs passages or typed graph facts, plan hybrid/community/structural for that clause too.
+- Prioritize including at least one vector search step (graphrag__hybrid_search or graphrag__contextual_search) unless the question is fully answered by a matching graphrag__gsql__* tool or is a pure structured-data request (an exact count, an attribute/id lookup, a relationship traversal, or an aggregation over typed graph data). Whenever the answer could plausibly live in document text (what/why/how/describe/summarize, definitions, explanations, figures), include a vector search step. When unsure, include vector search.
+- Use BOTH structural and unstructured kinds when a question needs facts from the graph AND supporting text; you may run several of each, in any order. When you use STRUCTURAL, pair it with a vector search step unless the question is a pure structured-data request.
 - Prefer the smallest plan that will work. Trivial/greeting questions need only the final answer step.
 - Tabular / numeric questions (a specific value, a row, a column total, a ranking, or a year-over-year comparison from a table or chart): prefer graphrag__contextual_search or graphrag__hybrid_search with top_k>=10 (these return atomic table chunks that preserve full row/column structure); avoid graphrag__similarity_search alone; quote any specific table label, column header, year, or unit from the question (e.g. "ROE 2023"); for "compare X across years/regions/categories" set top_k>=15."""
 
@@ -1200,6 +1212,7 @@ def hyde_prompt(self):
 - **Quote exact values from the source.** Numbers, units, time periods, and named entities must appear verbatim — do not round, approximate, or translate units. Keep units in their original format, script, and language. For example, if the source says `1,234 km`, write `1,234 km`, not `767 miles` or `about 1,200 km`.
 - **For comparison or "which is the highest" questions, list each candidate's value before stating the conclusion.** Show the working — do not jump directly to a one-line answer.
 - **Score** each context for relevance and use only the high-scoring ones; do not invent additional logic.
+- **Multi-part questions:** answer each part from its matching context. Use structured-query results for typed graph facts; use document passages for "what does the report/document say." Do not quote a structured note as what a named report says. If retrieved passages are off-topic for a part, say that part is not in the retrieved documents.
 - **Cover** the relevant information, especially image references that carry critical visual information.
 - **Format** the answer in Markdown — titles, paragraphs, bulleted / numbered lists, images, and tables. Place images and tables below the related text section.
 - **Tables**: every row, including the header, starts on a new line.
diff --git a/graphrag-ui/src/pages/setup/KGAdmin.tsx b/graphrag-ui/src/pages/setup/KGAdmin.tsx
index 2cf23b5..eb1213d 100644
--- a/graphrag-ui/src/pages/setup/KGAdmin.tsx
+++ b/graphrag-ui/src/pages/setup/KGAdmin.tsx
@@ -2,7 +2,7 @@ import React, { useState, useEffect, useRef } from "react";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { TagInput, TypeHint } from "@/components/ui/tag-input";
-import { Database, Loader2, RefreshCw, Upload, Wrench } from "lucide-react";
+import { Database, Loader2, RefreshCw, Upload, Wrench, FileCode, List } from "lucide-react";
 import { pauseIdleTimer, resumeIdleTimer, pingIdleTimer } from "@/hooks/useIdleTimeout";
 import {
   Dialog,
@@ -19,6 +19,7 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { useConfirm } from "@/hooks/useConfirm";
 import { useAlert } from "@/hooks/useAlert";
 import { resolveUploadConflicts } from "@/utils/uploadConflicts";
@@ -35,6 +36,37 @@ const INPUT_CLIP_FIX: React.CSSProperties = {
   lineHeight: "1.5",
 };
 
+type QueryDraft = {
+  name: string;
+  returns: string;
+  useFor: string;
+  doNotUse: string;
+  gsql: string;
+};
+type ListedQuery = { function_header: string; description: string; docstring?: string };
+
+function emptyQueryDraft(): QueryDraft {
+  return { name: "", returns: "", useFor: "", doNotUse: "", gsql: "" };
+}
+
+/** Same 1–2 sentence shape as built-in tools in tool_registry.py. */
+function buildToolDescription(
+  name: string,
+  returns: string,
+  useFor: string,
+  doNotUse: string
+): string {
+  const n = name.trim() || "this_query";
+  const r = returns.trim().replace(/\.+$/, "");
+  const u = useFor.trim().replace(/\.+$/, "");
+  const d = doNotUse.trim().replace(/\.+$/, "");
+  const parts = [`Run installed query ${n}.`];
+  if (r) parts.push(`Returns ${r}.`);
+  if (u) parts.push(`Use for ${u}.`);
+  if (d) parts.push(`Do not use for ${d}.`);
+  return parts.join(" ");
+}
+
 /**
  * Returns a human-readable error string when a graph name violates naming rules,
  * or null when the name is valid.
@@ -68,6 +100,7 @@ const KGAdmin = () => {
   const [refreshDialogOpen, setRefreshDialogOpen] = useState(false);
   const [ingestDialogOpen, setIngestDialogOpen] = useState(false);
   const [migrationDialogOpen, setMigrationDialogOpen] = useState(false);
+  const [registerDialogOpen, setRegisterDialogOpen] = useState(false);
 
   // Migration Assistant state
   const [migrationGraph, setMigrationGraph] = useState("");
@@ -79,19 +112,23 @@ const KGAdmin = () => {
       missing_files: string[];
     };
     needs_repair?: boolean;
-    embeddings?: {
-      by_type: Record<string, { total: number; missing: number }>;
-      total_missing: number;
-    };
-    embeddings_incomplete?: boolean;
-    community_summaries?: { total: number; needs_resummarize: number };
-    community_summaries_incomplete?: boolean;
   } | null>(null);
   const [migrationChecking, setMigrationChecking] = useState(false);
   const [migrationApplying, setMigrationApplying] = useState(false);
-  // "" | "regenerate_embeddings" | "regenerate_summaries" — which regen is running
-  const [migrationRegenerating, setMigrationRegenerating] = useState("");
   const [migrationMessage, setMigrationMessage] = useState("");
+
+  // Register Queries state
+  const [registerGraph, setRegisterGraph] = useState("");
+  const [registerMode, setRegisterMode] = useState<"single" | "multiple">("single");
+  const [registeredQueries, setRegisteredQueries] = useState<ListedQuery[]>([]);
+  const [installedQueries, setInstalledQueries] = useState<ListedQuery[]>([]);
+  const [queryDrafts, setQueryDrafts] = useState<QueryDraft[]>([emptyQueryDraft()]);
+  const [registerLoading, setRegisterLoading] = useState(false);
+  const [registerSaving, setRegisterSaving] = useState(false);
+  const [registerMessage, setRegisterMessage] = useState("");
+  const [queryListFilter, setQueryListFilter] = useState("");
+  const [registerPage, setRegisterPage] = useState<"registered" | "original">("registered");
+  const registerStatusRef = useRef<HTMLDivElement>(null);
   // Reset states when dialogs close
   const handleInitializeDialogChange = (open: boolean) => {
     if (!open && isConfirmDialogOpen) {
@@ -154,27 +191,14 @@ const KGAdmin = () => {
         return;
       }
       setMigrationStatus(data);
-      if (
-        !data.needs_repair &&
-        !data.embeddings_incomplete &&
-        !data.community_summaries_incomplete
-      ) {
+      if (!data.needs_repair) {
         setMigrationMessage("✅ Graph is up to date — no repairs needed.");
       } else {
-        const parts: string[] = [];
         const out = data.queries?.outdated?.length || 0;
         const miss = data.queries?.not_installed?.length || 0;
-        if (out || miss)
-          parts.push(`${out} outdated query(s), ${miss} not installed`);
-        if (data.embeddings_incomplete)
-          parts.push(
-            `${data.embeddings?.total_missing ?? 0} vertices missing embeddings`
-          );
-        if (data.community_summaries_incomplete)
-          parts.push(
-            `${data.community_summaries?.needs_resummarize ?? 0} communities need re-summarization`
-          );
-        setMigrationMessage(`Found: ${parts.join("; ")}.`);
+        setMigrationMessage(
+          `Found ${out} outdated query(s) and ${miss} not installed.`
+        );
       }
     } catch (err: any) {
       setMigrationMessage(`Check failed: ${err.message || err}`);
@@ -248,46 +272,213 @@ const KGAdmin = () => {
     }
   };
 
-  // Targeted data-integrity regeneration (not a full rebuild). action is
-  // "regenerate_embeddings" or "regenerate_summaries".
-  const runRegenerate = async (
-    action: "regenerate_embeddings" | "regenerate_summaries"
-  ) => {
-    const auth = sessionStorage.getItem("auth");
-    if (!auth) {
-      setMigrationMessage("Not authenticated.");
+  const loadRegisterQueries = async (graph: string, keepMessage = false) => {
+    if (!graph.trim()) return;
+    const creds = sessionStorage.getItem("auth");
+    if (!creds) {
+      setRegisterMessage("Not authenticated.");
+      return;
+    }
+    setRegisterLoading(true);
+    setRegisteredQueries([]);
+    setInstalledQueries([]);
+    try {
+      const registeredResp = await fetch(`/ui/${graph}/registered_queries`, {
+        headers: { Authorization: creds },
+      });
+      const registeredData = await registeredResp.json();
+      if (!registeredResp.ok) {
+        setRegisterMessage(
+          registeredData?.detail || `Failed to list queries: ${registeredResp.statusText}`
+        );
+        return;
+      }
+      setRegisteredQueries(registeredData?.registered || registeredData?.queries || []);
+      setInstalledQueries(registeredData?.installed || []);
+      if (!keepMessage) setRegisterMessage("");
+    } catch (err: any) {
+      setRegisterMessage(`Failed to load queries: ${err.message || err}`);
+    } finally {
+      setRegisterLoading(false);
+    }
+  };
+
+  const openRegisterDialog = () => {
+    setRegisterMessage("");
+    setQueryListFilter("");
+    setRegisterPage("registered");
+    setRegisterMode("single");
+    setQueryDrafts([emptyQueryDraft()]);
+    const initial =
+      sessionStorage.getItem("selectedGraph") || availableGraphs[0] || "";
+    setRegisterGraph(initial);
+    setRegisterDialogOpen(true);
+    if (initial) loadRegisterQueries(initial);
+  };
+
+  const useInstalledQuery = (q: ListedQuery) => {
+    setRegisterMode("single");
+    setQueryDrafts([
+      {
+        name: q.function_header,
+        returns: "",
+        useFor: "",
+        doNotUse: "",
+        gsql: "",
+      },
+    ]);
+    setRegisterPage("registered");
+    setRegisterMessage(
+      `Selected installed query "${q.function_header}". Fill in what it returns and when to use it, then click Register.`
+    );
+  };
+
+  const visibleDrafts = registerMode === "single" ? queryDrafts.slice(0, 1) : queryDrafts;
+  const queryFilter = queryListFilter.trim().toLowerCase();
+  const matchesQueryFilter = (q: ListedQuery) =>
+    !queryFilter ||
+    q.function_header.toLowerCase().includes(queryFilter) ||
+    (q.description || "").toLowerCase().includes(queryFilter);
+  const visibleRegisteredQueries = registeredQueries.filter(matchesQueryFilter);
+  const visibleOriginalQueries = installedQueries.filter(matchesQueryFilter);
+
+  const updateDraft = (index: number, patch: Partial<QueryDraft>) => {
+    setQueryDrafts((prev) => {
+      const next = prev.length ? [...prev] : [emptyQueryDraft()];
+      while (next.length <= index) next.push(emptyQueryDraft());
+      next[index] = { ...next[index], ...patch };
+      return next;
+    });
+  };
+
+  const runRegisterQueries = async () => {
+    if (!registerGraph) {
+      setRegisterMessage("Pick a graph first.");
+      return;
+    }
+    const drafts = visibleDrafts
+      .map((d) => ({
+        name: d.name.trim(),
+        returns: d.returns.trim(),
+        useFor: d.useFor.trim(),
+        doNotUse: d.doNotUse.trim(),
+        gsql: (d.gsql || "").trim(),
+      }))
+      .filter((d) => d.name || d.returns || d.useFor || d.gsql);
+    if (drafts.length === 0) {
+      setRegisterMessage(
+        "Enter a query name, what it returns, and when to use it (paste GSQL only if the query is not installed yet)."
+      );
+      return;
+    }
+    if (drafts.some((d) => !d.name)) {
+      setRegisterMessage("Each query needs a name.");
+      return;
+    }
+    const missingReturns = drafts.filter((d) => !d.returns).map((d) => d.name);
+    if (missingReturns.length > 0) {
+      setRegisterMessage(`Say what this query returns for: ${missingReturns.join(", ")}`);
+      return;
+    }
+    const missingUse = drafts.filter((d) => !d.useFor).map((d) => d.name);
+    if (missingUse.length > 0) {
+      setRegisterMessage(`Say when to use this tool for: ${missingUse.join(", ")}`);
+      return;
+    }
+    const creds = sessionStorage.getItem("auth");
+    if (!creds) {
+      setRegisterMessage("Not authenticated.");
       return;
     }
-    const isEmb = action === "regenerate_embeddings";
-    setMigrationRegenerating(action);
-    setMigrationMessage(
-      isEmb ? "Regenerating embeddings…" : "Regenerating community summaries…"
+    const willCreate = drafts.some((d) => d.gsql);
+    setRegisterSaving(true);
+    setRegisterMessage(
+      willCreate
+        ? drafts.length > 1
+          ? "Creating, installing, and registering queries…"
+          : "Creating, installing, and registering query…"
+        : drafts.length > 1
+          ? "Registering queries…"
+          : "Registering query…"
     );
+    requestAnimationFrame(() => {
+      registerStatusRef.current?.scrollIntoView({ behavior: "smooth", block: "nearest" });
+    });
     try {
-      const resp = await fetch(`/ui/${migrationGraph}/migration/${action}`, {
+      const resp = await fetch(`/ui/${registerGraph}/registered_queries`, {
         method: "POST",
-        headers: { Authorization: auth },
+        headers: { Authorization: creds, "Content-Type": "application/json" },
+        body: JSON.stringify({
+          queries: drafts.map((d) => ({
+            function_header: d.name,
+            description: buildToolDescription(d.name, d.returns, d.useFor, d.doNotUse),
+            gsql: d.gsql,
+          })),
+        }),
       });
-      const data = await resp.json().catch(() => ({}));
+      const data = await resp.json();
       if (!resp.ok) {
-        setMigrationMessage(
-          `Regenerate failed: ${data.detail || resp.statusText}`
-        );
+        const detail =
+          typeof data?.detail === "string"
+            ? data.detail
+            : data?.detail?.message || JSON.stringify(data?.detail || data);
+        setRegisterMessage(detail || `Register failed: ${resp.statusText}`);
         return;
       }
-      const done = isEmb ? data.regenerated ?? 0 : data.resummarized ?? 0;
-      const skipped = data.skipped ?? 0;
-      const verb = isEmb ? "Re-embedded" : "Re-summarized";
-      setMigrationMessage(
-        `✅ ${verb} ${done}` +
-          (skipped ? `; ${skipped} skipped (need a rebuild).` : ".")
+      const createdCount = data.created?.length || 0;
+      const registeredCount = data.registered?.length || drafts.length;
+      setRegisterMessage(
+        createdCount > 0
+          ? `✅ Created, installed, and registered ${registeredCount} quer${
+              registeredCount === 1 ? "y" : "ies"
+            }. GraphRAG tagged the GSQL description so the agent can use ${
+              registeredCount === 1 ? "it" : "them"
+            } as a tool.`
+          : `✅ Registered ${registeredCount} quer${
+              registeredCount === 1 ? "y" : "ies"
+            }. GraphRAG tagged the GSQL description.`
       );
-      // Refresh so the counts reflect the regenerated state.
-      await runMigrationCheck(migrationGraph);
+      setQueryDrafts([emptyQueryDraft()]);
+      await loadRegisterQueries(registerGraph, true);
+    } catch (err: any) {
+      setRegisterMessage(`Register failed: ${err.message || err}`);
+    } finally {
+      setRegisterSaving(false);
+    }
+  };
+
+  const runUnregisterQuery = async (header: string) => {
+    const ok = await confirm(
+      `Unregister query "${header}"? This removes it from GraphRAG candidates. The installed GSQL query on the graph is not dropped.`
+    );
+    if (!ok) return;
+    const creds = sessionStorage.getItem("auth");
+    if (!creds) {
+      setRegisterMessage("Not authenticated.");
+      return;
+    }
+    setRegisterSaving(true);
+    setRegisterMessage(`Unregistering ${header}…`);
+    requestAnimationFrame(() => {
+      registerStatusRef.current?.scrollIntoView({ behavior: "smooth", block: "nearest" });
+    });
+    try {
+      const resp = await fetch(`/ui/${registerGraph}/registered_queries/delete`, {
+        method: "POST",
+        headers: { Authorization: creds, "Content-Type": "application/json" },
+        body: JSON.stringify({ ids: [header] }),
+      });
+      const data = await resp.json();
+      if (!resp.ok) {
+        setRegisterMessage(data?.detail || `Delete failed: ${resp.statusText}`);
+        return;
+      }
+      setRegisterMessage(`✅ Unregistered ${header}.`);
+      await loadRegisterQueries(registerGraph, true);
     } catch (err: any) {
-      setMigrationMessage(`Regenerate failed: ${err.message || err}`);
+      setRegisterMessage(`Delete failed: ${err.message || err}`);
     } finally {
-      setMigrationRegenerating("");
+      setRegisterSaving(false);
     }
   };
 
@@ -1478,6 +1669,30 @@ const KGAdmin = () => {
             </div>
           </div>
 
+          {/* Register Queries Card */}
+          <div className="border border-gray-300 dark:border-[#3D3D3D] rounded-lg p-6 bg-white dark:bg-shadeA flex flex-col h-full">
+            <div className="mb-4">
+              <div className="w-12 h-12 rounded-full bg-tigerOrange/10 flex items-center justify-center mb-4">
+                <FileCode className="h-6 w-6 text-tigerOrange" />
+              </div>
+              <h2 className="text-lg font-semibold mb-2 text-black dark:text-white">
+                Register Queries
+              </h2>
+              <p className="text-sm text-gray-600 dark:text-[#D9D9D9] mb-4">
+                Paste GSQL to create and install a query, then register it as a GraphRAG tool. Leave GSQL empty to tag an already-installed query.
+              </p>
+            </div>
+            <div className="mt-auto pt-4 border-t border-gray-300 dark:border-[#3D3D3D]">
+              <Button
+                onClick={openRegisterDialog}
+                className="gradient w-full text-white"
+              >
+                <FileCode className="h-4 w-4 mr-2" />
+                Register Queries
+              </Button>
+            </div>
+          </div>
+
         </div>
 
         {/* Initialize Dialog */}
@@ -2953,97 +3168,6 @@ const KGAdmin = () => {
                       </div>
                     </div>
                   )}
-
-                  {/* Data-integrity health: embedding coverage */}
-                  {migrationStatus.embeddings &&
-                    Object.keys(migrationStatus.embeddings.by_type).length > 0 && (
-                      <div
-                        className={`p-3 rounded border ${
-                          migrationStatus.embeddings_incomplete
-                            ? "bg-yellow-50 dark:bg-yellow-900/20 border-yellow-200 dark:border-yellow-800"
-                            : "bg-green-50 dark:bg-green-900/20 border-green-200 dark:border-green-800"
-                        }`}
-                      >
-                        <div className="flex items-center justify-between gap-2">
-                          <div className="font-medium text-black dark:text-white">
-                            Embedding health
-                            {migrationStatus.embeddings.total_missing > 0
-                              ? ` — ${migrationStatus.embeddings.total_missing} missing`
-                              : " — all embedded"}
-                          </div>
-                          {migrationStatus.embeddings_incomplete && (
-                            <Button
-                              onClick={() => runRegenerate("regenerate_embeddings")}
-                              disabled={
-                                !!migrationRegenerating ||
-                                migrationApplying ||
-                                migrationChecking ||
-                                isRebuildRunning
-                              }
-                              className="gradient text-white h-7 text-xs whitespace-nowrap"
-                            >
-                              {migrationRegenerating === "regenerate_embeddings" ? (
-                                <>
-                                  <Loader2 className="h-3 w-3 mr-1 animate-spin" />
-                                  Regenerating…
-                                </>
-                              ) : (
-                                "Regenerate embeddings"
-                              )}
-                            </Button>
-                          )}
-                        </div>
-                        <div className="mt-1 font-mono text-xs text-gray-600 dark:text-gray-400">
-                          {Object.entries(migrationStatus.embeddings.by_type)
-                            .map(
-                              ([t, c]) => `${t}: ${c.missing}/${c.total} missing`
-                            )
-                            .join("  ·  ")}
-                        </div>
-                      </div>
-                    )}
-
-                  {/* Data-integrity health: community summaries */}
-                  {migrationStatus.community_summaries &&
-                    (migrationStatus.community_summaries.total ?? 0) > 0 && (
-                      <div
-                        className={`p-3 rounded border ${
-                          migrationStatus.community_summaries_incomplete
-                            ? "bg-yellow-50 dark:bg-yellow-900/20 border-yellow-200 dark:border-yellow-800"
-                            : "bg-green-50 dark:bg-green-900/20 border-green-200 dark:border-green-800"
-                        }`}
-                      >
-                        <div className="flex items-center justify-between gap-2">
-                          <div className="font-medium text-black dark:text-white">
-                            Community summaries —{" "}
-                            {migrationStatus.community_summaries.needs_resummarize}/
-                            {migrationStatus.community_summaries.total} need
-                            re-summarization
-                          </div>
-                          {migrationStatus.community_summaries_incomplete && (
-                            <Button
-                              onClick={() => runRegenerate("regenerate_summaries")}
-                              disabled={
-                                !!migrationRegenerating ||
-                                migrationApplying ||
-                                migrationChecking ||
-                                isRebuildRunning
-                              }
-                              className="gradient text-white h-7 text-xs whitespace-nowrap"
-                            >
-                              {migrationRegenerating === "regenerate_summaries" ? (
-                                <>
-                                  <Loader2 className="h-3 w-3 mr-1 animate-spin" />
-                                  Regenerating…
-                                </>
-                              ) : (
-                                "Regenerate summaries"
-                              )}
-                            </Button>
-                          )}
-                        </div>
-                      </div>
-                    )}
                 </div>
               )}
 
@@ -3095,6 +3219,450 @@ const KGAdmin = () => {
             </DialogFooter>
           </DialogContent>
         </Dialog>
+
+        {/* Register Queries Dialog */}
+        <Dialog open={registerDialogOpen} onOpenChange={setRegisterDialogOpen}>
+          <DialogContent
+            className="sm:max-w-[720px] max-h-[90vh] overflow-y-auto bg-white dark:bg-background border-gray-300 dark:border-[#3D3D3D]"
+            onInteractOutside={(e) => e.preventDefault()}
+          >
+            <DialogHeader>
+              <DialogTitle className="text-black dark:text-white">
+                Register Queries
+              </DialogTitle>
+              <DialogDescription className="text-gray-600 dark:text-[#D9D9D9]">
+                Register installed GSQL as GraphRAG tools, or pick an original query already on the graph.
+              </DialogDescription>
+            </DialogHeader>
+
+            <div className="py-4 space-y-4">
+              <div>
+                <label className="block text-sm font-medium mb-2 text-black dark:text-white">
+                  Graph
+                </label>
+                <Select
+                  value={registerGraph}
+                  onValueChange={(v) => {
+                    setRegisterGraph(v);
+                    loadRegisterQueries(v);
+                  }}
+                  disabled={registerLoading || registerSaving}
+                >
+                  <SelectTrigger className="dark:border-[#3D3D3D] dark:bg-shadeA">
+                    <SelectValue placeholder="Pick a graph" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {availableGraphs.length > 0 ? (
+                      availableGraphs.map((g) => (
+                        <SelectItem key={g} value={g}>
+                          {g}
+                        </SelectItem>
+                      ))
+                    ) : (
+                      <SelectItem value="no-graphs" disabled>
+                        No graphs available
+                      </SelectItem>
+                    )}
+                  </SelectContent>
+                </Select>
+              </div>
+
+              <Tabs
+                value={registerPage}
+                onValueChange={(value) => {
+                  if (registerSaving) return;
+                  setQueryListFilter("");
+                  setRegisterPage(value as "registered" | "original");
+                }}
+                className="w-full"
+              >
+                <TabsList className="grid w-full grid-cols-2">
+                  <TabsTrigger value="registered" disabled={registerSaving}>
+                    <FileCode className="h-4 w-4 mr-2" />
+                    Registered Queries
+                  </TabsTrigger>
+                  <TabsTrigger value="original" disabled={registerSaving}>
+                    <List className="h-4 w-4 mr-2" />
+                    Original Queries
+                  </TabsTrigger>
+                </TabsList>
+
+              {registerLoading && (
+                <div className="flex items-center text-sm text-gray-600 dark:text-[#D9D9D9]">
+                  <Loader2 className="h-4 w-4 mr-2 animate-spin text-tigerOrange" />
+                  Loading queries…
+                </div>
+              )}
+
+              <TabsContent value="registered" className="space-y-4">
+                  <p className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                    Fill what the query returns and when to use it — GraphRAG merges those fields into the same one-line description the agent already uses for hybrid search and structural retrieve. Leave GSQL empty to tag an already-installed query.
+                  </p>
+                  {!registerLoading && registerGraph && (
+                    <div className="space-y-4">
+                      <Input
+                        style={INPUT_CLIP_FIX}
+                        value={queryListFilter}
+                        onChange={(e) => setQueryListFilter(e.target.value)}
+                        placeholder="Filter registered queries by name…"
+                        disabled={registerSaving}
+                        className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                      />
+
+                      <div>
+                        <div className="text-sm font-medium mb-2 text-black dark:text-white">
+                          Registered queries ({registeredQueries.length})
+                        </div>
+                        <p className="text-xs text-gray-500 dark:text-[#A0A0A0] mb-2">
+                          Tagged with [GRAPHRAG_TOOL]. The agent can pick these as tools.
+                        </p>
+                        {registeredQueries.length === 0 ? (
+                          <p className="text-xs text-gray-500 dark:text-[#A0A0A0]">
+                            None registered yet. Paste GSQL below, or open Original Queries and click Use.
+                          </p>
+                        ) : visibleRegisteredQueries.length === 0 ? (
+                          <p className="text-xs text-gray-500 dark:text-[#A0A0A0]">
+                            No registered queries match the filter.
+                          </p>
+                        ) : (
+                          <div className="space-y-2">
+                            {visibleRegisteredQueries.map((q) => (
+                              <div
+                                key={q.function_header}
+                                className="flex items-start justify-between gap-3 border border-tigerOrange/40 rounded-md p-3 bg-tigerOrange/5"
+                              >
+                                <div className="min-w-0">
+                                  <div className="flex items-center gap-2">
+                                    <div className="font-mono text-sm text-black dark:text-white">
+                                      {q.function_header}
+                                    </div>
+                                    <span className="shrink-0 text-[10px] uppercase tracking-wide px-1.5 py-0.5 rounded bg-tigerOrange/20 text-tigerOrange">
+                                      Registered
+                                    </span>
+                                  </div>
+                                  <div className="text-xs text-gray-600 dark:text-[#D9D9D9] mt-1 whitespace-pre-wrap">
+                                    {q.description || "No description"}
+                                  </div>
+                                </div>
+                                <Button
+                                  variant="outline"
+                                  onClick={() => runUnregisterQuery(q.function_header)}
+                                  disabled={registerSaving}
+                                  className="shrink-0 dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                                >
+                                  Delete
+                                </Button>
+                              </div>
+                            ))}
+                          </div>
+                        )}
+                      </div>
+                    </div>
+                  )}
+
+                  <div>
+                    <label className="block text-sm font-medium mb-2 text-black dark:text-white">
+                      Registration mode
+                    </label>
+                    <div className="flex flex-col gap-1 text-sm text-gray-700 dark:text-[#D9D9D9]">
+                      <label className="inline-flex items-center gap-2">
+                        <input
+                          type="radio"
+                          name="registerMode"
+                          checked={registerMode === "single"}
+                          onChange={() => {
+                            setRegisterMode("single");
+                            setQueryDrafts((prev) => (prev.length ? [prev[0]] : [emptyQueryDraft()]));
+                          }}
+                          disabled={registerLoading || registerSaving}
+                        />
+                        <span>Single query</span>
+                      </label>
+                      <label className="inline-flex items-center gap-2">
+                        <input
+                          type="radio"
+                          name="registerMode"
+                          checked={registerMode === "multiple"}
+                          onChange={() => setRegisterMode("multiple")}
+                          disabled={registerLoading || registerSaving}
+                        />
+                        <span>Multiple queries</span>
+                      </label>
+                    </div>
+                  </div>
+
+                  <div className="space-y-3">
+                    {visibleDrafts.map((draft, index) => (
+                      <div
+                        key={index}
+                        className="border border-gray-200 dark:border-[#3D3D3D] rounded-md p-3 space-y-3"
+                      >
+                        {registerMode === "multiple" && (
+                          <div className="flex items-center justify-between">
+                            <div className="text-sm font-medium text-black dark:text-white">
+                              Query {index + 1}
+                            </div>
+                            {visibleDrafts.length > 1 && (
+                              <Button
+                                variant="outline"
+                                onClick={() =>
+                                  setQueryDrafts((prev) => prev.filter((_, i) => i !== index))
+                                }
+                                disabled={registerSaving}
+                                className="h-8 px-2 dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                              >
+                                Remove
+                              </Button>
+                            )}
+                          </div>
+                        )}
+                        <div>
+                          <label className="block text-sm font-medium mb-2 text-black dark:text-white">
+                            Query name
+                          </label>
+                          <Input
+                            style={INPUT_CLIP_FIX}
+                            value={draft.name}
+                            onChange={(e) => updateDraft(index, { name: e.target.value })}
+                            placeholder="e.g. my_custom_query"
+                            disabled={registerSaving}
+                            className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                          />
+                        </div>
+                        <div>
+                          <label className="block text-sm font-medium mb-2 text-black dark:text-white">
+                            GSQL
+                          </label>
+                          <textarea
+                            className="w-full min-h-[140px] rounded-md border border-input bg-background dark:border-[#3D3D3D] dark:bg-shadeA px-3 py-2 text-sm font-mono text-black dark:text-white"
+                            value={draft.gsql}
+                            onChange={(e) => updateDraft(index, { gsql: e.target.value })}
+                            placeholder={`CREATE OR REPLACE QUERY my_custom_query() FOR GRAPH ${registerGraph || "graphname"} {\n  PRINT 1 AS result;\n}`}
+                            disabled={registerSaving}
+                          />
+                          <p className="mt-1 text-xs text-gray-500 dark:text-[#A0A0A0]">
+                            Optional if the query is already installed. Paste a full CREATE statement or the query body.
+                          </p>
+                        </div>
+                        <div>
+                          <label className="block text-sm font-medium mb-2 text-black dark:text-white">
+                            What it returns
+                          </label>
+                          <Input
+                            style={INPUT_CLIP_FIX}
+                            value={draft.returns}
+                            onChange={(e) => updateDraft(index, { returns: e.target.value })}
+                            placeholder="e.g. the month the FILP / 財政投融資計画 annual plan is decided"
+                            disabled={registerSaving}
+                            className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                          />
+                          <p className="mt-1 text-xs text-gray-500 dark:text-[#A0A0A0]">
+                            Finish the sentence: “Returns …” — the fact this query answers, not how it is written in GSQL.
+                          </p>
+                        </div>
+                        <div>
+                          <label className="block text-sm font-medium mb-2 text-black dark:text-white">
+                            Use for
+                          </label>
+                          <Input
+                            style={INPUT_CLIP_FIX}
+                            value={draft.useFor}
+                            onChange={(e) => updateDraft(index, { useFor: e.target.value })}
+                            placeholder="e.g. questions about when that plan is finalized"
+                            disabled={registerSaving}
+                            className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                          />
+                          <p className="mt-1 text-xs text-gray-500 dark:text-[#A0A0A0]">
+                            Same as hybrid_search / community_search: “Use for …” when the agent should pick this tool.
+                          </p>
+                        </div>
+                        <div>
+                          <label className="block text-sm font-medium mb-2 text-black dark:text-white">
+                            Do not use for
+                            <span className="ml-1 font-normal text-gray-500 dark:text-[#A0A0A0]">
+                              (optional)
+                            </span>
+                          </label>
+                          <Input
+                            style={INPUT_CLIP_FIX}
+                            value={draft.doNotUse}
+                            onChange={(e) => updateDraft(index, { doNotUse: e.target.value })}
+                            placeholder="e.g. policy cost, ALM, or JFC amounts"
+                            disabled={registerSaving}
+                            className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                          />
+                        </div>
+                        {(draft.returns.trim() || draft.useFor.trim()) && (
+                          <div className="rounded-md border border-gray-200 dark:border-[#3D3D3D] bg-gray-50 dark:bg-shadeA p-3">
+                            <div className="text-xs font-medium text-gray-500 dark:text-[#A0A0A0] mb-1">
+                              Tool description the agent will see
+                            </div>
+                            <p className="text-sm text-black dark:text-white">
+                              {buildToolDescription(
+                                draft.name,
+                                draft.returns,
+                                draft.useFor,
+                                draft.doNotUse
+                              )}
+                            </p>
+                          </div>
+                        )}
+                      </div>
+                    ))}
+                    {registerMode === "multiple" && (
+                      <Button
+                        variant="outline"
+                        onClick={() => setQueryDrafts((prev) => [...prev, emptyQueryDraft()])}
+                        disabled={registerSaving}
+                        className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                      >
+                        Add another query
+                      </Button>
+                    )}
+                  </div>
+              </TabsContent>
+              <TabsContent value="original" className="space-y-4">
+                  <p className="text-sm font-medium text-gray-500 dark:text-gray-400">
+                    Browse GSQL queries installed on the graph that are not registered as GraphRAG tools. Click Use to fill the register form.
+                  </p>
+                {!registerLoading && registerGraph && (
+                  <div className="space-y-4">
+                    <Input
+                      style={INPUT_CLIP_FIX}
+                      value={queryListFilter}
+                      onChange={(e) => setQueryListFilter(e.target.value)}
+                      placeholder="Filter original queries by name…"
+                      disabled={registerSaving}
+                      className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                    />
+
+                    <div>
+                      <div className="text-sm font-medium mb-2 text-black dark:text-white">
+                        Original installed queries ({installedQueries.length})
+                      </div>
+                      <p className="text-xs text-gray-500 dark:text-[#A0A0A0] mb-2">
+                        Installed on the graph, not tagged as GraphRAG tools. Click Use to fill the Registered Queries form.
+                      </p>
+                      {installedQueries.length === 0 ? (
+                        <p className="text-xs text-gray-500 dark:text-[#A0A0A0]">
+                          No installed queries on this graph yet.
+                        </p>
+                      ) : visibleOriginalQueries.length === 0 ? (
+                        <p className="text-xs text-gray-500 dark:text-[#A0A0A0]">
+                          No original queries match the filter.
+                        </p>
+                      ) : (
+                        <div className="space-y-2">
+                          {visibleOriginalQueries.map((q) => (
+                            <div
+                              key={q.function_header}
+                              className="flex items-start justify-between gap-3 border border-gray-200 dark:border-[#3D3D3D] rounded-md p-3"
+                            >
+                              <div className="min-w-0">
+                                <div className="flex items-center gap-2">
+                                  <div className="font-mono text-sm text-black dark:text-white">
+                                    {q.function_header}
+                                  </div>
+                                  <span className="shrink-0 text-[10px] uppercase tracking-wide px-1.5 py-0.5 rounded bg-gray-200 dark:bg-[#3D3D3D] text-gray-600 dark:text-[#A0A0A0]">
+                                    Installed
+                                  </span>
+                                </div>
+                                {q.description ? (
+                                  <div className="text-xs text-gray-600 dark:text-[#D9D9D9] mt-1 line-clamp-2">
+                                    {q.description}
+                                  </div>
+                                ) : (
+                                  <div className="text-xs text-gray-400 dark:text-[#808080] mt-1">
+                                    No description
+                                  </div>
+                                )}
+                              </div>
+                              <Button
+                                variant="outline"
+                                onClick={() => useInstalledQuery(q)}
+                                disabled={registerSaving}
+                                className="shrink-0 dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+                              >
+                                Use
+                              </Button>
+                            </div>
+                          ))}
+                        </div>
+                      )}
+                    </div>
+                  </div>
+                )}
+              </TabsContent>
+              </Tabs>
+            </div>
+
+            <DialogFooter className="flex-col sm:flex-col gap-3 sm:space-x-0">
+              {(registerSaving || registerMessage) && (
+                <div ref={registerStatusRef} className="w-full space-y-2">
+                  {registerSaving && (
+                    <div className="space-y-2">
+                      <div className="flex items-center text-sm text-gray-600 dark:text-[#D9D9D9]">
+                        <Loader2 className="h-4 w-4 mr-2 animate-spin text-tigerOrange" />
+                        {registerMessage || "Working…"}
+                      </div>
+                      <div className="h-2 w-full rounded-full bg-gray-200 dark:bg-[#3D3D3D] overflow-hidden">
+                        <div className="h-full w-full rounded-full bg-tigerOrange animate-pulse" />
+                      </div>
+                    </div>
+                  )}
+                  {!registerSaving && registerMessage && (
+                    <div
+                      className={`p-3 rounded-lg text-sm whitespace-pre-line ${
+                        registerMessage.includes("❌") ||
+                        registerMessage.toLowerCase().includes("fail")
+                          ? "bg-red-50 dark:bg-red-900/20 text-red-700 dark:text-red-300"
+                          : registerMessage.includes("✅")
+                          ? "bg-green-50 dark:bg-green-900/20 text-green-700 dark:text-green-300"
+                          : "bg-blue-50 dark:bg-blue-900/20 text-blue-700 dark:text-blue-300"
+                      }`}
+                    >
+                      {registerMessage}
+                    </div>
+                  )}
+                </div>
+              )}
+              <div className="flex flex-col-reverse sm:flex-row sm:justify-end sm:space-x-2 w-full">
+              <Button
+                onClick={() => setRegisterDialogOpen(false)}
+                variant="outline"
+                disabled={registerSaving}
+                className="dark:border-[#3D3D3D] dark:bg-shadeA dark:text-white"
+              >
+                Close
+              </Button>
+              {registerPage === "registered" && (
+                <Button
+                  onClick={runRegisterQueries}
+                  disabled={registerSaving || !registerGraph}
+                  className="gradient text-white"
+                >
+                  {registerSaving ? (
+                    <>
+                      <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                      {visibleDrafts.some((d) => (d.gsql || "").trim())
+                        ? "Creating & registering…"
+                        : "Registering…"}
+                    </>
+                  ) : (
+                    <>
+                      <FileCode className="h-4 w-4 mr-2" />
+                      {visibleDrafts.some((d) => (d.gsql || "").trim())
+                        ? "Create & Register"
+                        : "Register"}
+                    </>
+                  )}
+                </Button>
+              )}
+              </div>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+
       </div>
       {confirmDialog}
       {alertDialog}
diff --git a/graphrag/app/agent/agentic_agent.py b/graphrag/app/agent/agentic_agent.py
index b585c6e..7e305be 100644
--- a/graphrag/app/agent/agentic_agent.py
+++ b/graphrag/app/agent/agentic_agent.py
@@ -210,6 +210,20 @@ def question_for_agent(
             except Exception as exc:
                 logger.warning(f"agentic: mcp_addons discovery skipped: {exc}")
 
+            try:
+                from tools.gsql_query_tools import discover_tagged_query_tools
+                gsql_tools = discover_tagged_query_tools(
+                    self.conn, self.conn.graphname
+                )
+                if gsql_tools:
+                    external_tools.update(gsql_tools)
+                    logger.info(
+                        f"agentic: {len(gsql_tools)} tagged GSQL tool(s) for "
+                        f"graph={self.conn.graphname}"
+                    )
+            except Exception as exc:
+                logger.warning(f"agentic: tagged GSQL discovery skipped: {exc}")
+
             # Logged-in user, when available (used for per-call _meta on MCP tools).
             user = getattr(self.conn, "username", None)
 
diff --git a/graphrag/app/agent/agentic_react.py b/graphrag/app/agent/agentic_react.py
index f838720..de9329e 100644
--- a/graphrag/app/agent/agentic_react.py
+++ b/graphrag/app/agent/agentic_react.py
@@ -56,7 +56,11 @@
 
 
 def _tool_label(name: str) -> str:
-    return _TOOL_LABELS.get(name, "Gathering information")
+    if name in _TOOL_LABELS:
+        return _TOOL_LABELS[name]
+    if (name or "").startswith("graphrag__gsql__"):
+        return f"Running registered query {name[len('graphrag__gsql__'):]}"
+    return "Gathering information"
 
 def run_react(ctx, llm, question, conversation=None) -> GraphRAGResponse:
     """Run the free tool-calling loop for one question and return a response."""
diff --git a/graphrag/app/routers/ui.py b/graphrag/app/routers/ui.py
index a482e90..6a9d7ef 100644
--- a/graphrag/app/routers/ui.py
+++ b/graphrag/app/routers/ui.py
@@ -1699,6 +1699,234 @@ def _migration_apply_inner(
     }
 
 
+_CREATE_QUERY_NAME_RE = re.compile(
+    r"(?is)^\s*CREATE\s+(?:OR\s+REPLACE\s+)?QUERY\s+([A-Za-z_][A-Za-z0-9_]*)"
+)
+
+
+def _user_query_gsql(header: str, gsql: str, graphname: str) -> str:
+    """Normalize pasted GSQL into a CREATE OR REPLACE QUERY statement."""
+    text = re.sub(r"(?im)^\s*USE\s+GRAPH\s+\S+\s*;?\s*", "", (gsql or "").strip()).strip()
+    if not text:
+        raise HTTPException(status_code=400, detail=f"GSQL is empty for query '{header}'.")
+    m = _CREATE_QUERY_NAME_RE.match(text)
+    if m:
+        qname = m.group(1)
+        if qname != header:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"GSQL query name '{qname}' does not match the name field "
+                    f"'{header}'."
+                ),
+            )
+        if not re.match(r"(?is)^\s*CREATE\s+OR\s+REPLACE\s+QUERY\b", text):
+            text = re.sub(
+                r"(?is)^\s*CREATE\s+QUERY\b",
+                "CREATE OR REPLACE QUERY",
+                text,
+                count=1,
+            )
+        return text
+    return (
+        f"CREATE OR REPLACE QUERY {header}() FOR GRAPH {graphname} {{\n{text}\n}}\n"
+    )
+
+
+def _create_user_query(conn, graphname: str, header: str, query_body: str) -> None:
+    """CREATE OR REPLACE via createQuery REST, with GSQL fallback."""
+    conn.graphname = graphname
+    tg_err = None
+    try:
+        res = conn.createQuery(query_body)
+        tg_err = create_response_error(res)
+    except Exception as create_exc:
+        tg_err = create_response_error(http_error_response_body(create_exc))
+        if not tg_err:
+            logger.info(
+                "Register: createQuery transport error for '%s'; gsql fallback: %s",
+                header,
+                create_exc,
+            )
+            gres = conn.gsql(f"USE GRAPH {graphname}\nBEGIN\n{query_body}\nEND\n")
+            if gsql_output_error(gres):
+                logger.debug("Register: full gsql result for '%s': %s", header, gres)
+                tg_err = concise_gsql_error(gres)
+    if tg_err:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Failed to create query '{header}': {tg_err}",
+        )
+
+
+def _gsql_desc_quoted(text: str) -> str:
+    escaped = (
+        (text or "")
+        .replace("\\", "\\\\")
+        .replace('"', '\\"')
+        .replace("\r\n", "\\n")
+        .replace("\n", "\\n")
+    )
+    return f'"{escaped}"'
+
+
+def _gsql_desc_cmd(conn, graphname: str, statement: str) -> str:
+    from common.db.schema_utils import gsql_output_error
+
+    out = conn.gsql(f"USE GRAPH {graphname}\n{statement}\n")
+    text = out if isinstance(out, str) else str(out)
+    err = gsql_output_error(text)
+    if err:
+        raise HTTPException(status_code=400, detail=err)
+    return text
+
+
+@router.get(route_prefix + "/{graphname}/registered_queries")
+def ui_list_registered_queries(
+    graphname: ValidGraphName,
+    creds: Annotated[tuple[list[str], HTTPBasicCredentials], Depends(ui_basic_auth)],
+):
+    """List original installed queries and queries tagged with ``[GRAPHRAG_TOOL]``."""
+    from tools.gsql_query_tools import list_query_catalog
+
+    cred_obj = creds[1]
+    conn = get_db_connection_pwd_manual(graphname, cred_obj.username, cred_obj.password)
+    try:
+        catalog = list_query_catalog(conn, graphname)
+    except Exception as exc:
+        logger.warning("list registered queries failed: %s", exc)
+        raise HTTPException(
+            status_code=400,
+            detail=f"Failed to list queries: {exc}",
+        ) from exc
+    registered = catalog.get("registered") or []
+    installed = catalog.get("installed") or []
+    return {
+        "queries": registered,
+        "registered": registered,
+        "installed": installed,
+    }
+
+
+@router.post(route_prefix + "/{graphname}/registered_queries")
+def ui_register_queries(
+    graphname: ValidGraphName,
+    creds: Annotated[tuple[list[str], HTTPBasicCredentials], Depends(ui_basic_auth)],
+    payload: Annotated[dict | None, Body()] = None,
+):
+    """Create + install pasted GSQL (when provided), then tag with ``UPDATE DESCRIPTION``.
+
+    Prepends ``[GRAPHRAG_TOOL]`` so ``SHOW DESCRIPTION`` can tell user-registered
+    queries from original installed ones. Empty GSQL tags an already-installed query.
+    """
+    from common.db.migrate import get_installed_query_names
+    from common.db.query_install import install_query_set
+    from tools.gsql_query_tools import TOOL_MARKER
+
+    body = payload or {}
+    raw = body.get("queries", body if isinstance(body, dict) else [])
+    if isinstance(raw, dict):
+        raw = [raw]
+    if not raw:
+        raise HTTPException(status_code=400, detail="Provide at least one query to register.")
+    to_process: list[tuple[str, str, str]] = []
+    for item in raw:
+        header = (item.get("function_header") or item.get("name") or "").strip()
+        if not header:
+            raise HTTPException(status_code=400, detail="Each query needs a name.")
+        if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", header):
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"Invalid query name '{header}'. Use letters, digits, and "
+                    "underscores; start with a letter or underscore."
+                ),
+            )
+        description = (item.get("description") or "").strip()
+        if not description:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Description is required for query '{header}'.",
+            )
+        gsql = (item.get("gsql") or item.get("query") or "").strip()
+        to_process.append((header, description, gsql))
+    cred_obj = creds[1]
+    conn = get_db_connection_pwd_manual(graphname, cred_obj.username, cred_obj.password)
+    conn.graphname = graphname
+
+    created: list[str] = []
+    for header, _description, gsql in to_process:
+        if not gsql:
+            continue
+        query_body = _user_query_gsql(header, gsql, graphname)
+        _create_user_query(conn, graphname, header, query_body)
+        created.append(header)
+    if created:
+        try:
+            install_query_set(conn, created)
+        except Exception as exc:
+            logger.error("Register: install failed for %s: %s", created, exc, exc_info=True)
+            raise HTTPException(
+                status_code=400,
+                detail=f"Created but failed to install: {concise_gsql_error(exc)}",
+            ) from exc
+
+    installed = get_installed_query_names(conn, graphname)
+    registered = []
+    for header, description, gsql in to_process:
+        if header not in installed:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    f"Query '{header}' is not installed on graph '{graphname}'. "
+                    "Paste GSQL to create and install it, or install it first."
+                ),
+            )
+        desc = description if TOOL_MARKER in description else f"{TOOL_MARKER}\n{description}"
+        _gsql_desc_cmd(
+            conn,
+            graphname,
+            f"UPDATE DESCRIPTION OF QUERY {header} {_gsql_desc_quoted(desc)}",
+        )
+        registered.append(header)
+    return {"registered": registered, "created": created}
+
+
+@router.post(route_prefix + "/{graphname}/registered_queries/delete")
+def ui_delete_registered_queries(
+    graphname: ValidGraphName,
+    creds: Annotated[tuple[list[str], HTTPBasicCredentials], Depends(ui_basic_auth)],
+    payload: Annotated[dict | None, Body()] = None,
+):
+    """GSQL ``DROP DESCRIPTION OF QUERY``. The installed query is not dropped."""
+    body = payload or {}
+    ids = body.get("ids") or body.get("function_headers") or []
+    if isinstance(ids, str):
+        ids = [ids]
+    if not ids:
+        raise HTTPException(status_code=400, detail="Provide ids of queries to unregister.")
+    cred_obj = creds[1]
+    conn = get_db_connection_pwd_manual(graphname, cred_obj.username, cred_obj.password)
+    deleted = []
+    for header in ids:
+        name = str(header).strip()
+        if not name:
+            continue
+        if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
+            raise HTTPException(status_code=400, detail=f"Invalid query name '{name}'.")
+        try:
+            _gsql_desc_cmd(conn, graphname, f"DROP DESCRIPTION OF QUERY {name}")
+        except HTTPException as exc:
+            detail = str(exc.detail).lower()
+            if not any(
+                s in detail
+                for s in ("does not exist", "no description", "not found", "has no description")
+            ):
+                raise
+        deleted.append(name)
+    return {"deleted": deleted}
+
+
 @router.post(route_prefix + "/{graphname}/initialize_graph")
 def init_graph(
     graphname: ValidGraphName,
diff --git a/graphrag/app/tools/gsql_query_tools.py b/graphrag/app/tools/gsql_query_tools.py
new file mode 100644
index 0000000..a526cbb
--- /dev/null
+++ b/graphrag/app/tools/gsql_query_tools.py
@@ -0,0 +1,308 @@
+# Copyright (c) 2024-2026 TigerGraph, Inc.
+#
+# This program may be redistributed and/or modified under the terms of the GNU
+# Affero General Public License as published by the Free Software Foundation,
+# either version 3 of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+# details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+"""Discover tagged GSQL queries as agent catalog tools.
+
+Not a chat tool. Called in-process before plan/react so tagged queries
+already appear in ``## Tools``. Each tagged query runs via
+``conn.runInstalledQuery``.
+
+User vs original is a keyword on the native GSQL description
+(``UPDATE`` / ``SHOW`` / ``DROP DESCRIPTION OF QUERY``).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any
+
+from tools.tool_registry import ToolSpec
+
+logger = logging.getLogger(__name__)
+
+TOOL_PREFIX = "graphrag__gsql__"
+TOOL_MARKER = "[GRAPHRAG_TOOL]"
+
+# TG SHOW DESCRIPTION OF QUERY * prints:
+#   The description of queryName: text
+# Older / other formats may use a leading dash.
+_SHOW_LINE_RE = re.compile(
+    r"^\s*(?:The description of\s+|-\s+)([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(.*)$",
+    re.IGNORECASE,
+)
+
+
+def tool_name_for(query_name: str) -> str:
+    return f"{TOOL_PREFIX}{query_name}"
+
+
+def _unescape_desc(text: str | None) -> str:
+    t = (text or "").strip()
+    if not t or t.lower() == "null":
+        return ""
+    return t.replace("\\n", "\n").replace('\\"', '"')
+
+
+def strip_tool_marker(description: str | None) -> str:
+    text = _unescape_desc(description)
+    if text.startswith(TOOL_MARKER):
+        text = text[len(TOOL_MARKER) :]
+    else:
+        text = text.replace(TOOL_MARKER, "")
+    return text.lstrip("\n").strip()
+
+
+def _parse_show_description(output: str) -> list[tuple[str, str]]:
+    rows: list[tuple[str, str]] = []
+    current_name: str | None = None
+    current_desc: list[str] = []
+
+    def _flush():
+        nonlocal current_name, current_desc
+        if current_name:
+            rows.append((current_name, "\n".join(current_desc).strip()))
+        current_name = None
+        current_desc = []
+
+    for raw in (output or "").splitlines():
+        line = raw.rstrip()
+        if not line.strip() or line.strip().lower().startswith("using graph"):
+            continue
+        m = _SHOW_LINE_RE.match(line)
+        if m:
+            _flush()
+            current_name = m.group(1)
+            current_desc = [m.group(2)]
+            continue
+        if current_name is not None:
+            current_desc.append(line.strip())
+    _flush()
+    return [(name, _unescape_desc(desc)) for name, desc in rows]
+
+
+def _rows_from_query_description(raw) -> list[tuple[str, str]]:
+    if not raw:
+        return []
+    if isinstance(raw, str):
+        return _parse_show_description(raw)
+    if isinstance(raw, dict):
+        if "queryName" in raw or "name" in raw:
+            raw = [raw]
+        else:
+            out = []
+            for k, v in raw.items():
+                if isinstance(v, str):
+                    out.append((str(k), v))
+                elif isinstance(v, dict):
+                    out.append((str(k), v.get("description") or ""))
+            return out
+    if isinstance(raw, list):
+        out = []
+        for item in raw:
+            if not isinstance(item, dict):
+                continue
+            name = item.get("queryName") or item.get("name") or item.get("query")
+            desc = item.get("description") or item.get("desc") or ""
+            if name:
+                out.append((str(name), str(desc)))
+        return out
+    return []
+
+
+def _fetch_description_rows(
+    conn, graphname: str, query_names: list[str] | None = None
+) -> list[tuple[str, str]]:
+    """Read query descriptions. ``getQueryDescription('*')`` is not valid on TG."""
+    conn.graphname = graphname
+    by_name: dict[str, str] = {}
+    if query_names:
+        try:
+            for name, desc in _rows_from_query_description(
+                conn.getQueryDescription(query_names)
+            ):
+                by_name[name] = _unescape_desc(desc)
+        except Exception as exc:
+            logger.debug("getQueryDescription(list) failed: %s", exc)
+    from common.db.schema_utils import gsql_output_error
+    out = conn.gsql(f"USE GRAPH {graphname}\nSHOW DESCRIPTION OF QUERY *\n")
+    text = out if isinstance(out, str) else str(out)
+    err = gsql_output_error(text)
+    if err:
+        logger.warning("SHOW DESCRIPTION OF QUERY * failed: %s", err)
+    else:
+        for name, desc in _parse_show_description(text):
+            if name not in by_name or (TOOL_MARKER in desc and TOOL_MARKER not in by_name.get(name, "")):
+                by_name[name] = desc
+    return list(by_name.items())
+
+
+def list_query_catalog(conn, graphname: str) -> dict[str, list[dict]]:
+    """Installed queries split into original vs ``[GRAPHRAG_TOOL]``-tagged."""
+    from common.db.migrate import get_installed_query_names
+
+    try:
+        installed_names = sorted(get_installed_query_names(conn, graphname))
+    except Exception as exc:
+        logger.warning("get_installed_query_names failed: %s", exc)
+        installed_names = []
+    desc_by_name = dict(_fetch_description_rows(conn, graphname, installed_names))
+    if not installed_names:
+        installed_names = sorted(desc_by_name.keys())
+
+    registered: list[dict] = []
+    original: list[dict] = []
+    for name in installed_names:
+        desc = desc_by_name.get(name, "") or ""
+        if TOOL_MARKER in desc:
+            registered.append({
+                "function_header": name,
+                "description": strip_tool_marker(desc),
+            })
+        else:
+            original.append({
+                "function_header": name,
+                "description": desc.strip(),
+            })
+    logger.info(
+        "query catalog graph=%s registered=%s original=%s",
+        graphname,
+        [r["function_header"] for r in registered],
+        [o["function_header"] for o in original],
+    )
+    return {"registered": registered, "installed": original}
+
+
+def list_tagged_queries(conn, graphname: str) -> list[dict]:
+    """``SHOW DESCRIPTION OF QUERY *`` / ``getQueryDescription``, keep ``[GRAPHRAG_TOOL]``."""
+    return list_query_catalog(conn, graphname)["registered"]
+
+
+def _gsql_type_to_json(t: str) -> dict:
+    u = (t or "STRING").upper()
+    if u in ("INT", "UINT", "UINT64", "INT64"):
+        return {"type": "integer"}
+    if u in ("FLOAT", "DOUBLE"):
+        return {"type": "number"}
+    if u in ("BOOL", "BOOLEAN"):
+        return {"type": "boolean"}
+    if u.startswith("SET") or u.startswith("LIST") or u.startswith("BAG"):
+        return {"type": "array", "items": {"type": "string"}}
+    return {"type": "string"}
+
+
+def _iter_params(raw_input) -> list[tuple[str, str]]:
+    items: list[tuple[str, str]] = []
+    if isinstance(raw_input, dict):
+        for k, v in raw_input.items():
+            if isinstance(v, dict):
+                v = v.get("type") or v.get("paramType") or "STRING"
+            items.append((str(k), str(v)))
+        return items
+    if isinstance(raw_input, list):
+        for x in raw_input:
+            if isinstance(x, dict) and x:
+                k = list(x.keys())[0]
+                v = x[k]
+                if isinstance(v, dict):
+                    v = v.get("type") or v.get("paramType") or "STRING"
+                items.append((str(k), str(v)))
+            elif isinstance(x, str):
+                items.append((x, "STRING"))
+    return items
+
+
+def args_schema_for(conn, query_name: str) -> dict:
+    try:
+        meta = conn.getQueryMetadata(query_name) or {}
+        raw_input = meta.get("input") or []
+    except Exception as exc:
+        logger.warning("getQueryMetadata(%s) failed: %s", query_name, exc)
+        raw_input = []
+    props = {}
+    required = []
+    for pname, ptype in _iter_params(raw_input):
+        js = _gsql_type_to_json(str(ptype))
+        js["description"] = f"Parameter {pname} ({ptype})"
+        props[pname] = js
+        required.append(pname)
+    schema: dict[str, Any] = {"type": "object", "properties": props}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+def _result_is_empty(result: Any) -> bool:
+    if result is None:
+        return True
+    if isinstance(result, (list, dict, str)) and len(result) == 0:
+        return True
+    return False
+
+
+def _make_runner(query_name: str):
+    def _fn(ctx, **kwargs):
+        ctx.emit(f"Running registered query {query_name}")
+        try:
+            result = ctx.conn.runInstalledQuery(query_name, params=kwargs or {})
+        except Exception as exc:
+            logger.warning("registered query %s failed: %s", query_name, exc)
+            return {
+                "ok": False,
+                "summary": f"{query_name} failed: {exc}",
+                "context": None,
+                "citations": [],
+            }
+        if _result_is_empty(result):
+            return {
+                "ok": False,
+                "summary": f"{query_name} returned no rows",
+                "context": None,
+                "citations": [],
+            }
+        return {
+            "ok": True,
+            "summary": f"{query_name} returned results",
+            "context": {
+                "function_call": f"runInstalledQuery({query_name!r})",
+                "query_name": query_name,
+                "result": result,
+            },
+            "citations": [],
+        }
+
+    _fn.__name__ = f"run_{query_name}"
+    return _fn
+
+
+def discover_tagged_query_tools(conn, graphname: str) -> dict[str, ToolSpec]:
+    """Build a ToolSpec per tagged GSQL query. Empty dict on failure."""
+    try:
+        tagged = list_tagged_queries(conn, graphname)
+    except Exception as exc:
+        logger.warning("SHOW DESCRIPTION tagged-query list failed: %s", exc)
+        return {}
+    out: dict[str, ToolSpec] = {}
+    for row in tagged:
+        name = row.get("function_header") or ""
+        if not name:
+            continue
+        spec_name = tool_name_for(name)
+        out[spec_name] = ToolSpec(
+            name=spec_name,
+            description=row.get("description") or f"Run installed query {name}.",
+            args_schema_json=args_schema_for(conn, name),
+            fn=_make_runner(name),
+        )
+    return out