diff --git a/.claude/skills/graft/SKILL.md b/.claude/skills/graft/SKILL.md
index d4cbc72d..2dde4502 100644
--- a/.claude/skills/graft/SKILL.md
+++ b/.claude/skills/graft/SKILL.md
@@ -154,3 +154,14 @@ When the graft MCP server is connected, these are exposed as tools too:
 `graft_find_code`, `graft_find_all`, `graft_file_api`, `graft_trace_calls` (with
 `direction` / `depth`), `graft_repo_map`, `graft_check_freshness`. Use whichever surface is
 available; the guidance is identical.
+
+<!-- ranch:agent-tools:start -->
+## Project rule: agent tools
+
+A module is not done until the Ranch agent has tools for what the console
+can do. Before adding or changing an admin-console capability, read
+`docs/agent-tools.md`: tools live in the slice as `<name>.tool.ts` with
+`topic` / `title` / `template`, audience gating, `confirm` on anything
+destructive, no secrets in results, and a spec. The API refuses to boot a
+tool without that metadata.
+<!-- ranch:agent-tools:end -->
diff --git a/.specify/feature.json b/.specify/feature.json
index 1ce695e1..97590af0 100644
--- a/.specify/feature.json
+++ b/.specify/feature.json
@@ -1,3 +1,3 @@
 {
-  "feature_directory": "specs/015-chat-message-reliability"
+  "feature_directory": "specs/016-agent-tool-parity"
 }
diff --git a/CLAUDE.md b/CLAUDE.md
index 6a638a71..9546ef3e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -43,4 +43,12 @@ problem a day apart without meeting. A fix that lands in one console and leaves
 the other behind is half a fix, and the missing half is the one the user
 clicks.
 
+**Agent tools (`api`):** read `docs/agent-tools.md` before adding or changing
+any admin-console capability. The console is a window, the chat is the hands:
+a module is not done until the Ranch agent has a tool for what the console
+can do — in the slice, with `topic`/`title`/`template`, gated to the right
+audience, `confirm` on anything destructive, no secrets in results, and a spec.
+The API refuses to boot a tool without that metadata; the reviewer checks the
+rest against the checklist at the end of that doc.
+
 Project overview: `README.md`.
diff --git a/Makefile b/Makefile
index 44a1c152..b83cd0bd 100644
--- a/Makefile
+++ b/Makefile
@@ -13,6 +13,10 @@ help: ## Show this help
 
 init: ## Interactive setup wizard (local + optional Hetzner deploy)
 	@bash scripts/init.sh
+	@node scripts/ensure-agent-tools-rule.mjs
+
+agent-tools-rule: ## Re-insert the agent-tools rule pointer into graft-owned guidance files
+	@node scripts/ensure-agent-tools-rule.mjs
 
 setup: install db db-wait migrate k3d ## Full local setup (non-interactive)
 	@echo ""
diff --git a/README.md b/README.md
index 0f8e6e15..e89ad6ed 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,18 @@ Set `PUBLIC_API_URL` to the origin other agents reach this API on — every
 card URL is built from it. See `specs/013-a2a-agent-peers/` and
 `specs/014-a2a-protocol-upgrade/` for the full specifications.
 
+## Agent tools and the Tools panel
+
+The console is a window; the chat is the hands. Everything the admin console
+can do, the Ranch admin agent can do through a tool served by this API's own
+MCP server — agents, templates, skills, LLM credentials, MCP servers,
+knowledge bases and sources, settings, peers, paddock, users and API keys,
+chats and usage, browser sessions, upgrades. Press the wrench beside the chat
+composer to see the agent's tools grouped by topic; a click drops a starter
+prompt into the composer. Tools added after a pod started show "after restart"
+until it restarts. Adding a console capability means adding its tool in the
+same PR — see `docs/agent-tools.md` and `specs/016-agent-tool-parity/`.
+
 ## Project Structure
 
 ```
diff --git a/admin/slices/agent/agent/components/agent/chat/Tab.vue b/admin/slices/agent/agent/components/agent/chat/Tab.vue
index ba6dc70e..ad100150 100644
--- a/admin/slices/agent/agent/components/agent/chat/Tab.vue
+++ b/admin/slices/agent/agent/components/agent/chat/Tab.vue
@@ -144,6 +144,7 @@ watch(
         :agent-id="agent.id"
         :title="`Chat with ${agent.name}`"
         :restart-prompt="false"
+        :tools-button="false"
         :agent-state="bridleAgentState"
         :offline-hint="offlineHint"
         :initial-debug-enabled="agent.debugEnabled"
diff --git a/admin/slices/agent/agent/components/agent/workspace/Main.vue b/admin/slices/agent/agent/components/agent/workspace/Main.vue
index ab3db986..464cf82c 100644
--- a/admin/slices/agent/agent/components/agent/workspace/Main.vue
+++ b/admin/slices/agent/agent/components/agent/workspace/Main.vue
@@ -258,6 +258,7 @@ async function onRemove() {
             <IconRefresh v-else class="size-4" />
             {{ isRestarting ? 'Restarting…' : 'Restart' }}
           </Button>
+          <ToolCatalogButton :agent-id="agent.id" />
           <SharePanelProvider :agent-id="agent.id" />
           <Button variant="outline" size="sm" as-child>
             <NuxtLink :to="`/agents/${agent.id}/edit`">Edit</NuxtLink>
diff --git a/admin/slices/agent/toolCatalog/components/toolCatalog/Button.vue b/admin/slices/agent/toolCatalog/components/toolCatalog/Button.vue
new file mode 100644
index 00000000..8290ef8c
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/components/toolCatalog/Button.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { Wrench } from 'lucide-vue-next'
+import { Button } from '#theme/components/ui/button'
+import { useToolCatalogStore } from '../../stores/toolCatalog'
+
+/**
+ * Opens the Tools sheet for one agent (CLEAN-109). Sits in the page header
+ * beside Share and Edit; the sheet itself is mounted by the chat composer,
+ * which is the component that inserts the picked template.
+ */
+const props = withDefaults(
+  defineProps<{
+    agentId: string
+    size?: 'sm' | 'default'
+    class?: string
+  }>(),
+  { size: 'sm', class: undefined },
+)
+
+const store = useToolCatalogStore()
+const isOpen = computed(() => store.sheetOpenFor === props.agentId)
+</script>
+
+<template>
+  <Button
+    variant="outline"
+    :size="size"
+    :class="props.class"
+    :aria-expanded="isOpen"
+    title="What this agent can do — click a tool to drop a starter prompt into the chat"
+    @click="store.openSheet(agentId)"
+  >
+    <Wrench class="size-4" />
+    Tools
+  </Button>
+</template>
diff --git a/admin/slices/agent/toolCatalog/components/toolCatalog/Empty.vue b/admin/slices/agent/toolCatalog/components/toolCatalog/Empty.vue
new file mode 100644
index 00000000..11736e3d
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/components/toolCatalog/Empty.vue
@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import { AlertCircle, SearchX, Wrench } from 'lucide-vue-next'
+import { Skeleton } from '#theme/components/ui/skeleton'
+
+/** The panel's non-list states: loading, failed, no tools, no matches. */
+defineProps<{
+  kind: 'loading' | 'error' | 'empty' | 'no-results'
+  message?: string | null
+}>()
+
+const emit = defineEmits<{
+  retry: []
+  clear: []
+}>()
+</script>
+
+<template>
+  <div v-if="kind === 'loading'" class="flex flex-col gap-3 px-1 py-2" aria-busy="true">
+    <Skeleton v-for="i in 6" :key="i" class="h-9 w-full" />
+  </div>
+
+  <div
+    v-else-if="kind === 'error'"
+    class="flex flex-col items-start gap-2 rounded-md border border-destructive/40 bg-destructive/5 px-3 py-3 text-sm"
+    role="alert"
+  >
+    <span class="flex items-center gap-2 text-destructive">
+      <AlertCircle class="size-4 shrink-0" />
+      Could not load the tools.
+    </span>
+    <span v-if="message" class="text-xs text-muted-foreground">{{ message }}</span>
+    <button
+      type="button"
+      class="cursor-pointer rounded-md border px-2 py-1 text-xs font-medium transition-colors hover:bg-muted"
+      @click="emit('retry')"
+    >
+      Retry
+    </button>
+  </div>
+
+  <div
+    v-else-if="kind === 'no-results'"
+    class="flex flex-col items-center gap-2 px-3 py-8 text-center text-sm text-muted-foreground"
+  >
+    <SearchX class="size-6" />
+    <span>No tool matches that.</span>
+    <button
+      type="button"
+      class="cursor-pointer text-xs underline underline-offset-2 hover:no-underline"
+      @click="emit('clear')"
+    >
+      Clear the search
+    </button>
+  </div>
+
+  <div
+    v-else
+    class="flex flex-col items-center gap-2 px-3 py-8 text-center text-sm text-muted-foreground"
+  >
+    <Wrench class="size-6" />
+    <span>This agent has no tools from Ranch.</span>
+  </div>
+</template>
diff --git a/admin/slices/agent/toolCatalog/components/toolCatalog/Group.vue b/admin/slices/agent/toolCatalog/components/toolCatalog/Group.vue
new file mode 100644
index 00000000..1e68845b
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/components/toolCatalog/Group.vue
@@ -0,0 +1,98 @@
+<script setup lang="ts">
+import { Loader2, RotateCw } from 'lucide-vue-next'
+import {
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '#theme/components/ui/accordion'
+import type { IAgentToolGroup } from '#toolCatalog/domain'
+import Row from './Row.vue'
+
+/**
+ * One accordion of the panel: a topic of built-in tools, or an external MCP
+ * server the agent is attached to (whose tools the server itself provides).
+ * "After restart" on the header means the running pod lacks at least one
+ * tool here; the restart button reuses the agent store's normal flow.
+ */
+defineProps<{
+  group: IAgentToolGroup
+  restarting: boolean
+  canRestart: boolean
+}>()
+
+const emit = defineEmits<{
+  pick: [template: string]
+  restart: []
+}>()
+</script>
+
+<template>
+  <AccordionItem :value="group.key">
+    <!-- The trigger's default hover underline would run under the count and
+         the "after restart" badge too; underline the title alone. -->
+    <AccordionTrigger class="group py-2.5 hover:no-underline">
+      <span class="flex min-w-0 flex-1 flex-wrap items-center gap-x-2 gap-y-1">
+        <span class="truncate group-hover:underline">{{ group.title }}</span>
+        <span
+          v-if="group.kind === 'builtin'"
+          class="rounded-full bg-muted px-1.5 text-[10px] font-medium text-muted-foreground"
+        >
+          {{ group.tools.length }}
+        </span>
+        <span
+          v-else
+          class="rounded-full bg-muted px-1.5 text-[10px] font-medium uppercase tracking-wide text-muted-foreground"
+        >
+          MCP server
+        </span>
+        <span
+          v-if="group.afterRestart"
+          class="inline-flex items-center gap-1 rounded-full border border-orange-500/40 bg-orange-500/10 px-1.5 py-px text-[10px] font-medium text-orange-700 dark:text-orange-300"
+        >
+          <RotateCw class="size-3" />
+          after restart
+        </span>
+      </span>
+    </AccordionTrigger>
+    <AccordionContent class="pb-2">
+      <div
+        v-if="group.afterRestart"
+        class="mb-2 flex flex-wrap items-center justify-between gap-2 rounded-md border border-orange-500/40 bg-orange-500/10 px-2.5 py-2 text-xs text-orange-700 dark:text-orange-300"
+      >
+        <span>
+          {{
+            group.kind === 'builtin'
+              ? 'The running agent does not have the marked tools yet. You can still insert a prompt, but the agent cannot act on it until it restarts.'
+              : 'This server changed after the agent started. The agent connects to it after a restart.'
+          }}
+        </span>
+        <button
+          type="button"
+          :disabled="restarting || !canRestart"
+          class="inline-flex shrink-0 cursor-pointer items-center gap-1 rounded-md border border-orange-500/50 bg-background px-2 py-1 text-[11px] font-medium text-foreground transition-colors hover:bg-muted disabled:cursor-not-allowed disabled:opacity-50"
+          @click="emit('restart')"
+        >
+          <Loader2 v-if="restarting" class="size-3 animate-spin" />
+          <RotateCw v-else class="size-3" />
+          {{ restarting ? 'Restarting…' : 'Restart now' }}
+        </button>
+      </div>
+
+      <div v-if="group.kind === 'external'" class="px-2 text-xs text-muted-foreground">
+        <p v-if="group.description">{{ group.description }}</p>
+        <p class="mt-1">
+          Its tools are provided by the server itself; ask the agent what it can do
+          with it, or open the server on the MCP servers page.
+        </p>
+      </div>
+      <div v-else class="flex flex-col">
+        <Row
+          v-for="tool in group.tools"
+          :key="tool.name"
+          :tool="tool"
+          @pick="emit('pick', $event)"
+        />
+      </div>
+    </AccordionContent>
+  </AccordionItem>
+</template>
diff --git a/admin/slices/agent/toolCatalog/components/toolCatalog/Row.vue b/admin/slices/agent/toolCatalog/components/toolCatalog/Row.vue
new file mode 100644
index 00000000..cd58261f
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/components/toolCatalog/Row.vue
@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { ShieldAlert, RotateCw } from 'lucide-vue-next'
+import type { IAgentToolEntry } from '#toolCatalog/domain'
+
+/**
+ * One tool of the panel (CLEAN-109): a button so the keyboard reaches it,
+ * a human title first, the technical name in small type, the description in
+ * plain words. Click hands the starter template to the composer.
+ */
+defineProps<{
+  tool: IAgentToolEntry
+}>()
+
+const emit = defineEmits<{
+  pick: [template: string]
+}>()
+</script>
+
+<template>
+  <button
+    type="button"
+    class="group flex w-full cursor-pointer flex-col gap-1 rounded-md px-2 py-2 text-left transition-colors hover:bg-muted focus-visible:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50"
+    :class="tool.inPod === false ? 'opacity-70' : ''"
+    :title="tool.template"
+    @click="emit('pick', tool.template)"
+  >
+    <span class="flex flex-wrap items-center gap-x-2 gap-y-1">
+      <span class="text-sm font-medium text-foreground">{{ tool.title }}</span>
+      <span class="font-mono text-[11px] text-muted-foreground">{{ tool.name }}</span>
+      <span
+        v-if="tool.destructive"
+        class="inline-flex items-center gap-1 rounded-full border border-amber-500/40 bg-amber-500/10 px-1.5 py-px text-[10px] font-medium text-amber-700 dark:text-amber-300"
+        title="The agent asks you to confirm before running this."
+      >
+        <ShieldAlert class="size-3" />
+        asks first
+      </span>
+      <span
+        v-if="tool.inPod === false"
+        class="inline-flex items-center gap-1 rounded-full border border-orange-500/40 bg-orange-500/10 px-1.5 py-px text-[10px] font-medium text-orange-700 dark:text-orange-300"
+        title="The running agent does not have this tool yet. It will after a restart."
+      >
+        <RotateCw class="size-3" />
+        after restart
+      </span>
+    </span>
+    <span class="text-xs leading-snug text-muted-foreground line-clamp-3">
+      {{ tool.description }}
+    </span>
+  </button>
+</template>
diff --git a/admin/slices/agent/toolCatalog/components/toolCatalog/Sheet.vue b/admin/slices/agent/toolCatalog/components/toolCatalog/Sheet.vue
new file mode 100644
index 00000000..21126c21
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/components/toolCatalog/Sheet.vue
@@ -0,0 +1,202 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { Search, X } from 'lucide-vue-next'
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from '#theme/components/ui/sheet'
+import { Accordion } from '#theme/components/ui/accordion'
+import { Input } from '#theme/components/ui/input'
+import { ScrollArea } from '#theme/components/ui/scroll-area'
+import { useAgentStore } from '#agent/stores/agent'
+import { useToolCatalogStore } from '../../stores/toolCatalog'
+import { filterCatalog } from '../../utils/filterCatalog'
+import Group from './Group.vue'
+import Empty from './Empty.vue'
+
+/**
+ * The Tools panel (CLEAN-109): what this agent can do, by topic, one click
+ * from the composer. Renders the store's record for the agent — never the
+ * value a fetch returned — and keeps only loading state from useAsyncData
+ * (docs/state.md). Search text and open accordions live in the store per
+ * agent so reopening restores them.
+ */
+const props = defineProps<{
+  agentId: string
+  open: boolean
+}>()
+
+const emit = defineEmits<{
+  'update:open': [value: boolean]
+  pick: [template: string]
+}>()
+
+const store = useToolCatalogStore()
+const agentStore = useAgentStore()
+
+const catalog = computed(() => store.byAgent(props.agentId))
+const agent = computed(() => agentStore.byId(props.agentId))
+const ui = computed(() => store.uiOf(props.agentId))
+
+const { pending, error, refresh } = useAsyncData(
+  `admin-tool-catalog-${props.agentId}`,
+  () => store.fetchByAgent(props.agentId),
+  { immediate: false, server: false },
+)
+
+// Load on first open, and again on every open so a tool that landed since is
+// there; the cached record renders meanwhile, so nothing flickers.
+watch(
+  () => props.open,
+  (isOpen) => {
+    if (isOpen) void refresh()
+  },
+  { immediate: true },
+)
+
+// After a restart the pod lists again; re-read once the agent is back so the
+// "after restart" markers clear without a manual reopen.
+watch(
+  () => agent.value?.status,
+  (status, previous) => {
+    if (status === 'running' && previous && previous !== 'running' && props.open) {
+      void refresh()
+    }
+  },
+)
+
+const query = computed({
+  get: () => ui.value.query,
+  set: (value: string) => store.setQuery(props.agentId, value),
+})
+
+const groups = computed(() => filterCatalog(catalog.value, query.value))
+
+// While searching, every matching topic is open; otherwise the person's own
+// choice. Only an untouched sheet (`expanded === null`) opens the first topic
+// so the panel never looks empty — once the person collapses it, `[]` is a
+// choice and stays.
+const expanded = computed<string[]>({
+  get: () => {
+    if (query.value.trim()) return groups.value.map((g) => g.key)
+    if (ui.value.expanded !== null) return ui.value.expanded
+    return groups.value.length ? [groups.value[0].key] : []
+  },
+  set: (keys: string[]) => {
+    if (!query.value.trim()) store.setExpanded(props.agentId, keys)
+  },
+})
+
+const state = computed<'loading' | 'error' | 'empty' | 'no-results' | 'list'>(() => {
+  if (!catalog.value && pending.value) return 'loading'
+  if (!catalog.value && error.value) return 'error'
+  if (!catalog.value) return 'loading'
+  if (!catalog.value.groups.length) return 'empty'
+  if (!groups.value.length) return 'no-results'
+  return 'list'
+})
+
+const errorMessage = computed(() =>
+  error.value instanceof Error ? error.value.message : error.value ? String(error.value) : null,
+)
+
+const restarting = ref(false)
+const canRestart = computed(() => {
+  const status = agent.value?.status
+  return status === 'running' || status === 'failed' || status === 'unreachable'
+})
+
+async function restart() {
+  if (restarting.value) return
+  restarting.value = true
+  try {
+    await agentStore.restart(props.agentId)
+  } catch {
+    // The agent store already rolled the optimistic status back; the panel
+    // stays open so the person can try again.
+  } finally {
+    restarting.value = false
+  }
+}
+
+function pick(template: string) {
+  emit('pick', template)
+  emit('update:open', false)
+}
+
+const searchRef = ref<InstanceType<typeof Input> | null>(null)
+</script>
+
+<template>
+  <Sheet :open="open" @update:open="emit('update:open', $event)">
+    <SheetContent
+      side="right"
+      class="flex w-full flex-col gap-0 p-0 sm:max-w-md"
+      @open-auto-focus.prevent="searchRef?.$el?.focus?.()"
+    >
+      <SheetHeader class="gap-1 border-b px-4 pt-4 pb-3 text-left">
+        <SheetTitle class="text-base">Tools</SheetTitle>
+        <SheetDescription class="text-xs">
+          What {{ agent?.name ?? 'this agent' }} can do. Click a tool to drop a
+          starter prompt into the chat, then edit it freely.
+        </SheetDescription>
+        <div class="relative mt-2">
+          <Search class="pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2 text-muted-foreground" />
+          <!-- type="text", not "search": Chromium draws its own clear
+               button on search inputs, and the sheet already has one. -->
+          <Input
+            ref="searchRef"
+            v-model="query"
+            type="text"
+            autocomplete="off"
+            placeholder="Search tools…"
+            aria-label="Search tools"
+            class="h-9 pl-8 pr-8"
+          />
+          <button
+            v-if="query"
+            type="button"
+            aria-label="Clear search"
+            class="absolute top-1/2 right-2 -translate-y-1/2 cursor-pointer rounded-sm text-muted-foreground hover:text-foreground"
+            @click="query = ''"
+          >
+            <X class="size-4" />
+          </button>
+        </div>
+      </SheetHeader>
+
+      <ScrollArea class="min-h-0 flex-1">
+        <div class="px-4 py-2">
+          <Empty
+            v-if="state !== 'list'"
+            :kind="state"
+            :message="errorMessage"
+            @retry="refresh()"
+            @clear="query = ''"
+          />
+          <Accordion v-else v-model="expanded" type="multiple" class="w-full">
+            <Group
+              v-for="group in groups"
+              :key="group.key"
+              :group="group"
+              :restarting="restarting"
+              :can-restart="canRestart"
+              @pick="pick"
+              @restart="restart"
+            />
+          </Accordion>
+        </div>
+      </ScrollArea>
+
+      <p
+        v-if="catalog?.podStartedAt === null"
+        class="border-t px-4 py-2 text-[11px] text-muted-foreground"
+      >
+        The agent is not running. Tools are listed as they will be once it starts.
+      </p>
+    </SheetContent>
+  </Sheet>
+</template>
diff --git a/admin/slices/agent/toolCatalog/data/index.ts b/admin/slices/agent/toolCatalog/data/index.ts
new file mode 100644
index 00000000..f17b523a
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/data/index.ts
@@ -0,0 +1,2 @@
+export * from './toolCatalog.gateway';
+export * from './toolCatalog.mapper';
diff --git a/admin/slices/agent/toolCatalog/data/toolCatalog.gateway.ts b/admin/slices/agent/toolCatalog/data/toolCatalog.gateway.ts
new file mode 100644
index 00000000..2287238a
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/data/toolCatalog.gateway.ts
@@ -0,0 +1,43 @@
+import { AgentsService } from '#api/data';
+import type { AgentToolCatalogDto } from '#api/data/repositories/api/types.gen';
+import { BaseGateway } from '#common/data/BaseGateway';
+import { unwrapEnvelope } from '#common/data/unwrapEnvelope';
+import type { IAgentToolCatalog } from '../domain/toolCatalog.types';
+import { IToolCatalogGateway } from '../domain/toolCatalog.types';
+import { ToolCatalogMapper } from './toolCatalog.mapper';
+
+interface HeyApiResult {
+  data?: unknown;
+  error?: unknown;
+  response?: { status?: number };
+}
+
+/**
+ * The generated client answers a failed request with `{ error }` rather than
+ * throwing; the panel wants the sentence ("Agent not found", a 502), so the
+ * error is raised here instead of read as an empty catalogue.
+ */
+function unwrapOrThrow(res: HeyApiResult, action: string): unknown {
+  const err = res.error as { message?: string } | undefined;
+  if (err !== undefined && err !== null) {
+    const status = res.response?.status;
+    if (err.message) throw new Error(err.message);
+    if (status && status >= 400) throw new Error(`${action} failed: HTTP ${status}`);
+    throw new Error(`${action} failed: could not reach the API.`);
+  }
+  return unwrapEnvelope(res.data);
+}
+
+/** The only place the console reads an agent's tool catalogue (CLEAN-109). */
+export class ToolCatalogGateway extends BaseGateway implements IToolCatalogGateway {
+  private mapper = new ToolCatalogMapper();
+
+  forAgent(agentId: string): Promise<IAgentToolCatalog> {
+    return this.execute(async () => {
+      const res = await AgentsService.getAgentTools({ path: { id: agentId } });
+      const dto = unwrapOrThrow(res, 'Loading tools') as AgentToolCatalogDto | null;
+      if (!dto) throw new Error('Loading tools returned no data');
+      return this.mapper.toCatalog(dto);
+    });
+  }
+}
diff --git a/admin/slices/agent/toolCatalog/data/toolCatalog.mapper.ts b/admin/slices/agent/toolCatalog/data/toolCatalog.mapper.ts
new file mode 100644
index 00000000..028f8cd5
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/data/toolCatalog.mapper.ts
@@ -0,0 +1,57 @@
+import type {
+  AgentToolCatalogDto,
+  AgentToolEntryDto,
+  AgentToolGroupDto,
+} from '#api/data/repositories/api/types.gen';
+import type {
+  IAgentToolCatalog,
+  IAgentToolEntry,
+  IAgentToolGroup,
+} from '../domain/toolCatalog.types';
+
+const str = (v: unknown, fallback = ''): string =>
+  typeof v === 'string' ? v : fallback;
+
+/**
+ * DTO → domain, defensively: a missing field becomes an empty string or an
+ * empty list rather than an exception, because a half-broken catalogue is
+ * still a usable menu.
+ */
+export class ToolCatalogMapper {
+  toEntry(dto: AgentToolEntryDto): IAgentToolEntry {
+    return {
+      name: str(dto.name),
+      title: str(dto.title, str(dto.name)),
+      description: str(dto.description),
+      template: str(dto.template),
+      destructive: dto.destructive === true,
+      inPod:
+        dto.inPod === true ? true : dto.inPod === false ? false : null,
+    };
+  }
+
+  toGroup(dto: AgentToolGroupDto): IAgentToolGroup {
+    const tools = Array.isArray(dto.tools)
+      ? dto.tools.map((t) => this.toEntry(t))
+      : [];
+    return {
+      key: str(dto.key),
+      title: str(dto.title, str(dto.key)),
+      kind: dto.kind === 'external' ? 'external' : 'builtin',
+      ...(dto.description ? { description: dto.description } : {}),
+      afterRestart: dto.afterRestart === true,
+      tools,
+    };
+  }
+
+  toCatalog(dto: AgentToolCatalogDto): IAgentToolCatalog {
+    return {
+      agentId: str(dto.agentId),
+      podStartedAt: dto.podStartedAt ?? null,
+      listedAt: dto.listedAt ?? null,
+      groups: Array.isArray(dto.groups)
+        ? dto.groups.map((g) => this.toGroup(g))
+        : [],
+    };
+  }
+}
diff --git a/admin/slices/agent/toolCatalog/domain/index.ts b/admin/slices/agent/toolCatalog/domain/index.ts
new file mode 100644
index 00000000..684a863e
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/domain/index.ts
@@ -0,0 +1,2 @@
+export * from './toolCatalog.types';
+export * from './toolCatalog.service';
diff --git a/admin/slices/agent/toolCatalog/domain/toolCatalog.service.ts b/admin/slices/agent/toolCatalog/domain/toolCatalog.service.ts
new file mode 100644
index 00000000..cb256f03
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/domain/toolCatalog.service.ts
@@ -0,0 +1,10 @@
+import type { IAgentToolCatalog, IToolCatalogGateway } from './toolCatalog.types';
+
+/** Pass-through to the gateway, in the slice shape the console uses everywhere. */
+export class ToolCatalogService {
+  constructor(private readonly gateway: IToolCatalogGateway) {}
+
+  forAgent(agentId: string): Promise<IAgentToolCatalog> {
+    return this.gateway.forAgent(agentId);
+  }
+}
diff --git a/admin/slices/agent/toolCatalog/domain/toolCatalog.types.ts b/admin/slices/agent/toolCatalog/domain/toolCatalog.types.ts
new file mode 100644
index 00000000..fd868b0e
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/domain/toolCatalog.types.ts
@@ -0,0 +1,40 @@
+/**
+ * The chat's Tools panel (CLEAN-109): the tools this agent's runtime would
+ * receive, grouped by topic, plus its external MCP servers as opaque groups.
+ * Mirrors the API's AgentToolCatalogDto; see
+ * specs/016-agent-tool-parity/data-model.md §3.
+ */
+
+export type AgentToolGroupKinds = 'builtin' | 'external';
+
+export interface IAgentToolEntry {
+  name: string;
+  title: string;
+  description: string;
+  /** Starter prompt with «…» placeholders — a starter, not a form. */
+  template: string;
+  destructive: boolean;
+  /** null — no pod; false — the running pod did not list it; true — it did. */
+  inPod: boolean | null;
+}
+
+export interface IAgentToolGroup {
+  /** Topic key, or `mcp:<serverId>` for an external server. */
+  key: string;
+  title: string;
+  kind: AgentToolGroupKinds;
+  description?: string;
+  afterRestart: boolean;
+  tools: IAgentToolEntry[];
+}
+
+export interface IAgentToolCatalog {
+  agentId: string;
+  podStartedAt: string | null;
+  listedAt: string | null;
+  groups: IAgentToolGroup[];
+}
+
+export abstract class IToolCatalogGateway {
+  abstract forAgent(agentId: string): Promise<IAgentToolCatalog>;
+}
diff --git a/admin/slices/agent/toolCatalog/i18n/locales/en.json b/admin/slices/agent/toolCatalog/i18n/locales/en.json
new file mode 100644
index 00000000..0967ef42
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/i18n/locales/en.json
@@ -0,0 +1 @@
+{}
diff --git a/admin/slices/agent/toolCatalog/index.d.ts b/admin/slices/agent/toolCatalog/index.d.ts
new file mode 100644
index 00000000..0ea6b0b2
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/index.d.ts
@@ -0,0 +1,9 @@
+import type { ToolCatalogService } from './domain/toolCatalog.service';
+
+declare module '#app' {
+  interface NuxtApp {
+    $toolCatalogService: ToolCatalogService;
+  }
+}
+
+export {};
diff --git a/admin/slices/agent/toolCatalog/nuxt.config.ts b/admin/slices/agent/toolCatalog/nuxt.config.ts
new file mode 100644
index 00000000..56d3c4c4
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/nuxt.config.ts
@@ -0,0 +1,16 @@
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const currentDir = dirname(fileURLToPath(import.meta.url));
+
+export default defineNuxtConfig({
+  alias: { '#toolCatalog': currentDir },
+  imports: {
+    dirs: [`${currentDir}/stores`],
+  },
+  modules: ['@nuxtjs/i18n'],
+  i18n: {
+    langDir: 'locales',
+    locales: [{ code: 'en', file: 'en.json' }],
+  },
+});
diff --git a/admin/slices/agent/toolCatalog/plugins/di.ts b/admin/slices/agent/toolCatalog/plugins/di.ts
new file mode 100644
index 00000000..731f90b6
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/plugins/di.ts
@@ -0,0 +1,18 @@
+import { ToolCatalogGateway } from '../data/toolCatalog.gateway';
+import { ToolCatalogService } from '../domain/toolCatalog.service';
+
+/**
+ * Composition root for the tool catalogue slice (CLEAN-109). Provides
+ * `$toolCatalogService`.
+ */
+export default defineNuxtPlugin({
+  name: 'agent-tool-catalog-di',
+  setup() {
+    const service = new ToolCatalogService(new ToolCatalogGateway());
+    return {
+      provide: {
+        toolCatalogService: service,
+      },
+    };
+  },
+});
diff --git a/admin/slices/agent/toolCatalog/stores/toolCatalog.ts b/admin/slices/agent/toolCatalog/stores/toolCatalog.ts
new file mode 100644
index 00000000..52c647b4
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/stores/toolCatalog.ts
@@ -0,0 +1,98 @@
+import { createServiceGetter } from '#common/composables/createServiceGetter';
+import type { ToolCatalogService } from '#toolCatalog/domain';
+import type { IAgentToolCatalog } from '#toolCatalog/domain';
+
+export type {
+  IAgentToolCatalog,
+  IAgentToolEntry,
+  IAgentToolGroup,
+} from '#toolCatalog/domain';
+
+const getService = createServiceGetter<ToolCatalogService>('$toolCatalogService');
+
+export interface IToolCatalogUiState {
+  query: string;
+  /**
+   * Which accordions the person opened. `null` means they never touched
+   * them and the sheet may pick a default; `[]` means they closed every one
+   * — the two must stay distinct or the first group reopens on every collapse.
+   */
+  expanded: string[] | null;
+}
+
+const EMPTY_UI: IToolCatalogUiState = { query: '', expanded: null };
+
+/**
+ * One catalogue per agent (CLEAN-109), the entity the Tools panel renders.
+ * Keyed by agent id because the Rancher page and an agent's Chat tab can be
+ * open at once; sharing one record would show one agent the other's tools.
+ * The sheet's own state (search text, which accordions are open) lives here
+ * too, per agent, so reopening the sheet restores it within the session.
+ */
+export const useToolCatalogStore = defineStore('toolCatalog', () => {
+  const catalogs = ref<Record<string, IAgentToolCatalog>>({});
+  const ui = ref<Record<string, IToolCatalogUiState>>({});
+
+  // Which agent's sheet is open. The button lives in the page header, the
+  // sheet next to the composer it writes into; this is the one fact both
+  // read, so neither has to know about the other.
+  const sheetOpenFor = ref<string | null>(null);
+
+  function openSheet(agentId: string): void {
+    sheetOpenFor.value = agentId;
+  }
+
+  function closeSheet(): void {
+    sheetOpenFor.value = null;
+  }
+
+  function byAgent(agentId: string): IAgentToolCatalog | undefined {
+    return catalogs.value[agentId];
+  }
+
+  function upsert(catalog: IAgentToolCatalog): IAgentToolCatalog {
+    catalogs.value = { ...catalogs.value, [catalog.agentId]: catalog };
+    return catalogs.value[catalog.agentId];
+  }
+
+  /** Fetches upsert; the caller renders `byAgent`, never the return value. */
+  async function fetchByAgent(agentId: string): Promise<IAgentToolCatalog> {
+    const catalog = await getService().forAgent(agentId);
+    return upsert(catalog);
+  }
+
+  function uiOf(agentId: string): IToolCatalogUiState {
+    return ui.value[agentId] ?? EMPTY_UI;
+  }
+
+  function setQuery(agentId: string, query: string): void {
+    ui.value = { ...ui.value, [agentId]: { ...uiOf(agentId), query } };
+  }
+
+  function setExpanded(agentId: string, expanded: string[]): void {
+    ui.value = { ...ui.value, [agentId]: { ...uiOf(agentId), expanded } };
+  }
+
+  function toggleGroup(agentId: string, key: string): void {
+    const current = uiOf(agentId).expanded ?? [];
+    setExpanded(
+      agentId,
+      current.includes(key) ? current.filter((k) => k !== key) : [...current, key],
+    );
+  }
+
+  return {
+    catalogs,
+    ui,
+    sheetOpenFor,
+    openSheet,
+    closeSheet,
+    byAgent,
+    upsert,
+    fetchByAgent,
+    uiOf,
+    setQuery,
+    setExpanded,
+    toggleGroup,
+  };
+});
diff --git a/admin/slices/agent/toolCatalog/utils/filterCatalog.test.ts b/admin/slices/agent/toolCatalog/utils/filterCatalog.test.ts
new file mode 100644
index 00000000..9484b94c
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/utils/filterCatalog.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, test } from 'bun:test';
+import { filterCatalog } from './filterCatalog';
+import type { IAgentToolCatalog } from '../domain/toolCatalog.types';
+
+const tool = (name: string, title: string, description: string) => ({
+  name,
+  title,
+  description,
+  template: `Do «${name}»`,
+  destructive: false,
+  inPod: true as boolean | null,
+});
+
+const catalog: IAgentToolCatalog = {
+  agentId: 'a',
+  podStartedAt: null,
+  listedAt: null,
+  groups: [
+    {
+      key: 'agents',
+      title: 'Agents',
+      kind: 'builtin',
+      afterRestart: false,
+      tools: [
+        tool('list_agents', 'List agents', 'Every agent with status'),
+        tool('restart_agent', 'Restart an agent', 'Replace the pod'),
+      ],
+    },
+    {
+      key: 'mcp_servers',
+      title: 'MCP servers',
+      kind: 'builtin',
+      afterRestart: false,
+      tools: [tool('register_mcp_server', 'Register an MCP server', 'Add a server')],
+    },
+    {
+      key: 'mcp:srv-1',
+      title: 'GitHub',
+      kind: 'external',
+      description: 'GitHub MCP server',
+      afterRestart: false,
+      tools: [],
+    },
+  ],
+};
+
+describe('filterCatalog', () => {
+  test('returns everything for an empty query and nothing for no catalogue', () => {
+    expect(filterCatalog(catalog, '')).toBe(catalog.groups);
+    expect(filterCatalog(catalog, '   ')).toBe(catalog.groups);
+    expect(filterCatalog(undefined, 'x')).toEqual([]);
+  });
+
+  test('matches on title, name and description, case-insensitively, keeping only matching tools', () => {
+    const byName = filterCatalog(catalog, 'RESTART_agent');
+    expect(byName.map((g) => g.key)).toEqual(['agents']);
+    expect(byName[0].tools.map((t) => t.name)).toEqual(['restart_agent']);
+
+    const byDescription = filterCatalog(catalog, 'pod');
+    expect(byDescription[0].tools.map((t) => t.name)).toEqual(['restart_agent']);
+  });
+
+  test('matches across topics and external servers', () => {
+    const r = filterCatalog(catalog, 'mcp');
+    expect(r.map((g) => g.key)).toEqual(['mcp_servers', 'mcp:srv-1']);
+  });
+
+  test('requires every word to match', () => {
+    expect(filterCatalog(catalog, 'register server').map((g) => g.key)).toEqual(['mcp_servers']);
+    expect(filterCatalog(catalog, 'register nothing')).toEqual([]);
+  });
+
+  test('does not mutate the source groups', () => {
+    filterCatalog(catalog, 'restart');
+    expect(catalog.groups[0].tools.length).toBe(2);
+  });
+});
diff --git a/admin/slices/agent/toolCatalog/utils/filterCatalog.ts b/admin/slices/agent/toolCatalog/utils/filterCatalog.ts
new file mode 100644
index 00000000..a2e627ba
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/utils/filterCatalog.ts
@@ -0,0 +1,37 @@
+import type { IAgentToolCatalog, IAgentToolGroup } from '../domain/toolCatalog.types';
+
+const norm = (s: string): string => s.trim().toLowerCase();
+
+/**
+ * The panel's search (CLEAN-109): groups whose tools match the query on
+ * title, technical name or description, with only the matching tools kept.
+ * An external group matches on its own title and description. An empty
+ * query returns the groups untouched.
+ */
+export function filterCatalog(
+  catalog: IAgentToolCatalog | undefined,
+  query: string,
+): IAgentToolGroup[] {
+  if (!catalog) return [];
+  const q = norm(query);
+  if (!q) return catalog.groups;
+
+  const words = q.split(/\s+/).filter(Boolean);
+  const matches = (...fields: Array<string | undefined>): boolean => {
+    const hay = fields.map((f) => norm(f ?? '')).join(' ');
+    return words.every((w) => hay.includes(w));
+  };
+
+  const out: IAgentToolGroup[] = [];
+  for (const group of catalog.groups) {
+    if (group.kind === 'external') {
+      if (matches(group.title, group.description)) out.push(group);
+      continue;
+    }
+    const tools = group.tools.filter((t) =>
+      matches(t.title, t.name, t.description),
+    );
+    if (tools.length) out.push({ ...group, tools });
+  }
+  return out;
+}
diff --git a/admin/slices/agent/toolCatalog/utils/insertTemplate.test.ts b/admin/slices/agent/toolCatalog/utils/insertTemplate.test.ts
new file mode 100644
index 00000000..cbba7893
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/utils/insertTemplate.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  firstPlaceholderRange,
+  hasPlaceholder,
+  insertTemplate,
+} from './insertTemplate';
+
+describe('insertTemplate', () => {
+  test('inserts into an empty draft and selects the first placeholder', () => {
+    const r = insertTemplate('', 0, 'Restart the agent «name»');
+    expect(r.text).toBe('Restart the agent «name»');
+    expect(r.text.slice(r.selectionStart, r.selectionEnd)).toBe('«name»');
+  });
+
+  test('appends with a space after a draft that has no trailing whitespace', () => {
+    const r = insertTemplate('Please', 6, 'Restart the agent «name»');
+    expect(r.text).toBe('Please Restart the agent «name»');
+    expect(r.text.slice(r.selectionStart, r.selectionEnd)).toBe('«name»');
+  });
+
+  test('does not double a space that is already there', () => {
+    const r = insertTemplate('Please ', 7, 'Do «x»');
+    expect(r.text).toBe('Please Do «x»');
+  });
+
+  test('inserts mid-draft with spaces on both sides', () => {
+    const r = insertTemplate('ab', 1, 'Do «x»');
+    expect(r.text).toBe('a Do «x» b');
+    expect(r.text.slice(r.selectionStart, r.selectionEnd)).toBe('«x»');
+  });
+
+  test('selects the end of the insertion when the template has no placeholder', () => {
+    const r = insertTemplate('', 0, 'List all agents');
+    expect(r.selectionStart).toBe(r.selectionEnd);
+    expect(r.selectionStart).toBe('List all agents'.length);
+  });
+
+  test('picks the first placeholder of the inserted text, not one from the draft', () => {
+    const r = insertTemplate('«old» ', 6, 'Do «new»');
+    expect(r.text.slice(r.selectionStart, r.selectionEnd)).toBe('«new»');
+  });
+
+  test('clamps a cursor outside the draft', () => {
+    expect(insertTemplate('ab', 99, 'x').text).toBe('ab x');
+    expect(insertTemplate('ab', -5, 'x').text).toBe('x ab');
+  });
+});
+
+describe('placeholders', () => {
+  test('finds ranges and reports presence', () => {
+    expect(firstPlaceholderRange('a «b» c')).toEqual([2, 5]);
+    expect(firstPlaceholderRange('a «b» c', 3)).toBe(null);
+    expect(hasPlaceholder('none')).toBe(false);
+    expect(hasPlaceholder('«»')).toBe(true);
+  });
+});
diff --git a/admin/slices/agent/toolCatalog/utils/insertTemplate.ts b/admin/slices/agent/toolCatalog/utils/insertTemplate.ts
new file mode 100644
index 00000000..275dab44
--- /dev/null
+++ b/admin/slices/agent/toolCatalog/utils/insertTemplate.ts
@@ -0,0 +1,59 @@
+/**
+ * Dropping a tool's starter template into the composer (CLEAN-109). Pure so
+ * it can be tested without a textarea. The template is a starter, not a
+ * form: the person keeps editing after it lands.
+ */
+
+export interface IInsertion {
+  text: string;
+  selectionStart: number;
+  selectionEnd: number;
+}
+
+const PLACEHOLDER = /«[^»]*»/;
+
+/** [start, end) of the first «…» at or after `from`, or null. */
+export function firstPlaceholderRange(
+  text: string,
+  from = 0,
+): [number, number] | null {
+  const match = PLACEHOLDER.exec(text.slice(from));
+  if (!match) return null;
+  const start = from + match.index;
+  return [start, start + match[0].length];
+}
+
+export function hasPlaceholder(text: string): boolean {
+  return PLACEHOLDER.test(text);
+}
+
+/**
+ * Inserts `template` at `cursor` in `draft`, with a space on either side when
+ * the neighbouring text does not already provide one. The selection lands on
+ * the first placeholder of the inserted text so the person can type over it,
+ * or at the end of the insertion when there is none.
+ */
+export function insertTemplate(
+  draft: string,
+  cursor: number,
+  template: string,
+): IInsertion {
+  const at = Math.max(0, Math.min(cursor, draft.length));
+  const before = draft.slice(0, at);
+  const after = draft.slice(at);
+
+  const needsLeading = before.length > 0 && !/\s$/.test(before);
+  const needsTrailing = after.length > 0 && !/^\s/.test(after);
+
+  const inserted = (needsLeading ? ' ' : '') + template + (needsTrailing ? ' ' : '');
+  const text = before + inserted + after;
+
+  const insertionStart = before.length + (needsLeading ? 1 : 0);
+  const insertionEnd = insertionStart + template.length;
+
+  const range = firstPlaceholderRange(text, insertionStart);
+  if (range && range[0] < insertionEnd) {
+    return { text, selectionStart: range[0], selectionEnd: range[1] };
+  }
+  return { text, selectionStart: insertionEnd, selectionEnd: insertionEnd };
+}
diff --git a/admin/slices/bridle/components/bridle/Input.vue b/admin/slices/bridle/components/bridle/Input.vue
index fc3d4f19..cdaec2db 100644
--- a/admin/slices/bridle/components/bridle/Input.vue
+++ b/admin/slices/bridle/components/bridle/Input.vue
@@ -1,10 +1,16 @@
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { computed, nextTick, ref } from 'vue'
 import { Textarea } from '#theme/components/ui/textarea'
 import { Button } from '#theme/components/ui/button'
 import { AlertCircle, Paperclip, Send } from 'lucide-vue-next'
 import { bridleKey, useBridleStore } from '../../stores/bridle'
 import AttachmentChip from './AttachmentChip.vue'
+import ToolCatalogSheet from '#toolCatalog/components/toolCatalog/Sheet.vue'
+import { useToolCatalogStore } from '#toolCatalog/stores/toolCatalog'
+import {
+  hasPlaceholder,
+  insertTemplate,
+} from '#toolCatalog/utils/insertTemplate'
 import {
   FILE_PICKER_ACCEPT,
   MAX_ATTACHMENTS_PER_MESSAGE,
@@ -63,6 +69,44 @@ const handleSend = () => {
   textareaRef.value?.$el?.focus()
 }
 
+// ─── Tools panel (CLEAN-109) ─────────────────────────────────────────────
+// The sheet lives here, not in the Provider, because the draft does: picking
+// a tool must write into `input` and move the caret, and nothing else owns
+// those. The button that opens it sits in the page header (ToolCatalogButton)
+// and talks to the composer through the store. A template is a starter, not
+// a form — it lands at the caret and the person keeps typing.
+const toolCatalog = useToolCatalogStore()
+const toolsOpen = computed({
+  get: () => toolCatalog.sheetOpenFor === props.agentId,
+  set: (open: boolean) => {
+    if (open) toolCatalog.openSheet(props.agentId)
+    else if (toolCatalog.sheetOpenFor === props.agentId) toolCatalog.closeSheet()
+  },
+})
+
+const textareaEl = (): HTMLTextAreaElement | null => {
+  const el = textareaRef.value?.$el as HTMLTextAreaElement | undefined
+  return el && typeof el.setSelectionRange === 'function' ? el : null
+}
+
+const onPickTemplate = (template: string) => {
+  const el = textareaEl()
+  const cursor = el?.selectionStart ?? input.value.length
+  const insertion = insertTemplate(input.value, cursor, template)
+  input.value = insertion.text
+  toolsOpen.value = false
+  void nextTick(() => {
+    const target = textareaEl()
+    if (!target) return
+    target.focus()
+    target.setSelectionRange(insertion.selectionStart, insertion.selectionEnd)
+  })
+}
+
+// A «…» left in the draft is allowed — the agent will ask — but it is shown,
+// so nobody sends "Restart the agent «name»" by accident.
+const draftHasPlaceholder = computed(() => hasPlaceholder(input.value))
+
 const handleKeydown = (e: KeyboardEvent) => {
   if (e.key === 'Enter' && !e.shiftKey) {
     e.preventDefault()
@@ -131,12 +175,20 @@ const onPaste = (event: ClipboardEvent) => {
         @change="onFilesPicked"
       >
 
+      <ToolCatalogSheet
+        v-model:open="toolsOpen"
+        :agent-id="agentId"
+        @pick="onPickTemplate"
+      />
+
       <Textarea
         ref="textareaRef"
         v-model="input"
         :placeholder="placeholder"
         :disabled="disabled"
         class="min-h-[40px] max-h-[120px] resize-none"
+        :class="draftHasPlaceholder ? 'ring-1 ring-amber-500/50' : ''"
+        :title="draftHasPlaceholder ? 'Fill in the «…» placeholders, or send as is and the agent will ask.' : undefined"
         :rows="1"
         @keydown="handleKeydown"
         @paste="onPaste"
diff --git a/admin/slices/bridle/components/bridle/Provider.vue b/admin/slices/bridle/components/bridle/Provider.vue
index 0a42566c..c325e87d 100644
--- a/admin/slices/bridle/components/bridle/Provider.vue
+++ b/admin/slices/bridle/components/bridle/Provider.vue
@@ -6,6 +6,7 @@ import { buildChatFlow, type IChatFlowDayItem } from '../../utils/chatFlow'
 import Message from './Message.vue'
 import Input from './Input.vue'
 import DropZone from './DropZone.vue'
+import ToolCatalogButton from '#toolCatalog/components/toolCatalog/Button.vue'
 import DebugPanel from './DebugPanel.vue'
 import { Card, CardContent, CardFooter, CardHeader } from '#theme/components/ui/card'
 import { ScrollArea } from '#theme/components/ui/scroll-area'
@@ -31,6 +32,9 @@ const props = withDefaults(defineProps<{
   // Hosts with their own restart controls (the admin agent page) turn the
   // header's built-in restart prompt off to keep the header uncluttered.
   restartPrompt?: boolean
+  // The Tools button (CLEAN-109). Hosts with their own header actions (the
+  // admin agent page puts it beside Share and Edit) turn this one off.
+  toolsButton?: boolean
   // Host-supplied reconciled agent state. The WS alone can't tell the truth
   // fast enough: after a restart the OLD pod keeps its socket alive for a few
   // seconds ("Connected" while the pod is dying), and on a freshly opened
@@ -54,6 +58,7 @@ const props = withDefaults(defineProps<{
   placeholder: 'Type a message...',
   showStatus: true,
   restartPrompt: true,
+  toolsButton: true,
   agentState: null,
   offlineHint: null,
   initialDebugEnabled: null,
@@ -523,6 +528,11 @@ async function onConfirmReset() {
         <h3 class="font-semibold text-sm">{{ title }}</h3>
       </div>
       <div class="flex items-center gap-3">
+        <ToolCatalogButton
+          v-if="toolsButton"
+          :agent-id="agentId"
+          class="h-7 px-2 text-xs"
+        />
         <Button
           v-if="showRestartPrompt"
           variant="outline"
diff --git a/admin/slices/setup/api/data/repositories/api/schemas.gen.ts b/admin/slices/setup/api/data/repositories/api/schemas.gen.ts
index dd472f65..4b4c4be0 100644
--- a/admin/slices/setup/api/data/repositories/api/schemas.gen.ts
+++ b/admin/slices/setup/api/data/repositories/api/schemas.gen.ts
@@ -429,7 +429,13 @@ export const KnowledgeListItemDtoSchema = {
     },
     failedCount: {
       type: "number",
-      description: "Sources whose last index run recorded an error",
+      description:
+        "Sources whose last index run recorded an error nothing will retry without a person",
+    },
+    retryingCount: {
+      type: "number",
+      description:
+        "Sources that failed for a reason that passes (a model outage, a lost connection) and are retried automatically",
     },
     processingCount: {
       type: "number",
@@ -479,6 +485,7 @@ export const KnowledgeListItemDtoSchema = {
     "sourceCount",
     "indexedCount",
     "failedCount",
+    "retryingCount",
     "processingCount",
     "indexRunAlive",
     "instanceState",
@@ -627,6 +634,11 @@ export const KnowledgeOverviewDtoSchema = {
     },
     failedCount: {
       type: "number",
+      description: "Failed, and nothing will retry them by itself",
+    },
+    retryingCount: {
+      type: "number",
+      description: "Failed for a passing reason; retried automatically",
     },
     processingCount: {
       type: "number",
@@ -644,6 +656,7 @@ export const KnowledgeOverviewDtoSchema = {
     "sourceCount",
     "indexedCount",
     "failedCount",
+    "retryingCount",
     "processingCount",
     "byType",
     "totalSizeBytes",
@@ -786,7 +799,7 @@ export const SourceDtoSchema = {
     },
     indexStatus: {
       type: "string",
-      enum: ["indexed", "pending", "failed"],
+      enum: ["indexed", "pending", "retrying", "failed"],
     },
     indexState: {
       type: "string",
@@ -802,6 +815,17 @@ export const SourceDtoSchema = {
       type: "string",
       nullable: true,
     },
+    indexAttempts: {
+      type: "number",
+      description:
+        "Failed attempts since the source last indexed or was retried by hand; the reconciler stops retrying after three.",
+    },
+    indexRetryAt: {
+      type: "string",
+      nullable: true,
+      description:
+        "When the reconciler will retry a failed source on its own; null once it will not (permanent failure, or the retries are spent).",
+    },
     textState: {
       type: "string",
       enum: ["none", "pending", "ready", "failed"],
@@ -835,6 +859,8 @@ export const SourceDtoSchema = {
     "indexState",
     "indexError",
     "indexedAt",
+    "indexAttempts",
+    "indexRetryAt",
     "textState",
     "textError",
     "createdAt",
@@ -1193,6 +1219,12 @@ export const AgentPodStatusDtoSchema = {
       nullable: true,
       example: "2026-04-30T10:15:00Z",
     },
+    terminating: {
+      type: "boolean",
+      example: false,
+      description:
+        "The pod is being deleted (restart cleanup, stop, manual delete). Its phase on the way out says nothing about the health of the agent.",
+    },
     lastTerminationReason: {
       type: "string",
       nullable: true,
@@ -1219,6 +1251,7 @@ export const AgentPodStatusDtoSchema = {
     "ready",
     "restartCount",
     "startedAt",
+    "terminating",
     "lastTerminationReason",
     "containerWaitingReason",
     "message",
@@ -3372,7 +3405,7 @@ export const AgentDelegationDtoSchema = {
       type: "string",
       nullable: true,
       description:
-        "Why it did not produce an answer: PEER_NOT_RUNNING, PEER_TIMEOUT, PEER_REJECTED_LOOP, PEER_REJECTED_DEPTH, PEER_UNAUTHORIZED, PEER_UNREACHABLE or PEER_ERROR. Null while waiting and on success.",
+        "Why it did not produce an answer: PEER_NOT_RUNNING, PEER_TIMEOUT, PEER_REJECTED_LOOP, PEER_REJECTED_DEPTH, PEER_UNAUTHORIZED, PEER_UNREACHABLE, PEER_ADDRESS_REFUSED (the card points at a private or local address, so nothing was sent), PEER_UNSUPPORTED (the card offers no JSON-RPC interface on A2A 1.0) or PEER_ERROR. Null while waiting and on success — including an empty reply, which is answered.",
       example: null,
     },
     excerpt: {
@@ -3415,6 +3448,117 @@ export const AgentDelegationDtoSchema = {
   ],
 } as const;
 
+export const AgentToolEntryDtoSchema = {
+  type: "object",
+  properties: {
+    name: {
+      type: "string",
+      description: "Technical MCP tool name.",
+      example: "register_mcp_server",
+    },
+    title: {
+      type: "string",
+      example: "Register an MCP server",
+    },
+    description: {
+      type: "string",
+      description:
+        "The per-caller description, exactly what the runtime would be given.",
+    },
+    template: {
+      type: "string",
+      description: "Starter prompt with «…» placeholders.",
+      example: "Register the MCP server at «url» named «name»",
+    },
+    destructive: {
+      type: "boolean",
+      description:
+        "The tool removes, revokes or interrupts something and needs confirm: true.",
+    },
+    inPod: {
+      type: "boolean",
+      nullable: true,
+      description:
+        "null — no pod runs; false — the running pod did not list this tool (restart needed); true — it did.",
+    },
+  },
+  required: [
+    "name",
+    "title",
+    "description",
+    "template",
+    "destructive",
+    "inPod",
+  ],
+} as const;
+
+export const AgentToolGroupDtoSchema = {
+  type: "object",
+  properties: {
+    key: {
+      type: "string",
+      description:
+        "Topic key (e.g. mcp_servers) or mcp:<serverId> for an external server.",
+      example: "mcp_servers",
+    },
+    title: {
+      type: "string",
+      example: "MCP servers",
+    },
+    kind: {
+      type: "string",
+      enum: ["builtin", "external"],
+    },
+    description: {
+      type: "string",
+      description:
+        "External servers only — the server row's description. Never its url or auth value.",
+    },
+    afterRestart: {
+      type: "boolean",
+      description:
+        "builtin — at least one tool has inPod=false; external — the server row changed after the pod started.",
+    },
+    tools: {
+      description:
+        "Empty for external groups; their tools are served by the server itself.",
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/AgentToolEntryDto",
+      },
+    },
+  },
+  required: ["key", "title", "kind", "afterRestart", "tools"],
+} as const;
+
+export const AgentToolCatalogDtoSchema = {
+  type: "object",
+  properties: {
+    agentId: {
+      type: "string",
+    },
+    podStartedAt: {
+      type: "string",
+      nullable: true,
+      description: "When the current pod started; null when no pod runs.",
+      example: "2026-09-22T10:33:00.000Z",
+    },
+    listedAt: {
+      type: "string",
+      nullable: true,
+      description: "When the pod last called tools/list; null if it never did.",
+      example: "2026-09-22T10:33:05.000Z",
+    },
+    groups: {
+      type: "array",
+      items: {
+        $ref: "#/components/schemas/AgentToolGroupDto",
+      },
+    },
+  },
+  required: ["agentId", "podStartedAt", "listedAt", "groups"],
+} as const;
+
 export const SecretEntryDtoSchema = {
   type: "object",
   properties: {
diff --git a/admin/slices/setup/api/data/repositories/api/sdk.gen.ts b/admin/slices/setup/api/data/repositories/api/sdk.gen.ts
index 4eba3d9d..e1877eeb 100644
--- a/admin/slices/setup/api/data/repositories/api/sdk.gen.ts
+++ b/admin/slices/setup/api/data/repositories/api/sdk.gen.ts
@@ -230,6 +230,8 @@ import type {
   RemoveAgentPeerResponse,
   ListAgentDelegationsData,
   ListAgentDelegationsResponse,
+  GetAgentToolsData,
+  GetAgentToolsResponse,
   SecretControllerDeleteData,
   SecretControllerDeleteResponse,
   SecretControllerListData,
@@ -1814,6 +1816,22 @@ export class AgentsService {
       },
     });
   }
+
+  /**
+   * The tools this agent's runtime would receive from the built-in Ranch MCP server, grouped by topic for the chat's Tools panel, with a per-tool "present in the running pod" flag, plus the agent's external MCP servers as opaque groups. Owner or Admin only; agent tokens get their list from MCP tools/list instead (CLEAN-109).
+   */
+  public static getAgentTools<ThrowOnError extends boolean = false>(
+    options: Options<GetAgentToolsData, ThrowOnError>,
+  ) {
+    return (options.client ?? _heyApiClient).get<
+      GetAgentToolsResponse,
+      unknown,
+      ThrowOnError
+    >({
+      url: "/agents/{id}/tools",
+      ...options,
+    });
+  }
 }
 
 export class FilesService {
diff --git a/admin/slices/setup/api/data/repositories/api/types.gen.ts b/admin/slices/setup/api/data/repositories/api/types.gen.ts
index 38a7ef3b..b1a9b615 100644
--- a/admin/slices/setup/api/data/repositories/api/types.gen.ts
+++ b/admin/slices/setup/api/data/repositories/api/types.gen.ts
@@ -192,9 +192,13 @@ export type KnowledgeListItemDto = {
    */
   indexedCount: number;
   /**
-   * Sources whose last index run recorded an error
+   * Sources whose last index run recorded an error nothing will retry without a person
    */
   failedCount: number;
+  /**
+   * Sources that failed for a reason that passes (a model outage, a lost connection) and are retried automatically
+   */
+  retryingCount: number;
   /**
    * Sources handed to LightRAG that it has not finished processing. A ready knowledge with a non-zero count is searchable but not complete yet; run Index again once the pipeline drains.
    */
@@ -262,7 +266,14 @@ export type KnowledgeOverviewDto = {
    * Sources LightRAG confirmed as processed
    */
   indexedCount: number;
+  /**
+   * Failed, and nothing will retry them by itself
+   */
   failedCount: number;
+  /**
+   * Failed for a passing reason; retried automatically
+   */
+  retryingCount: number;
   /**
    * Handed to LightRAG and still in its pipeline
    */
@@ -324,13 +335,21 @@ export type SourceDto = {
    * True when indexStatus is "indexed". Kept for older callers.
    */
   indexed: boolean;
-  indexStatus: "indexed" | "pending" | "failed";
+  indexStatus: "indexed" | "pending" | "retrying" | "failed";
   indexState: "queued" | "processing" | "indexed" | "failed";
   /**
    * Error from the last index run, null once the source indexes.
    */
   indexError: string | null;
   indexedAt: string | null;
+  /**
+   * Failed attempts since the source last indexed or was retried by hand; the reconciler stops retrying after three.
+   */
+  indexAttempts: number;
+  /**
+   * When the reconciler will retry a failed source on its own; null once it will not (permanent failure, or the retries are spent).
+   */
+  indexRetryAt: string | null;
   /**
    * Text extraction for a PDF without a text layer: none (not a PDF, or it has its own text), pending (probing or OCR running), ready (recognised text is what gets indexed), failed (see textError).
    */
@@ -493,6 +512,10 @@ export type AgentPodStatusDto = {
   ready: boolean;
   restartCount: number;
   startedAt: string | null;
+  /**
+   * The pod is being deleted (restart cleanup, stop, manual delete). Its phase on the way out says nothing about the health of the agent.
+   */
+  terminating: boolean;
   lastTerminationReason: string | null;
   containerWaitingReason: string | null;
   message: string | null;
@@ -1553,7 +1576,7 @@ export type AgentDelegationDto = {
    */
   status: string;
   /**
-   * Why it did not produce an answer: PEER_NOT_RUNNING, PEER_TIMEOUT, PEER_REJECTED_LOOP, PEER_REJECTED_DEPTH, PEER_UNAUTHORIZED, PEER_UNREACHABLE or PEER_ERROR. Null while waiting and on success.
+   * Why it did not produce an answer: PEER_NOT_RUNNING, PEER_TIMEOUT, PEER_REJECTED_LOOP, PEER_REJECTED_DEPTH, PEER_UNAUTHORIZED, PEER_UNREACHABLE, PEER_ADDRESS_REFUSED (the card points at a private or local address, so nothing was sent), PEER_UNSUPPORTED (the card offers no JSON-RPC interface on A2A 1.0) or PEER_ERROR. Null while waiting and on success — including an empty reply, which is answered.
    */
   errorCode: string | null;
   /**
@@ -1565,6 +1588,64 @@ export type AgentDelegationDto = {
   durationMs: number | null;
 };
 
+export type AgentToolEntryDto = {
+  /**
+   * Technical MCP tool name.
+   */
+  name: string;
+  title: string;
+  /**
+   * The per-caller description, exactly what the runtime would be given.
+   */
+  description: string;
+  /**
+   * Starter prompt with «…» placeholders.
+   */
+  template: string;
+  /**
+   * The tool removes, revokes or interrupts something and needs confirm: true.
+   */
+  destructive: boolean;
+  /**
+   * null — no pod runs; false — the running pod did not list this tool (restart needed); true — it did.
+   */
+  inPod: boolean | null;
+};
+
+export type AgentToolGroupDto = {
+  /**
+   * Topic key (e.g. mcp_servers) or mcp:<serverId> for an external server.
+   */
+  key: string;
+  title: string;
+  kind: "builtin" | "external";
+  /**
+   * External servers only — the server row's description. Never its url or auth value.
+   */
+  description?: string;
+  /**
+   * builtin — at least one tool has inPod=false; external — the server row changed after the pod started.
+   */
+  afterRestart: boolean;
+  /**
+   * Empty for external groups; their tools are served by the server itself.
+   */
+  tools: Array<AgentToolEntryDto>;
+};
+
+export type AgentToolCatalogDto = {
+  agentId: string;
+  /**
+   * When the current pod started; null when no pod runs.
+   */
+  podStartedAt: string | null;
+  /**
+   * When the pod last called tools/list; null if it never did.
+   */
+  listedAt: string | null;
+  groups: Array<AgentToolGroupDto>;
+};
+
 export type SecretEntryDto = {
   name: string;
   value: string;
@@ -2592,7 +2673,7 @@ export type GetKnowledgeSourcesData = {
      * Case-insensitive substring match on the source name
      */
     search?: string;
-    status?: "indexed" | "pending" | "failed";
+    status?: "indexed" | "pending" | "retrying" | "failed";
     type?: "file" | "url" | "text";
     page?: number;
     perPage?: number;
@@ -2650,7 +2731,7 @@ export type ExportKnowledgeSourcesData = {
      * Case-insensitive substring match on the source name
      */
     search?: string;
-    status?: "indexed" | "pending" | "failed";
+    status?: "indexed" | "pending" | "retrying" | "failed";
     type?: "file" | "url" | "text";
   };
   url: "/knowledges/{knowledgeId}/sources/export";
@@ -4662,6 +4743,22 @@ export type ListAgentDelegationsResponses = {
 export type ListAgentDelegationsResponse =
   ListAgentDelegationsResponses[keyof ListAgentDelegationsResponses];
 
+export type GetAgentToolsData = {
+  body?: never;
+  path: {
+    id: string;
+  };
+  query?: never;
+  url: "/agents/{id}/tools";
+};
+
+export type GetAgentToolsResponses = {
+  200: AgentToolCatalogDto;
+};
+
+export type GetAgentToolsResponse =
+  GetAgentToolsResponses[keyof GetAgentToolsResponses];
+
 export type SecretControllerDeleteData = {
   body: DeleteSecretDto;
   path: {
diff --git a/admin/slices/setup/theme/components/ui/accordion/Accordion.vue b/admin/slices/setup/theme/components/ui/accordion/Accordion.vue
new file mode 100644
index 00000000..8fa390a1
--- /dev/null
+++ b/admin/slices/setup/theme/components/ui/accordion/Accordion.vue
@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import type { AccordionRootEmits, AccordionRootProps } from "reka-ui"
+import { AccordionRoot, useForwardPropsEmits } from "reka-ui"
+
+const props = defineProps<AccordionRootProps>()
+const emits = defineEmits<AccordionRootEmits>()
+
+const forwarded = useForwardPropsEmits(props, emits)
+</script>
+
+<template>
+  <AccordionRoot data-slot="accordion" v-bind="forwarded">
+    <slot />
+  </AccordionRoot>
+</template>
diff --git a/admin/slices/setup/theme/components/ui/accordion/AccordionContent.vue b/admin/slices/setup/theme/components/ui/accordion/AccordionContent.vue
new file mode 100644
index 00000000..173d7a74
--- /dev/null
+++ b/admin/slices/setup/theme/components/ui/accordion/AccordionContent.vue
@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import type { AccordionContentProps } from "reka-ui"
+import type { HTMLAttributes } from "vue"
+import { reactiveOmit } from "@vueuse/core"
+import { AccordionContent } from "reka-ui"
+import { cn } from '#theme/utils'
+
+const props = defineProps<AccordionContentProps & { class?: HTMLAttributes["class"] }>()
+
+const delegatedProps = reactiveOmit(props, "class")
+</script>
+
+<template>
+  <AccordionContent
+    data-slot="accordion-content"
+    v-bind="delegatedProps"
+    class="overflow-hidden text-sm"
+  >
+    <div :class="cn('pt-0 pb-3', props.class)">
+      <slot />
+    </div>
+  </AccordionContent>
+</template>
diff --git a/admin/slices/setup/theme/components/ui/accordion/AccordionItem.vue b/admin/slices/setup/theme/components/ui/accordion/AccordionItem.vue
new file mode 100644
index 00000000..ce88498c
--- /dev/null
+++ b/admin/slices/setup/theme/components/ui/accordion/AccordionItem.vue
@@ -0,0 +1,22 @@
+<script setup lang="ts">
+import type { AccordionItemProps } from "reka-ui"
+import type { HTMLAttributes } from "vue"
+import { reactiveOmit } from "@vueuse/core"
+import { AccordionItem, useForwardProps } from "reka-ui"
+import { cn } from '#theme/utils'
+
+const props = defineProps<AccordionItemProps & { class?: HTMLAttributes["class"] }>()
+
+const delegatedProps = reactiveOmit(props, "class")
+const forwardedProps = useForwardProps(delegatedProps)
+</script>
+
+<template>
+  <AccordionItem
+    data-slot="accordion-item"
+    v-bind="forwardedProps"
+    :class="cn('border-b last:border-b-0', props.class)"
+  >
+    <slot />
+  </AccordionItem>
+</template>
diff --git a/admin/slices/setup/theme/components/ui/accordion/AccordionTrigger.vue b/admin/slices/setup/theme/components/ui/accordion/AccordionTrigger.vue
new file mode 100644
index 00000000..28143514
--- /dev/null
+++ b/admin/slices/setup/theme/components/ui/accordion/AccordionTrigger.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+import type { AccordionTriggerProps } from "reka-ui"
+import type { HTMLAttributes } from "vue"
+import { reactiveOmit } from "@vueuse/core"
+import { ChevronDown } from "lucide-vue-next"
+import { AccordionHeader, AccordionTrigger } from "reka-ui"
+import { cn } from '#theme/utils'
+
+const props = defineProps<AccordionTriggerProps & { class?: HTMLAttributes["class"] }>()
+
+const delegatedProps = reactiveOmit(props, "class")
+</script>
+
+<template>
+  <AccordionHeader class="flex">
+    <AccordionTrigger
+      data-slot="accordion-trigger"
+      v-bind="delegatedProps"
+      :class="cn(
+        'focus-visible:border-ring focus-visible:ring-ring/50 flex flex-1 items-start justify-between gap-4 rounded-md py-3 text-left text-sm font-medium transition-all outline-none hover:underline focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&[data-state=open]>svg]:rotate-180',
+        props.class,
+      )"
+    >
+      <slot />
+      <slot name="icon">
+        <ChevronDown class="text-muted-foreground pointer-events-none size-4 shrink-0 translate-y-0.5 transition-transform duration-200" />
+      </slot>
+    </AccordionTrigger>
+  </AccordionHeader>
+</template>
diff --git a/admin/slices/setup/theme/components/ui/accordion/index.ts b/admin/slices/setup/theme/components/ui/accordion/index.ts
new file mode 100644
index 00000000..b18018b5
--- /dev/null
+++ b/admin/slices/setup/theme/components/ui/accordion/index.ts
@@ -0,0 +1,4 @@
+export { default as Accordion } from "./Accordion.vue"
+export { default as AccordionContent } from "./AccordionContent.vue"
+export { default as AccordionItem } from "./AccordionItem.vue"
+export { default as AccordionTrigger } from "./AccordionTrigger.vue"
diff --git a/api/prisma/migrations/20260922120000_agent_tool_listing/migration.sql b/api/prisma/migrations/20260922120000_agent_tool_listing/migration.sql
new file mode 100644
index 00000000..c79c951b
--- /dev/null
+++ b/api/prisma/migrations/20260922120000_agent_tool_listing/migration.sql
@@ -0,0 +1,16 @@
+-- Additive: new table AgentToolListing — the tool names the API last served to
+-- an agent's pod on MCP tools/list, so the console can mark tools the running
+-- pod does not have yet (CLEAN-109). One row per agent, cascades with it.
+-- Safe on an existing database.
+
+-- CreateTable
+CREATE TABLE "AgentToolListing" (
+    "agentId" TEXT NOT NULL,
+    "toolNames" JSONB NOT NULL,
+    "listedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "AgentToolListing_pkey" PRIMARY KEY ("agentId")
+);
+
+-- AddForeignKey
+ALTER TABLE "AgentToolListing" ADD CONSTRAINT "AgentToolListing_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "Agent"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/api/src/app.module.ts b/api/src/app.module.ts
index 86eb0900..3f43e347 100644
--- a/api/src/app.module.ts
+++ b/api/src/app.module.ts
@@ -11,6 +11,7 @@ import { AgentModule } from './slices/agent/agent/agent.module';
 import { AgentChannelModule } from './slices/agent/agentChannel/agentChannel.module';
 import { ShareLinkModule } from './slices/agent/shareLink/shareLink.module';
 import { PeerModule } from './slices/agent/peer/peer.module';
+import { ToolCatalogModule } from './slices/agent/toolCatalog/toolCatalog.module';
 import { TemplateModule } from './slices/agent/template/template.module';
 import { TemplateFileModule } from './slices/agent/templateFile/templateFile.module';
 import { TemplateInstallModule } from './slices/agent/templateInstall/templateInstall.module';
@@ -64,6 +65,7 @@ import { UserBrowserStateModule } from './slices/user/browserState/browserState.
     AgentChannelModule,
     ShareLinkModule,
     PeerModule,
+    ToolCatalogModule,
     FileModule,
     SecretModule,
     LogModule,
diff --git a/api/src/slices/agent/agent/agent.module.ts b/api/src/slices/agent/agent/agent.module.ts
index cc638e4a..071d3fba 100644
--- a/api/src/slices/agent/agent/agent.module.ts
+++ b/api/src/slices/agent/agent/agent.module.ts
@@ -1,5 +1,6 @@
 import { Module, forwardRef } from '@nestjs/common';
 import { AgentController } from './agent.controller';
+import { AgentAdminTool } from './agentAdmin.tool';
 import { IAgentGateway } from './domain/agent.gateway';
 import { AgentStatusService } from './domain/agentStatus.service';
 import { AgentDeployService } from './domain/agentDeploy.service';
@@ -36,6 +37,7 @@ import { SkillModule } from '#/skill/skill.module';
     AgentStatusService,
     AgentDeployService,
     DeployTracker,
+    AgentAdminTool,
     {
       provide: IAgentGateway,
       useClass: AgentGateway,
diff --git a/api/src/slices/agent/agent/agent.prisma b/api/src/slices/agent/agent/agent.prisma
index 8f9f9247..08902edf 100644
--- a/api/src/slices/agent/agent/agent.prisma
+++ b/api/src/slices/agent/agent/agent.prisma
@@ -7,6 +7,7 @@ import { ChatSession } from "../../chat/chat"
 import { AgentShareLink } from "../shareLink/shareLink"
 import { AgentPeer } from "../peer/peer"
 import { AgentDelegation } from "../peer/delegation"
+import { AgentToolListing } from "../toolCatalog/toolCatalog"
 
 model Agent {
   id              String         @id @default(uuid())
@@ -65,4 +66,6 @@ model Agent {
   peers              AgentPeer[]         @relation("AgentPeerCaller")
   peerOf             AgentPeer[]         @relation("AgentPeerTarget")
   delegations        AgentDelegation[]
+  // Last tools/list served to this agent's pod (CLEAN-109).
+  toolListing        AgentToolListing?
 }
diff --git a/api/src/slices/agent/agent/agentAdmin.tool.spec.ts b/api/src/slices/agent/agent/agentAdmin.tool.spec.ts
new file mode 100644
index 00000000..8664279d
--- /dev/null
+++ b/api/src/slices/agent/agent/agentAdmin.tool.spec.ts
@@ -0,0 +1,500 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { AgentAdminTool } from './agentAdmin.tool';
+import type { IAgentData } from './domain';
+import type { IAgentGateway } from './domain';
+import type { AgentDeployService } from './domain/agentDeploy.service';
+import type { AgentStatusService } from './domain/agentStatus.service';
+import type { WorkflowService } from '#/workflow/domain/workflow.service';
+import type { IPodGateway, IAgentPodStatus } from '#/agent/pod/domain';
+import type { IFileGateway } from '#/agent/file/domain';
+import type { AgentMcpResolver } from '#/mcpServer/domain/agentMcpResolver.service';
+import type { IMcpServerData } from '#/mcpServer/domain/mcpServer.types';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * These tools stop, start and delete agents from the chat. What matters most
+ * is not the happy path but that a plain agent cannot reach them, that a
+ * destructive call without the person's yes touches nothing, and that no
+ * credential — env values, MCP auth — ever lands in a result a model reads.
+ */
+const agent = (overrides: Partial<IAgentData> = {}): IAgentData =>
+  ({
+    id: 'agent-a',
+    name: 'Support Bot',
+    templateId: 'tpl-1',
+    llmCredentialId: 'llm-1',
+    status: 'running',
+    statusReason: null,
+    workflowId: 'wf-1',
+    firstDeployedAt: null,
+    lastDeployStartedAt: new Date('2026-09-17T10:00:00.000Z'),
+    launchContext: null,
+    config: {},
+    resources: {},
+    isAdmin: false,
+    debugEnabled: false,
+    knowledgeIds: [],
+    ...overrides,
+  }) as unknown as IAgentData;
+
+const pod = (overrides: Partial<IAgentPodStatus> = {}): IAgentPodStatus => ({
+  agentId: 'agent-a',
+  podName: 'agent-a-pod',
+  phase: 'Running',
+  ready: true,
+  restartCount: 0,
+  startedAt: '2026-09-17T10:00:00.000Z',
+  terminating: false,
+  lastTerminationReason: null,
+  containerWaitingReason: null,
+  message: null,
+  observedAt: '2026-09-17T10:05:00.000Z',
+  ...overrides,
+});
+
+const SECRET_URL = 'https://mcp.example/hidden-path';
+const SECRET_AUTH = 'Bearer super-secret-mcp-token';
+
+const server = (overrides: Partial<IMcpServerData> = {}): IMcpServerData => ({
+  id: 'mcp-1',
+  name: 'Docs',
+  description: null,
+  url: SECRET_URL,
+  transport: 'streamable-http' as IMcpServerData['transport'],
+  authType: 'bearer' as IMcpServerData['authType'],
+  authValue: SECRET_AUTH,
+  oauthClientId: null,
+  enabled: true,
+  builtIn: true,
+  templateIds: [],
+  createdAt: new Date('2026-09-01T00:00:00.000Z'),
+  updatedAt: new Date('2026-09-01T00:00:00.000Z'),
+  ...overrides,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: AgentAdminTool;
+  agents: { findById: jest.Mock; delete: jest.Mock };
+  deploy: { stopAgent: jest.Mock; deploy: jest.Mock };
+  status: { getCapacity: jest.Mock };
+  pods: { list: jest.Mock; getMetrics: jest.Mock; delete: jest.Mock };
+  workflows: { previewAgentEnv: jest.Mock; cancelAgentWorkflow: jest.Mock };
+  files: { wipe: jest.Mock };
+  mcps: { resolveForAgent: jest.Mock };
+}
+
+function harness(): Harness {
+  const agents = {
+    findById: jest.fn().mockResolvedValue(agent()),
+    delete: jest.fn().mockResolvedValue(undefined),
+  };
+  const deploy = {
+    stopAgent: jest.fn().mockResolvedValue(undefined),
+    deploy: jest.fn().mockResolvedValue(undefined),
+  };
+  const status = {
+    getCapacity: jest.fn().mockResolvedValue({
+      freeAgentSlots: 3,
+      usedAgentSlots: 5,
+      totalAgentSlots: 8,
+      slotCpuMilli: 100,
+      slotMemBytes: 536870912,
+      nodes: [],
+      observedAt: '2026-09-17T10:05:00.000Z',
+    }),
+  };
+  const pods = {
+    list: jest.fn().mockResolvedValue([pod()]),
+    getMetrics: jest.fn().mockResolvedValue({
+      pod: {
+        cpuMilli: 42,
+        memBytes: 1024,
+        cpuLimitMilli: 1000,
+        memLimitBytes: 2048,
+      },
+      node: { name: 'node-1', diskAvailBytes: 10, diskCapacityBytes: 100 },
+    }),
+    delete: jest.fn().mockResolvedValue(undefined),
+  };
+  const workflows = {
+    previewAgentEnv: jest.fn().mockResolvedValue([
+      { name: 'LOG_LEVEL', value: 'debug' },
+      { name: 'LLM_API_KEY', value: 'sk-live-do-not-leak' },
+      { name: 'TELEGRAM_BOT_TOKEN', value: 'tg-bot-token-value' },
+      { name: 'OPTIONAL_SECRET', value: '' },
+    ]),
+    cancelAgentWorkflow: jest.fn().mockResolvedValue(undefined),
+  };
+  const files = { wipe: jest.fn().mockResolvedValue(7) };
+  const mcps = { resolveForAgent: jest.fn().mockResolvedValue([server()]) };
+
+  const tool = new AgentAdminTool(
+    agents as unknown as IAgentGateway,
+    deploy as unknown as AgentDeployService,
+    status as unknown as AgentStatusService,
+    pods as unknown as IPodGateway,
+    workflows as unknown as WorkflowService,
+    files as unknown as IFileGateway,
+    mcps as unknown as AgentMcpResolver,
+  );
+  return { tool, agents, deploy, status, pods, workflows, files, mcps };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('AgentAdminTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, deploy, agents } = harness();
+    await expect(
+      tool.stopAgent({ id: 'agent-a', confirm: true }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(agents.findById).not.toHaveBeenCalled();
+    expect(deploy.stopAgent).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool } = harness();
+    await expect(
+      tool.getClusterCapacity({}, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('AgentAdminTool — stop_agent', () => {
+  it('refuses without confirm and touches nothing', async () => {
+    const { tool, deploy } = harness();
+    const result = await tool.stopAgent(
+      { id: 'agent-a', confirm: false },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('stop the agent «Support Bot»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(deploy.stopAgent).not.toHaveBeenCalled();
+  });
+
+  it('reports a missing agent before asking for confirmation', async () => {
+    const { tool, agents, deploy } = harness();
+    agents.findById.mockResolvedValue(null);
+    const result = await tool.stopAgent(
+      { id: 'nope', confirm: false },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('Agent nope not found');
+    expect(textOf(result)).toContain('list_agents');
+    expect(deploy.stopAgent).not.toHaveBeenCalled();
+  });
+
+  it('stops through the deploy service and hands back the fresh row', async () => {
+    const { tool, agents, deploy } = harness();
+    agents.findById
+      .mockResolvedValueOnce(agent())
+      .mockResolvedValueOnce(agent({ status: 'stopped', workflowId: null }));
+    const text = textOf(
+      await tool.stopAgent({ id: 'agent-a', confirm: true }, null, operator()),
+    );
+    expect(deploy.stopAgent).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('"status": "stopped"');
+    expect(text).toContain('start_agent');
+  });
+});
+
+describe('AgentAdminTool — start_agent', () => {
+  it('deploys a fresh pod', async () => {
+    const { tool, agents, deploy } = harness();
+    agents.findById
+      .mockResolvedValueOnce(agent({ status: 'stopped' }))
+      .mockResolvedValueOnce(agent({ status: 'deploying' }));
+    const text = textOf(
+      await tool.startAgent({ id: 'agent-a' }, null, operator()),
+    );
+    expect(deploy.deploy).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('"status": "deploying"');
+  });
+
+  it('names the next move when the agent does not exist', async () => {
+    const { tool, agents, deploy } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.startAgent({ id: 'nope' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_agents');
+    expect(deploy.deploy).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentAdminTool — delete_agent', () => {
+  it('refuses without confirm and deletes nothing', async () => {
+    const { tool, agents, pods, workflows, files } = harness();
+    const result = await tool.deleteAgent(
+      { id: 'agent-a', confirm: false },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('delete the agent «Support Bot»');
+    expect(agents.delete).not.toHaveBeenCalled();
+    expect(workflows.cancelAgentWorkflow).not.toHaveBeenCalled();
+    expect(pods.delete).not.toHaveBeenCalled();
+    expect(files.wipe).not.toHaveBeenCalled();
+  });
+
+  it('says the workspace will be wiped when wipeS3 is asked for', async () => {
+    const { tool } = harness();
+    const result = await tool.deleteAgent(
+      { id: 'agent-a', wipeS3: true, confirm: false },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('wipe its workspace files');
+  });
+
+  it('removes the row, cancels the workflow and deletes the pod, keeping S3', async () => {
+    const { tool, agents, pods, workflows, files } = harness();
+    const text = textOf(
+      await tool.deleteAgent(
+        { id: 'agent-a', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(agents.delete).toHaveBeenCalledWith('agent-a');
+    expect(workflows.cancelAgentWorkflow).toHaveBeenCalledWith('wf-1');
+    expect(pods.delete).toHaveBeenCalledWith('agent-a');
+    expect(files.wipe).not.toHaveBeenCalled();
+    expect(text).toContain('"ok": true');
+    expect(text).toContain('workspace files are kept');
+  });
+
+  it('wipes S3 only when wipeS3 is true', async () => {
+    const { tool, files } = harness();
+    const text = textOf(
+      await tool.deleteAgent(
+        { id: 'agent-a', wipeS3: true, confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(files.wipe).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('"wipedFiles": 7');
+  });
+
+  it('skips the workflow cancel when the agent has none', async () => {
+    const { tool, agents, workflows } = harness();
+    agents.findById.mockResolvedValue(agent({ workflowId: null }));
+    await tool.deleteAgent({ id: 'agent-a', confirm: true }, null, operator());
+    expect(workflows.cancelAgentWorkflow).not.toHaveBeenCalled();
+  });
+
+  it('tolerates a pod cleanup failure once the row is gone', async () => {
+    const { tool, agents, pods } = harness();
+    pods.delete.mockRejectedValue(new Error('k8s down'));
+    const text = textOf(
+      await tool.deleteAgent(
+        { id: 'agent-a', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(agents.delete).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('"ok": true');
+  });
+
+  it('reports a missing agent and deletes nothing', async () => {
+    const { tool, agents } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.deleteAgent({ id: 'nope', confirm: true }, null, operator()),
+    );
+    expect(text).toContain('Agent nope not found');
+    expect(agents.delete).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentAdminTool — get_agent_status', () => {
+  it('joins the row with its pod and metrics', async () => {
+    const { tool, pods } = harness();
+    const text = textOf(
+      await tool.getAgentStatus({ id: 'agent-a' }, null, operator()),
+    );
+    expect(pods.getMetrics).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('"status": "running"');
+    expect(text).toContain('"phase": "Running"');
+    expect(text).toContain('"ready": true');
+    expect(text).toContain('"startedAt": "2026-09-17T10:00:00.000Z"');
+    expect(text).toContain('"cpuMilli": 42');
+    expect(text).toContain('"diskAvailBytes": 10');
+  });
+
+  it('returns null pod and metrics for an agent without a pod', async () => {
+    const { tool, agents, pods } = harness();
+    agents.findById.mockResolvedValue(
+      agent({ status: 'stopped', statusReason: 'stopped by operator' }),
+    );
+    pods.list.mockResolvedValue([pod({ agentId: 'someone-else' })]);
+    pods.getMetrics.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getAgentStatus({ id: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('"pod": null');
+    expect(text).toContain('"metrics": null');
+    expect(text).toContain('"statusReason": "stopped by operator"');
+  });
+
+  it('names the next move when the agent does not exist', async () => {
+    const { tool, agents, pods } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getAgentStatus({ id: 'nope' }, null, operator()),
+    );
+    expect(text).toContain('list_agents');
+    expect(pods.getMetrics).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentAdminTool — get_agent_env', () => {
+  it('masks credential values by name and keeps the rest', async () => {
+    const { tool, workflows } = harness();
+    const text = textOf(
+      await tool.getAgentEnv({ id: 'agent-a' }, null, operator()),
+    );
+    expect(workflows.previewAgentEnv).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'agent-a' }),
+    );
+    expect(text).toContain('"name": "LOG_LEVEL"');
+    expect(text).toContain('"value": "debug"');
+    expect(text).toContain('"name": "LLM_API_KEY"');
+    expect(text).toContain('••••');
+    expect(text).not.toContain('sk-live-do-not-leak');
+    expect(text).not.toContain('tg-bot-token-value');
+  });
+
+  it('leaves an unset secret empty rather than pretending it has a value', async () => {
+    const { tool } = harness();
+    const result = JSON.parse(
+      textOf(await tool.getAgentEnv({ id: 'agent-a' }, null, operator())),
+    ) as { name: string; value: string; masked: boolean }[];
+    const unset = result.find((v) => v.name === 'OPTIONAL_SECRET');
+    expect(unset).toEqual({
+      name: 'OPTIONAL_SECRET',
+      value: '',
+      masked: false,
+    });
+  });
+
+  it('names the next move when the agent does not exist', async () => {
+    const { tool, agents, workflows } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getAgentEnv({ id: 'nope' }, null, operator()),
+    );
+    expect(text).toContain('list_agents');
+    expect(workflows.previewAgentEnv).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentAdminTool — list_agent_mcps', () => {
+  it('lists the servers without url or credential and reports no drift', async () => {
+    const { tool, mcps } = harness();
+    const text = textOf(
+      await tool.listAgentMcps({ id: 'agent-a' }, null, operator()),
+    );
+    expect(mcps.resolveForAgent).toHaveBeenCalledWith(
+      expect.objectContaining({ templateId: 'tpl-1' }),
+    );
+    expect(text).toContain('"name": "Docs"');
+    expect(text).toContain('"builtIn": true');
+    expect(text).toContain('"transport": "streamable-http"');
+    expect(text).toContain('"restartRequired": false');
+    expect(text).not.toContain(SECRET_AUTH);
+    expect(text).not.toContain(SECRET_URL);
+    expect(text).not.toContain('authValue');
+    expect(text).not.toContain('"url"');
+  });
+
+  it('flags a restart when a server changed after the pod started', async () => {
+    const { tool, mcps } = harness();
+    mcps.resolveForAgent.mockResolvedValue([
+      server({
+        id: 'mcp-2',
+        name: 'Jira',
+        builtIn: false,
+        updatedAt: new Date('2026-09-17T11:00:00.000Z'),
+      }),
+    ]);
+    const text = textOf(
+      await tool.listAgentMcps({ id: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('"restartRequired": true');
+    const parsed = JSON.parse(text) as {
+      drift: { changedServers: string[]; configChangedAt: string | null };
+    };
+    expect(parsed.drift.changedServers).toEqual(['Jira']);
+    expect(parsed.drift.configChangedAt).toBe('2026-09-17T11:00:00.000Z');
+    expect(text).toContain('restart_agent with id=agent-a');
+  });
+
+  it('does not call a stopped agent stale', async () => {
+    const { tool, pods, mcps } = harness();
+    pods.list.mockResolvedValue([]);
+    mcps.resolveForAgent.mockResolvedValue([
+      server({ updatedAt: new Date('2026-09-17T11:00:00.000Z') }),
+    ]);
+    const text = textOf(
+      await tool.listAgentMcps({ id: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('"restartRequired": false');
+    expect(text).toContain('No pod is running');
+  });
+
+  it('names the next move when the agent does not exist', async () => {
+    const { tool, agents, mcps } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.listAgentMcps({ id: 'nope' }, null, operator()),
+    );
+    expect(text).toContain('list_agents');
+    expect(mcps.resolveForAgent).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentAdminTool — get_cluster_capacity', () => {
+  it('hands back the capacity with a one-line summary', async () => {
+    const { tool, status } = harness();
+    const text = textOf(await tool.getClusterCapacity({}, null, operator()));
+    expect(status.getCapacity).toHaveBeenCalled();
+    expect(text).toContain('"freeAgentSlots": 3');
+    expect(text).toContain('3 of 8 agent slot(s) free');
+  });
+
+  it('says the cluster is unreachable instead of inventing a number', async () => {
+    const { tool, status } = harness();
+    status.getCapacity.mockResolvedValue(null);
+    const text = textOf(await tool.getClusterCapacity({}, null, operator()));
+    expect(text).toContain('"capacity": null');
+    expect(text).toContain('unreachable');
+  });
+});
diff --git a/api/src/slices/agent/agent/agentAdmin.tool.ts b/api/src/slices/agent/agent/agentAdmin.tool.ts
new file mode 100644
index 00000000..23230ea2
--- /dev/null
+++ b/api/src/slices/agent/agent/agentAdmin.tool.ts
@@ -0,0 +1,423 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  ok,
+  requireOperator,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAgentGateway } from './domain';
+import { AgentDeployService } from './domain/agentDeploy.service';
+import { AgentStatusService } from './domain/agentStatus.service';
+import { detectMcpConfigDrift } from './domain/mcpConfigDrift';
+import { WorkflowService } from '#/workflow/domain/workflow.service';
+import { IPodGateway } from '#/agent/pod/domain';
+import { IFileGateway } from '#/agent/file/domain';
+import { AgentMcpResolver } from '#/mcpServer/domain/agentMcpResolver.service';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+
+/**
+ * Env var names whose value never leaves the API through a tool. The console
+ * masks a fixed list (`BRIDLE_API_KEY`, `AWS_SECRET_ACCESS_KEY`, `LLM_API_KEY`,
+ * `TELEGRAM_BOT_TOKEN` in the Environment tab); a person can click "reveal"
+ * there, a model cannot, so the tool masks by name fragment instead — every
+ * console entry matches, and so does any credential added later (FR-004).
+ */
+const SECRET_NAME_FRAGMENTS = ['TOKEN', 'SECRET', 'KEY', 'PASSWORD'];
+const MASK = '••••';
+
+function isSecretEnvName(name: string): boolean {
+  const upper = name.toUpperCase();
+  return SECRET_NAME_FRAGMENTS.some((fragment) => upper.includes(fragment));
+}
+
+const notFound = (id: string) =>
+  ok({ error: `Agent ${id} not found — call list_agents to find the id` });
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/**
+ * The agent lifecycle from the chat (CLEAN-109). `rancher.tool.ts` already
+ * lists, creates, updates and restarts agents; this class adds what the
+ * console's agent page can do and the operator agent could not: stop and
+ * start, delete, and the read-only panels — live status and metrics, the
+ * pod environment preview, the MCP servers and their drift, cluster capacity.
+ *
+ * Every mutation goes through the same services `AgentController` calls, in
+ * the same order, so a stop from the chat frees the slot the same way a stop
+ * from the console does, and a delete tolerates the same Argo/k8s hiccups.
+ *
+ * Operator-only: hidden from a plain agent's tools/list, and refused by name.
+ */
+@Injectable()
+export class AgentAdminTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(AgentAdminTool.name);
+
+  constructor(
+    private readonly agents: IAgentGateway,
+    private readonly agentDeploy: AgentDeployService,
+    private readonly agentStatus: AgentStatusService,
+    private readonly pods: IPodGateway,
+    private readonly workflows: WorkflowService,
+    private readonly files: IFileGateway,
+    private readonly mcpResolver: AgentMcpResolver,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return callerIsOperator(httpRequest);
+  }
+
+  // ─── Lifecycle ───────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'stop_agent',
+    topic: ToolTopics.Agents,
+    title: 'Stop an agent',
+    template: 'Stop the agent «name»',
+    destructive: true,
+    description:
+      'Stop an agent without deleting it: cancels its deploy workflow and ' +
+      'deletes its pod to free cluster CPU/memory, then marks it "stopped". ' +
+      'Its files and settings stay. Use it to free a slot for another agent; ' +
+      'bring it back with start_agent. Takes the agent id — resolve a name ' +
+      'with list_agents first. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string().describe('Agent id — pick from list_agents'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async stopAgent(
+    args: { id: string; confirm: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(args.id);
+    if (!agent) return notFound(args.id);
+    const refusal = confirmed(
+      args,
+      `stop the agent «${agent.name}» and delete its pod`,
+    );
+    if (refusal) return refusal;
+    await this.agentDeploy.stopAgent(args.id);
+    const after = await this.agents.findById(args.id);
+    return ok({
+      ok: true,
+      agent: after,
+      message: `Agent «${agent.name}» stopped — its pod is gone and its slot is free. Call start_agent to bring it back.`,
+    });
+  }
+
+  @Tool({
+    name: 'start_agent',
+    topic: ToolTopics.Agents,
+    title: 'Start an agent',
+    template: 'Start the agent «name»',
+    description:
+      'Start a stopped agent: deploys a fresh pod and reattaches the ' +
+      'runtime. The inverse of stop_agent. The agent shows as "deploying" ' +
+      'until its readiness probe passes — check with get_agent_status. ' +
+      'Takes the agent id — resolve a name with list_agents first.',
+    parameters: z.object({
+      id: z.string().describe('Agent id — pick from list_agents'),
+    }),
+  })
+  async startAgent(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(id);
+    if (!agent) return notFound(id);
+    await this.agentDeploy.deploy(id);
+    const after = await this.agents.findById(id);
+    return ok({
+      ok: true,
+      agent: after,
+      message: `Agent «${agent.name}» is deploying — it will boot shortly.`,
+    });
+  }
+
+  @Tool({
+    name: 'delete_agent',
+    topic: ToolTopics.Agents,
+    title: 'Delete an agent',
+    template: 'Delete the agent «name» and its workspace',
+    destructive: true,
+    description:
+      'Stop and delete an agent for good: removes its record, cancels its ' +
+      'workflow and deletes its pod. Its workspace files in S3 are kept ' +
+      'unless wipeS3 is true — say so to the person, since a wipe cannot be ' +
+      'undone. Takes the agent id — resolve a name with list_agents first. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string().describe('Agent id — pick from list_agents'),
+      wipeS3: z
+        .boolean()
+        .optional()
+        .describe(
+          'Also delete every workspace file under agents/<id>/ in S3. Off by default.',
+        ),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteAgent(
+    args: { id: string; wipeS3?: boolean; confirm: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const { id } = args;
+    const agent = await this.agents.findById(id);
+    if (!agent) return notFound(id);
+    const refusal = confirmed(
+      args,
+      args.wipeS3
+        ? `delete the agent «${agent.name}» and wipe its workspace files`
+        : `delete the agent «${agent.name}» (its workspace files are kept)`,
+    );
+    if (refusal) return refusal;
+
+    // Same order as AgentController.remove: the row goes first so the list
+    // clears at once; a slow or flaky Argo/k8s cleanup must not leave the
+    // agent stuck in the console.
+    await this.agents.delete(id);
+
+    if (agent.workflowId) {
+      try {
+        await this.workflows.cancelAgentWorkflow(agent.workflowId);
+      } catch (err) {
+        this.logger.warn(
+          `Cancel workflow failed for agent ${id}: ${(err as Error).message}`,
+        );
+      }
+    }
+
+    try {
+      await this.pods.delete(id);
+    } catch (err) {
+      this.logger.warn(
+        `Pod cleanup failed for agent ${id}: ${(err as Error).message}`,
+      );
+    }
+
+    let wipedFiles: number | null = null;
+    if (args.wipeS3 === true) {
+      try {
+        wipedFiles = await this.files.wipe(id);
+        this.logger.log(
+          `Wiped ${wipedFiles} S3 object(s) for agent ${id} on delete`,
+        );
+      } catch (err) {
+        this.logger.warn(
+          `S3 wipe failed for agent ${id}: ${(err as Error).message}`,
+        );
+      }
+    }
+
+    return ok({
+      ok: true,
+      agentId: id,
+      name: agent.name,
+      wipedFiles,
+      message:
+        `Agent «${agent.name}» deleted.` +
+        (args.wipeS3
+          ? wipedFiles === null
+            ? ' The S3 wipe failed — the workspace files are still there.'
+            : ` ${wipedFiles} workspace file(s) wiped.`
+          : ' Its workspace files are kept in S3.'),
+    });
+  }
+
+  // ─── Read-only panels ────────────────────────────────────────────────
+
+  @Tool({
+    name: 'get_agent_status',
+    topic: ToolTopics.Agents,
+    title: 'Show live status and metrics',
+    template: 'How is the agent «name» doing right now?',
+    description:
+      'Live view of one agent: its status and statusReason, the pod (phase, ' +
+      'ready, startedAt, restarts, last termination reason) when one exists, ' +
+      'and resource usage — pod CPU/memory against limits, free disk on the ' +
+      'node. pod and metrics are null while the agent has no pod (stopped, ' +
+      'still pending). Takes the agent id — resolve a name with list_agents.',
+    parameters: z.object({
+      id: z.string().describe('Agent id — pick from list_agents'),
+    }),
+  })
+  async getAgentStatus(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(id);
+    if (!agent) return notFound(id);
+    // Same sources as GET agents/status (pod list) and GET :id/metrics.
+    const [pods, metrics] = await Promise.all([
+      this.pods.list(),
+      this.pods.getMetrics(id),
+    ]);
+    const pod = pods.find((p) => p.agentId === id) ?? null;
+    return ok({
+      id: agent.id,
+      name: agent.name,
+      status: agent.status,
+      statusReason: agent.statusReason,
+      lastDeployStartedAt: agent.lastDeployStartedAt,
+      pod: pod
+        ? {
+            phase: pod.phase,
+            ready: pod.ready,
+            startedAt: pod.startedAt,
+            restartCount: pod.restartCount,
+            terminating: pod.terminating,
+            lastTerminationReason: pod.lastTerminationReason,
+            containerWaitingReason: pod.containerWaitingReason,
+            message: pod.message,
+          }
+        : null,
+      metrics,
+    });
+  }
+
+  @Tool({
+    name: 'get_agent_env',
+    topic: ToolTopics.Agents,
+    title: 'Show the pod environment preview',
+    template: 'Show the environment the agent «name» runs with',
+    description:
+      'The env vars the agent pod receives on its next deploy, built from ' +
+      'the same code as the real pod manifest. Values of credentials (names ' +
+      'containing TOKEN, SECRET, KEY or PASSWORD) are masked as "••••" — the ' +
+      'console can reveal them, a tool cannot. Takes the agent id — resolve ' +
+      'a name with list_agents first.',
+    parameters: z.object({
+      id: z.string().describe('Agent id — pick from list_agents'),
+    }),
+  })
+  async getAgentEnv(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(id);
+    if (!agent) return notFound(id);
+    const env = await this.workflows.previewAgentEnv(agent);
+    return ok(
+      env.map((v) => ({
+        name: v.name,
+        value: v.value && isSecretEnvName(v.name) ? MASK : v.value,
+        masked: Boolean(v.value) && isSecretEnvName(v.name),
+      })),
+    );
+  }
+
+  @Tool({
+    name: 'list_agent_mcps',
+    topic: ToolTopics.Agents,
+    title: "Show the agent's MCP servers",
+    template:
+      'Which MCP servers does the agent «name» have, and does it need a restart?',
+    description:
+      'The MCP servers this agent gets at runtime — the ones its template ' +
+      'attaches plus the always-on built-ins — and whether the running pod ' +
+      'still carries that configuration. Servers are baked into the pod at ' +
+      'creation, so a change made afterwards only reaches it on a restart: ' +
+      'when restartRequired is true, offer restart_agent. Server urls and ' +
+      'credentials are not returned; use list_mcp_servers for details. Takes ' +
+      'the agent id — resolve a name with list_agents first.',
+    parameters: z.object({
+      id: z.string().describe('Agent id — pick from list_agents'),
+    }),
+  })
+  async listAgentMcps(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(id);
+    if (!agent) return notFound(id);
+
+    const [servers, pods] = await Promise.all([
+      this.mcpResolver.resolveForAgent(agent),
+      this.pods.list(),
+    ]);
+    const pod = pods.find((p) => p.agentId === agent.id) ?? null;
+
+    const drift = detectMcpConfigDrift({
+      servers: servers.map((s) => ({
+        id: s.id,
+        name: s.name,
+        updatedAt: s.updatedAt,
+      })),
+      podStartedAt: pod?.startedAt ? new Date(pod.startedAt) : null,
+    });
+
+    return ok({
+      agentId: agent.id,
+      // No url, no authValue: a model needs the names to reason, not the
+      // addresses and credentials the pod authenticates with (FR-004).
+      servers: servers.map((s) => ({
+        id: s.id,
+        name: s.name,
+        transport: s.transport,
+        enabled: s.enabled,
+        builtIn: s.builtIn,
+      })),
+      drift,
+      message: drift.restartRequired
+        ? `The pod started before ${drift.changedServers.join(', ')} changed — call restart_agent with id=${agent.id} to apply.`
+        : pod
+          ? 'The running pod carries exactly this server set.'
+          : 'No pod is running; the servers apply on the next deploy.',
+    });
+  }
+
+  @Tool({
+    name: 'get_cluster_capacity',
+    topic: ToolTopics.Agents,
+    title: 'Show cluster capacity',
+    template: 'How much capacity is left for new agents?',
+    description:
+      'How many more agents fit on the cluster: free schedulable CPU/memory ' +
+      'on the agent nodes divided by the fixed per-agent request floor, ' +
+      'minus agents still deploying without a pod. Cached about 15 seconds. ' +
+      'capacity is null when the Kubernetes API is unreachable — say so ' +
+      'rather than guessing a number.',
+    parameters: z.object({}),
+  })
+  async getClusterCapacity(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const capacity = await this.agentStatus.getCapacity();
+    if (!capacity) {
+      return ok({
+        capacity: null,
+        message:
+          'The Kubernetes API is unreachable right now — capacity is unknown. Try again in a moment.',
+      });
+    }
+    return ok({
+      capacity,
+      message: `${capacity.freeAgentSlots} of ${capacity.totalAgentSlots} agent slot(s) free.`,
+    });
+  }
+}
diff --git a/api/src/slices/agent/agentChannel/agentChannel.module.ts b/api/src/slices/agent/agentChannel/agentChannel.module.ts
index 9d324d8d..d2919b95 100644
--- a/api/src/slices/agent/agentChannel/agentChannel.module.ts
+++ b/api/src/slices/agent/agentChannel/agentChannel.module.ts
@@ -1,7 +1,9 @@
 import { Module, forwardRef } from '@nestjs/common';
 import { FileModule } from '#/agent/file/file.module';
+import { AgentModule } from '#/agent/agent/agent.module';
 import { AuthModule } from '#/user/auth/auth.module';
 import { AgentChannelController } from './agentChannel.controller';
+import { AgentChannelTool } from './agentChannel.tool';
 import { IAgentChannelGateway } from './domain/agentChannel.gateway';
 import { AgentChannelGateway } from './data/agentChannel.gateway';
 import { AgentChannelMapper } from './data/agentChannel.mapper';
@@ -11,11 +13,20 @@ import { AgentChannelMapper } from './data/agentChannel.mapper';
 // safe (we only consume IFileGateway, no back-edge), but forwardRef
 // matches the rest of the file slice's consumers and survives any
 // future restructuring.
+//
+// AgentModule (IAgentGateway, for the chat tool's existence check) must be a
+// forwardRef: AgentModule → WorkflowModule → AgentChannelModule already
+// exists, so a plain import here would close the cycle.
 @Module({
-  imports: [forwardRef(() => FileModule), AuthModule],
+  imports: [
+    forwardRef(() => FileModule),
+    forwardRef(() => AgentModule),
+    AuthModule,
+  ],
   controllers: [AgentChannelController],
   providers: [
     AgentChannelMapper,
+    AgentChannelTool,
     {
       provide: IAgentChannelGateway,
       useClass: AgentChannelGateway,
diff --git a/api/src/slices/agent/agentChannel/agentChannel.tool.spec.ts b/api/src/slices/agent/agentChannel/agentChannel.tool.spec.ts
new file mode 100644
index 00000000..cbe744a5
--- /dev/null
+++ b/api/src/slices/agent/agentChannel/agentChannel.tool.spec.ts
@@ -0,0 +1,193 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { AgentChannelTool } from './agentChannel.tool';
+import type { IAgentChannelGateway } from './domain/agentChannel.gateway';
+import type { IAgentChannel } from './domain/agentChannel.types';
+import type { IAgentGateway } from '#/agent/agent/domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Two things matter more than the happy path here: that a bot token never
+ * reaches the model's context, in either direction (a token read back from
+ * the workspace is a token in a transcript), and that a mistyped agent id is
+ * reported instead of being read as "no channels" or written as a new agent.
+ */
+const BOT_TOKEN = '123456:SECRET-bot-token';
+
+const channel = (overrides: Partial<IAgentChannel> = {}): IAgentChannel => ({
+  type: 'telegram',
+  config: { botToken: BOT_TOKEN, botName: 'support_bot', adminIds: '42' },
+  connected: true,
+  statusReason: null,
+  statusUpdatedAt: 1758000000000,
+  ...overrides,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: AgentChannelTool;
+  channels: { getForAgent: jest.Mock; setForAgent: jest.Mock };
+  agents: { findById: jest.Mock };
+}
+
+function harness(): Harness {
+  const channels = {
+    getForAgent: jest.fn().mockResolvedValue([channel()]),
+    setForAgent: jest.fn().mockResolvedValue([channel()]),
+  };
+  const agents = {
+    findById: jest
+      .fn()
+      .mockResolvedValue({ id: 'agent-a', name: 'Support Bot' }),
+  };
+  const tool = new AgentChannelTool(
+    channels as unknown as IAgentChannelGateway,
+    agents as unknown as IAgentGateway,
+  );
+  return { tool, channels, agents };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+const input = () => [
+  {
+    type: 'telegram' as const,
+    config: { botToken: BOT_TOKEN, botName: 'support_bot' },
+  },
+];
+
+describe('AgentChannelTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, channels } = harness();
+    await expect(
+      tool.setAgentChannels(
+        { agentId: 'agent-a', channels: input() },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(channels.setForAgent).not.toHaveBeenCalled();
+  });
+
+  it('refuses a read from a plain agent too', async () => {
+    const { tool, channels } = harness();
+    await expect(
+      tool.getAgentChannels({ agentId: 'agent-a' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(channels.getForAgent).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentChannelTool — reading', () => {
+  it('reports the channels with their live state and without the bot token', async () => {
+    const { tool, channels } = harness();
+    const text = textOf(
+      await tool.getAgentChannels({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(channels.getForAgent).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('"telegram"');
+    expect(text).toContain('support_bot');
+    expect(text).toContain('"connected": true');
+    expect(text).toContain('Support Bot');
+    expect(text).not.toContain(BOT_TOKEN);
+    expect(text).not.toContain('botToken');
+  });
+
+  it('answers an empty list for an agent with nothing configured', async () => {
+    const { tool, channels } = harness();
+    channels.getForAgent.mockResolvedValue([]);
+    const text = textOf(
+      await tool.getAgentChannels({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('"channels": []');
+  });
+
+  it('names the next move when the agent does not exist', async () => {
+    const { tool, channels, agents } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getAgentChannels({ agentId: 'agent-x' }, null, operator()),
+    );
+    expect(text).toContain('Agent agent-x not found');
+    expect(text).toContain('list_agents');
+    expect(channels.getForAgent).not.toHaveBeenCalled();
+  });
+});
+
+describe('AgentChannelTool — replacing the set', () => {
+  it('hands the full list to the gateway and acknowledges without the token', async () => {
+    const { tool, channels } = harness();
+    const text = textOf(
+      await tool.setAgentChannels(
+        { agentId: 'agent-a', channels: input() },
+        null,
+        operator(),
+      ),
+    );
+    expect(channels.setForAgent).toHaveBeenCalledWith('agent-a', input());
+    expect(text).toContain('Channels of «Support Bot» replaced');
+    expect(text).toContain('restart_agent with id=agent-a');
+    expect(text).not.toContain(BOT_TOKEN);
+    expect(text).not.toContain('botToken');
+  });
+
+  it('passes an empty list through so every channel is disconnected', async () => {
+    const { tool, channels } = harness();
+    channels.setForAgent.mockResolvedValue([]);
+    const text = textOf(
+      await tool.setAgentChannels(
+        { agentId: 'agent-a', channels: [] },
+        null,
+        operator(),
+      ),
+    );
+    expect(channels.setForAgent).toHaveBeenCalledWith('agent-a', []);
+    expect(text).toContain(
+      'Every channel of «Support Bot» is now disconnected',
+    );
+  });
+
+  it('writes nothing for an agent that does not exist', async () => {
+    const { tool, channels, agents } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.setAgentChannels(
+        { agentId: 'agent-x', channels: input() },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(channels.setForAgent).not.toHaveBeenCalled();
+  });
+
+  it('lets a storage failure escape, so the MCP layer reports it as an error', async () => {
+    const { tool, channels } = harness();
+    channels.setForAgent.mockRejectedValue(new Error('s3 is down'));
+    await expect(
+      tool.setAgentChannels(
+        { agentId: 'agent-a', channels: input() },
+        null,
+        operator(),
+      ),
+    ).rejects.toThrow('s3 is down');
+  });
+});
diff --git a/api/src/slices/agent/agentChannel/agentChannel.tool.ts b/api/src/slices/agent/agentChannel/agentChannel.tool.ts
new file mode 100644
index 00000000..41494aba
--- /dev/null
+++ b/api/src/slices/agent/agentChannel/agentChannel.tool.ts
@@ -0,0 +1,178 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import {
+  callerIsOperator,
+  ok,
+  requireOperator,
+  stripSecrets,
+  type ToolResult,
+} from '#/mcp/tooling';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { IAgentChannelGateway } from './domain/agentChannel.gateway';
+import type { IAgentChannel } from './domain/agentChannel.types';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** Same cap as `SetAgentChannelsDto` (`@ArrayMaxSize(8)`). */
+const MAX_CHANNELS = 8;
+
+/**
+ * A bot token is the channel's credential. `stripSecrets` knows Ranch's usual
+ * credential field names but not this one, so the list is spelled out here.
+ */
+const CHANNEL_SECRET_KEYS = [
+  'botToken',
+  'apiKey',
+  'authValue',
+  'password',
+  'passwordHash',
+  'secret',
+  'token',
+] as const;
+
+const telegramChannel = z.object({
+  type: z
+    .literal('telegram')
+    .describe('Channel type. v1 supports telegram only.'),
+  config: z.object({
+    botToken: z
+      .string()
+      .min(1)
+      .describe('Telegram bot HTTP API token, issued by @BotFather'),
+    botName: z
+      .string()
+      .optional()
+      .describe('Public bot username without @ — shown on landing pages'),
+    adminIds: z
+      .string()
+      .optional()
+      .describe(
+        'Comma-separated Telegram chat ids the runtime treats as bot admins',
+      ),
+  }),
+});
+
+type ChannelInput = z.infer<typeof telegramChannel>;
+
+/**
+ * The agent's delivery channels, from the chat (CLEAN-109). Mirrors
+ * `AgentChannelController`: the same `IAgentChannelGateway`, the same
+ * exhaustive-list semantics on write. Operator-only — a plain agent edits
+ * its own channels through the runtime's `channel_*` tools, not this one.
+ *
+ * The controller trusts its caller to send an id that exists, because the
+ * console only ever sends ids it listed. A model may not, and the gateway
+ * treats a missing file as "no channels" — so a typo would read as an empty
+ * set, and a write would create files under an agent that is not there. The
+ * tool therefore resolves the agent first and names it in the answer.
+ */
+@Injectable()
+export class AgentChannelTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(AgentChannelTool.name);
+
+  constructor(
+    private readonly channels: IAgentChannelGateway,
+    private readonly agents: IAgentGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'get_agent_channels',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Show delivery channels',
+    template: 'Which channels is the agent «name» connected to?',
+    description:
+      'The delivery channels an agent is configured for (Telegram in v1) ' +
+      'with the live state the runtime last reported: connected true = ' +
+      'polling, false = the last start failed (see statusReason), null = ' +
+      'nothing reported yet. Bot tokens are never returned. Returns an empty ' +
+      'list when nothing is configured. Takes the agent id — resolve a name ' +
+      'with list_agents first.',
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+    }),
+  })
+  async getAgentChannels(
+    { agentId }: { agentId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    const channels = await this.channels.getForAgent(agentId);
+    return ok({
+      agentId: agent.id,
+      agentName: agent.name,
+      channels: stripSecrets(channels, CHANNEL_SECRET_KEYS),
+    });
+  }
+
+  @Tool({
+    name: 'set_agent_channels',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Set delivery channels',
+    template: 'Connect the agent «name» to «channel list»',
+    description:
+      "Replace the agent's delivery channels with exactly this list — a " +
+      'channel left out is disconnected, and an empty list disconnects all. ' +
+      'Read get_agent_channels first so nothing is dropped by accident. The ' +
+      'bot token you pass is stored and never echoed back. A running agent ' +
+      'picks the change up on its next restart (restart_agent). Takes the ' +
+      'agent id — resolve a name with list_agents first.',
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+      channels: z
+        .array(telegramChannel)
+        .max(MAX_CHANNELS)
+        .describe(
+          'The full set of channels. Pass [] to disconnect every channel.',
+        ),
+    }),
+  })
+  async setAgentChannels(
+    { agentId, channels }: { agentId: string; channels: ChannelInput[] },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    const saved = await this.channels.setForAgent(
+      agentId,
+      channels as IAgentChannel[],
+    );
+    this.logger.log(
+      `Channels set through MCP: agent=${agentId} types=${
+        channels.map((c) => c.type).join(',') || 'none'
+      }`,
+    );
+    return ok({
+      message:
+        channels.length === 0
+          ? `Every channel of «${agent.name}» is now disconnected.`
+          : `Channels of «${agent.name}» replaced.`,
+      channels: stripSecrets(saved, CHANNEL_SECRET_KEYS),
+      note:
+        'A running agent keeps its old channel settings until it restarts — ' +
+        `restart_agent with id=${agentId} when the person is ready.`,
+    });
+  }
+}
+
+function notFound(agentId: string): ToolResult {
+  return ok({
+    error: `Agent ${agentId} not found — call list_agents to find the id`,
+  });
+}
diff --git a/api/src/slices/agent/file/file.module.ts b/api/src/slices/agent/file/file.module.ts
index cf790c92..b09c5578 100644
--- a/api/src/slices/agent/file/file.module.ts
+++ b/api/src/slices/agent/file/file.module.ts
@@ -3,6 +3,7 @@ import { AgentModule } from '#/agent/agent/agent.module';
 import { SettingModule } from '#/setting/setting.module';
 import { BridleModule } from '#/bridle/bridle.module';
 import { FileController } from './file.controller';
+import { FileTool } from './file.tool';
 import { IFileGateway } from './domain/file.gateway';
 import { S3FileGateway } from './data/file.gateway';
 import { SyncGuardService } from './domain/syncGuard.service';
@@ -25,6 +26,8 @@ import { TranscriptReaderService } from './domain/transcriptReader.service';
     },
     SyncGuardService,
     TranscriptReaderService,
+    // MCP tools of this slice (CLEAN-109): discovered by the registry.
+    FileTool,
   ],
   exports: [IFileGateway, TranscriptReaderService],
 })
diff --git a/api/src/slices/agent/file/file.tool.spec.ts b/api/src/slices/agent/file/file.tool.spec.ts
new file mode 100644
index 00000000..44216d69
--- /dev/null
+++ b/api/src/slices/agent/file/file.tool.spec.ts
@@ -0,0 +1,291 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { FileTool } from './file.tool';
+import type { IAgentGateway } from '#/agent/agent/domain';
+import type { IBridleGateway } from '#/bridle/domain';
+import type { IFileGateway, SyncGuardService } from './domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Two things matter more than the happy paths here: that a plain agent can
+ * neither see nor call these tools, and that the sync guard (CLEAN-50) and
+ * the delete confirmation both stop BEFORE anything touches S3 or the pod.
+ */
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+const agentRow = (overrides: Record<string, unknown> = {}) => ({
+  id: 'agent-a',
+  name: 'Support Bot',
+  lastPullAt: new Date('2026-09-17T10:00:00.000Z'),
+  lastSyncAt: null,
+  ...overrides,
+});
+
+interface Harness {
+  tool: FileTool;
+  agents: { findById: jest.Mock; setLastSyncAt: jest.Mock };
+  files: { list: jest.Mock; delete: jest.Mock; deletePrefix: jest.Mock };
+  bridle: { syncAgent: jest.Mock };
+  syncGuard: { assess: jest.Mock };
+}
+
+function harness(): Harness {
+  const agents = {
+    findById: jest.fn().mockResolvedValue(agentRow()),
+    setLastSyncAt: jest.fn().mockResolvedValue(undefined),
+  };
+  const files = {
+    list: jest.fn().mockResolvedValue([
+      {
+        path: 'SOUL.md',
+        size: 10,
+        updatedAt: new Date('2026-09-17T09:00:00.000Z'),
+      },
+      {
+        path: 'skills/x/SKILL.md',
+        size: 20,
+        updatedAt: new Date('2026-09-17T09:00:00.000Z'),
+      },
+    ]),
+    delete: jest.fn().mockResolvedValue(undefined),
+    deletePrefix: jest.fn().mockResolvedValue(3),
+  };
+  const bridle = {
+    syncAgent: jest.fn().mockResolvedValue({ agentOnline: true, pushed: 4 }),
+  };
+  const syncGuard = {
+    assess: jest.fn().mockResolvedValue({ baseline: null, atRisk: [] }),
+  };
+
+  const tool = new FileTool(
+    agents as unknown as IAgentGateway,
+    files as unknown as IFileGateway,
+    bridle as unknown as IBridleGateway,
+    syncGuard as unknown as SyncGuardService,
+  );
+  return { tool, agents, files, bridle, syncGuard };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('FileTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, files, bridle } = harness();
+    await expect(
+      tool.deleteAgentFile(
+        { agentId: 'agent-a', path: 'SOUL.md', confirm: true },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(
+      tool.syncAgentFiles({ agentId: 'agent-a' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(
+      tool.exportAgentFiles({ agentId: 'agent-a' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(files.delete).not.toHaveBeenCalled();
+    expect(bridle.syncAgent).not.toHaveBeenCalled();
+  });
+});
+
+describe('delete_agent_file', () => {
+  it('reports an unknown agent before asking for a confirmation', async () => {
+    const { tool, agents, files } = harness();
+    agents.findById.mockResolvedValue(null);
+    const result = await tool.deleteAgentFile(
+      { agentId: 'nope', path: 'SOUL.md' },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('not found');
+    expect(textOf(result)).toContain('list_agents');
+    expect(files.delete).not.toHaveBeenCalled();
+  });
+
+  it('refuses without confirm and names the file and the agent', async () => {
+    const { tool, files } = harness();
+    const result = await tool.deleteAgentFile(
+      { agentId: 'agent-a', path: 'SOUL.md' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('«SOUL.md»');
+    expect(textOf(result)).toContain('«Support Bot»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(files.delete).not.toHaveBeenCalled();
+    expect(files.deletePrefix).not.toHaveBeenCalled();
+  });
+
+  it('deletes one file when confirmed', async () => {
+    const { tool, files } = harness();
+    const result = await tool.deleteAgentFile(
+      { agentId: 'agent-a', path: 'SOUL.md', confirm: true },
+      null,
+      operator(),
+    );
+    expect(files.delete).toHaveBeenCalledWith('agent-a', 'SOUL.md');
+    expect(files.deletePrefix).not.toHaveBeenCalled();
+    const body = JSON.parse(textOf(result));
+    expect(body.deleted).toBe(1);
+    expect(body.recursive).toBe(false);
+    expect(body.notice).toContain('restart');
+  });
+
+  it('deletes a whole folder when recursive, as the console does', async () => {
+    const { tool, files } = harness();
+    const result = await tool.deleteAgentFile(
+      { agentId: 'agent-a', path: 'skills/x', recursive: true, confirm: true },
+      null,
+      operator(),
+    );
+    expect(files.deletePrefix).toHaveBeenCalledWith('agent-a', 'skills/x');
+    expect(files.delete).not.toHaveBeenCalled();
+    const body = JSON.parse(textOf(result));
+    expect(body.deleted).toBe(3);
+    expect(body.recursive).toBe(true);
+  });
+});
+
+describe('sync_agent_files', () => {
+  it('reports an unknown agent and does not touch the pod', async () => {
+    const { tool, agents, bridle, syncGuard } = harness();
+    agents.findById.mockResolvedValue(null);
+    const result = await tool.syncAgentFiles(
+      { agentId: 'nope' },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('not found');
+    expect(syncGuard.assess).not.toHaveBeenCalled();
+    expect(bridle.syncAgent).not.toHaveBeenCalled();
+  });
+
+  it('assesses with the agent markers and syncs when nothing is at risk', async () => {
+    const { tool, agents, bridle, syncGuard } = harness();
+    const result = await tool.syncAgentFiles(
+      { agentId: 'agent-a' },
+      null,
+      operator(),
+    );
+    expect(syncGuard.assess).toHaveBeenCalledWith(
+      'agent-a',
+      new Date('2026-09-17T10:00:00.000Z'),
+      null,
+    );
+    expect(bridle.syncAgent).toHaveBeenCalledWith('agent-a');
+    expect(agents.setLastSyncAt).toHaveBeenCalledWith('agent-a');
+    const body = JSON.parse(textOf(result));
+    expect(body).toMatchObject({ agentOnline: true, pushed: 4 });
+    expect(body.notice).toBeUndefined();
+  });
+
+  it('refuses with the at-risk list and does NOT sync', async () => {
+    const { tool, bridle, agents, syncGuard } = harness();
+    syncGuard.assess.mockResolvedValue({
+      baseline: new Date('2026-09-17T09:59:00.000Z'),
+      atRisk: [
+        {
+          path: 'SOUL.md',
+          size: 10,
+          updatedAt: new Date('2026-09-17T11:00:00.000Z'),
+        },
+      ],
+    });
+    const result = await tool.syncAgentFiles(
+      { agentId: 'agent-a' },
+      null,
+      operator(),
+    );
+    const body = JSON.parse(textOf(result));
+    expect(body.requiresConfirmation).toBe(true);
+    expect(body.atRisk).toEqual([
+      { path: 'SOUL.md', updatedAt: '2026-09-17T11:00:00.000Z' },
+    ]);
+    expect(body.baseline).toBe('2026-09-17T09:59:00.000Z');
+    expect(body.notice).toContain('confirm: true');
+    expect(bridle.syncAgent).not.toHaveBeenCalled();
+    expect(agents.setLastSyncAt).not.toHaveBeenCalled();
+  });
+
+  it('skips the guard once the person accepted the risk', async () => {
+    const { tool, bridle, syncGuard } = harness();
+    syncGuard.assess.mockResolvedValue({
+      baseline: new Date('2026-09-17T09:59:00.000Z'),
+      atRisk: [
+        {
+          path: 'SOUL.md',
+          size: 10,
+          updatedAt: new Date('2026-09-17T11:00:00.000Z'),
+        },
+      ],
+    });
+    await tool.syncAgentFiles(
+      { agentId: 'agent-a', confirm: true },
+      null,
+      operator(),
+    );
+    expect(syncGuard.assess).not.toHaveBeenCalled();
+    expect(bridle.syncAgent).toHaveBeenCalledWith('agent-a');
+  });
+
+  it('does not advance the baseline when the agent is offline', async () => {
+    const { tool, agents, bridle } = harness();
+    bridle.syncAgent.mockResolvedValue({ agentOnline: false, pushed: 0 });
+    const result = await tool.syncAgentFiles(
+      { agentId: 'agent-a' },
+      null,
+      operator(),
+    );
+    expect(agents.setLastSyncAt).not.toHaveBeenCalled();
+    const body = JSON.parse(textOf(result));
+    expect(body).toMatchObject({ agentOnline: false, pushed: 0 });
+    expect(body.notice).toContain('not connected');
+  });
+});
+
+describe('export_agent_files', () => {
+  it('hands back the console download path and the file count', async () => {
+    const { tool, files } = harness();
+    const result = await tool.exportAgentFiles(
+      { agentId: 'agent-a' },
+      null,
+      operator(),
+    );
+    expect(files.list).toHaveBeenCalledWith('agent-a');
+    const body = JSON.parse(textOf(result));
+    expect(body.downloadPath).toBe('/agents/agent-a/files/export');
+    expect(body.fileCount).toBe(2);
+    expect(body.note).toContain('login');
+  });
+
+  it('reports an unknown agent', async () => {
+    const { tool, agents, files } = harness();
+    agents.findById.mockResolvedValue(null);
+    const result = await tool.exportAgentFiles(
+      { agentId: 'nope' },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('not found');
+    expect(files.list).not.toHaveBeenCalled();
+  });
+});
diff --git a/api/src/slices/agent/file/file.tool.ts b/api/src/slices/agent/file/file.tool.ts
new file mode 100644
index 00000000..ca53d0aa
--- /dev/null
+++ b/api/src/slices/agent/file/file.tool.ts
@@ -0,0 +1,230 @@
+import { Inject, Injectable, forwardRef } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  CONFIRM_SENTENCE,
+  callerIsOperator,
+  confirmed,
+  ok,
+  requireOperator,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IBridleGateway } from '#/bridle/domain';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { IFileGateway, SyncGuardService } from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/**
+ * The workspace actions of the console's Files tab that `rancher.tool.ts`
+ * did not cover (CLEAN-109): delete, sync from the pod, export. Listing,
+ * reading and writing files stay where they were.
+ *
+ * Each method mirrors the matching `FileController` handler — same
+ * gateways, same guards, same response shape — so an agent cannot do from
+ * the chat what the console would have refused. The sync guard (CLEAN-50)
+ * in particular is copied rather than referenced: the pod pushes blindly
+ * over S3, and the at-risk list is the only thing standing between an
+ * operator and a silent overwrite.
+ *
+ * Operator-only: hidden from plain agents and refused if called anyway.
+ */
+@Injectable()
+export class FileTool implements IConditionallyListedTool {
+  constructor(
+    @Inject(forwardRef(() => IAgentGateway))
+    private readonly agents: IAgentGateway,
+    private readonly files: IFileGateway,
+    @Inject(forwardRef(() => IBridleGateway))
+    private readonly bridle: IBridleGateway,
+    private readonly syncGuard: SyncGuardService,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return callerIsOperator(httpRequest);
+  }
+
+  @Tool({
+    name: 'delete_agent_file',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Delete a workspace file',
+    template: 'Delete «path» from the agent «name»',
+    destructive: true,
+    description:
+      'Delete one file from the agent workspace in S3, or a whole folder ' +
+      '(for example a skill directory) when `recursive` is true. Resolve the ' +
+      'agent id with list_agents and the path with list_agent_files first. ' +
+      'Returns the number of objects deleted. Template-managed skills come ' +
+      'back on the next restart unless the agent is detached from the ' +
+      'template. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      agentId: z.string(),
+      path: z.string().describe('Relative path, e.g. skills/x-poster/SKILL.md'),
+      recursive: z
+        .boolean()
+        .optional()
+        .describe(
+          'When true, `path` is a folder and every file under it is deleted.',
+        ),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteAgentFile(
+    args: {
+      agentId: string;
+      path: string;
+      recursive?: boolean;
+      confirm?: boolean;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(args.agentId);
+    if (!agent) return this.agentNotFound(args.agentId);
+
+    const what = args.recursive
+      ? `delete the folder «${args.path}» and everything under it from the agent «${agent.name}»`
+      : `delete «${args.path}» from the agent «${agent.name}»`;
+    const refusal = confirmed(args, what);
+    if (refusal) return refusal;
+
+    let deleted = 1;
+    if (args.recursive) {
+      deleted = await this.files.deletePrefix(args.agentId, args.path);
+    } else {
+      await this.files.delete(args.agentId, args.path);
+    }
+
+    return ok({
+      agentId: args.agentId,
+      path: args.path,
+      recursive: Boolean(args.recursive),
+      deleted,
+      notice:
+        'Removed from S3 only. The running agent keeps its boot-time copy ' +
+        'until restarted; a template-managed skill is recreated on restart ' +
+        'unless the agent is detached from its template.',
+    });
+  }
+
+  @Tool({
+    name: 'sync_agent_files',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Sync files from the pod',
+    template: 'Sync the workspace files of the agent «name» from its pod',
+    description:
+      'Ask the running agent to push its local workspace files to S3, so the ' +
+      'console and read_agent_file see what the pod sees. Refuses with an ' +
+      '`atRisk` list (and does NOT sync) when S3 holds files edited after ' +
+      "the pod's last pull or push — those could be overwritten. Show the " +
+      'list to the person; call again with `confirm: true` only after they ' +
+      'accepted the risk. Returns `agentOnline` and the number of files ' +
+      'pushed; an offline agent pushes nothing.',
+    parameters: z.object({
+      agentId: z.string(),
+      confirm: z
+        .boolean()
+        .optional()
+        .describe(
+          'Set true only after the person saw the at-risk list and accepted ' +
+            'that those S3 files may be overwritten.',
+        ),
+    }),
+  })
+  async syncAgentFiles(
+    args: { agentId: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(args.agentId);
+    if (!agent) return this.agentNotFound(args.agentId);
+
+    // Same guard as FileController.sync (CLEAN-50): `confirm` skips the
+    // check because the operator already saw and accepted the list.
+    if (!args.confirm) {
+      const { baseline, atRisk } = await this.syncGuard.assess(
+        args.agentId,
+        agent.lastPullAt,
+        agent.lastSyncAt,
+      );
+      if (baseline && atRisk.length > 0) {
+        return ok({
+          requiresConfirmation: true,
+          synced: false,
+          atRisk: atRisk.map((n) => ({
+            path: n.path,
+            updatedAt: n.updatedAt.toISOString(),
+          })),
+          baseline: baseline.toISOString(),
+          notice:
+            'Not synced. These S3 files changed after the pod last aligned ' +
+            'with S3 and a sync may overwrite them. Show the list to the ' +
+            'person; call again with confirm: true once they accept.',
+        });
+      }
+    }
+
+    const result = await this.bridle.syncAgent(args.agentId);
+    // Offline sync did nothing, so it must not advance the conflict baseline.
+    if (result.agentOnline) {
+      await this.agents.setLastSyncAt(args.agentId);
+    }
+    return ok({
+      agentId: args.agentId,
+      agentOnline: result.agentOnline,
+      pushed: result.pushed,
+      ...(result.agentOnline
+        ? {}
+        : {
+            notice:
+              'The agent is not connected, nothing was pushed. Start or ' +
+              'restart it and sync again.',
+          }),
+    });
+  }
+
+  @Tool({
+    name: 'export_agent_files',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Export the workspace',
+    template: 'Export the workspace of the agent «name»',
+    description:
+      'Prepare a download of the whole agent workspace (files, skills, ' +
+      'runtime state) as a zip — the safety net before a destructive change. ' +
+      'The zip cannot travel through the chat: the result gives the console ' +
+      'path to open (it needs the person’s login) and how many files the ' +
+      'archive will hold. Resolve the agent id with list_agents first.',
+    parameters: z.object({ agentId: z.string() }),
+  })
+  async exportAgentFiles(
+    { agentId }: { agentId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ) {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return this.agentNotFound(agentId);
+
+    const nodes = await this.files.list(agentId);
+    return ok({
+      agentId,
+      agentName: agent.name,
+      fileCount: nodes.length,
+      downloadPath: `/agents/${agentId}/files/export`,
+      note: 'Open this path in the console (it needs your login) to download the zip.',
+    });
+  }
+
+  private agentNotFound(agentId: string) {
+    return ok({
+      error: `Agent ${agentId} not found — call list_agents to find the id`,
+    });
+  }
+}
diff --git a/api/src/slices/agent/peer/askAgent.tool.ts b/api/src/slices/agent/peer/askAgent.tool.ts
index 2f095fc6..ea5b9b4b 100644
--- a/api/src/slices/agent/peer/askAgent.tool.ts
+++ b/api/src/slices/agent/peer/askAgent.tool.ts
@@ -1,6 +1,6 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
 import type { Request } from 'express';
 import type { IAuthTokenPayload } from '#/user/auth/domain/auth.types';
 import type { IDynamicallyDescribedTool } from '#/mcp/interfaces/dynamic-description.interface';
@@ -155,6 +155,9 @@ export class AskAgentTool
 
   @Tool({
     name: 'ask_agent',
+    topic: ToolTopics.Peers,
+    title: 'Ask a peer agent',
+    template: 'Ask your peer «name» to «task»',
     description: NO_PEERS_DESCRIPTION,
     parameters: schema,
   })
diff --git a/api/src/slices/agent/peer/peerAdmin.tool.spec.ts b/api/src/slices/agent/peer/peerAdmin.tool.spec.ts
index e4ee3da7..8dd8bb6d 100644
--- a/api/src/slices/agent/peer/peerAdmin.tool.spec.ts
+++ b/api/src/slices/agent/peer/peerAdmin.tool.spec.ts
@@ -326,7 +326,7 @@ describe('PeerAdminTool — changing the peer set', () => {
     const { tool, peers } = harness();
     const text = textOf(
       await tool.removeAgentPeer(
-        { agentId: 'agent-a', peerId: 'peer-1' },
+        { agentId: 'agent-a', peerId: 'peer-1', confirm: true },
         null,
         operator(),
       ),
@@ -334,6 +334,18 @@ describe('PeerAdminTool — changing the peer set', () => {
     expect(peers.remove).toHaveBeenCalledWith('agent-a', 'peer-1');
     expect(text).toContain('still believes it has that colleague');
   });
+
+  it('refuses to remove a peer without the confirmation argument (CLEAN-109)', async () => {
+    const { tool, peers } = harness();
+    const result = await tool.removeAgentPeer(
+      { agentId: 'agent-a', peerId: 'peer-1' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(peers.remove).not.toHaveBeenCalled();
+  });
 });
 
 describe('PeerAdminTool — refusals carry the next move', () => {
diff --git a/api/src/slices/agent/peer/peerAdmin.tool.ts b/api/src/slices/agent/peer/peerAdmin.tool.ts
index 3a97bb8f..cfcdb27e 100644
--- a/api/src/slices/agent/peer/peerAdmin.tool.ts
+++ b/api/src/slices/agent/peer/peerAdmin.tool.ts
@@ -1,7 +1,8 @@
 import { ForbiddenException, Injectable, Logger } from '@nestjs/common';
 import { Request } from 'express';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
+import { CONFIRM_SENTENCE, confirmed } from '#/mcp/tooling';
 import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
 import { PeerService } from './domain/peer.service';
 import { AgentCardService } from './domain/agentCard.service';
@@ -77,6 +78,9 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'list_agent_peers',
+    topic: ToolTopics.Peers,
+    title: "List an agent's peers",
+    template: 'Which peers does the agent «name» have?',
     description:
       'Who an agent can delegate to: every peer connected to it, what each ' +
       "peer's card advertises, and whether the running pod has actually " +
@@ -115,6 +119,9 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'list_peer_candidates',
+    topic: ToolTopics.Peers,
+    title: 'Agents that can become peers',
+    template: 'Which agents could «name» delegate to?',
     description:
       'Agents of this Ranch that could become peers of the given agent, each ' +
       'marked with whether it already is one. Use it to turn a name the ' +
@@ -134,6 +141,9 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'preview_agent_card',
+    topic: ToolTopics.Peers,
+    title: "Preview an agent's card",
+    template: 'Show the A2A card of the agent «name»',
     description:
       'Read a card WITHOUT connecting anything: what that agent tells other ' +
       'agents it can do. Pass `peerAgentId` for an agent of this Ranch, or ' +
@@ -190,6 +200,9 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'list_agent_delegations',
+    topic: ToolTopics.Peers,
+    title: 'Recent delegations',
+    template: 'What did the agent «name» delegate recently?',
     description:
       'What this agent recently handed to its peers: the task, the peer it ' +
       'picked, the reason it gave, how it ended and an excerpt of the reply. ' +
@@ -226,6 +239,9 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'connect_agent_peer',
+    topic: ToolTopics.Peers,
+    title: 'Connect a peer',
+    template: 'Connect the agent «peer» as a peer of «name»',
     description:
       'Let one agent of this Ranch delegate to another: reads the peer card, ' +
       'mints a credential for exactly this pair and saves the connection. ' +
@@ -258,6 +274,9 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'import_external_agent',
+    topic: ToolTopics.Peers,
+    title: 'Import an external A2A agent',
+    template: 'Import the external agent at «url» as a peer of «name»',
     description:
       'Connect an A2A agent outside this Ranch by its address, so the given ' +
       'agent can delegate to it. Reads the card first and saves nothing if it ' +
@@ -306,6 +325,9 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'refresh_agent_peer',
+    topic: ToolTopics.Peers,
+    title: "Refresh a peer's card",
+    template: 'Refresh the card of the peer «peer» on the agent «name»',
     description:
       "Re-read a peer's card, for when its owner says it can do something " +
       'new. A failed read keeps the card already stored — a stale description ' +
@@ -336,23 +358,34 @@ export class PeerAdminTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'remove_agent_peer',
+    topic: ToolTopics.Peers,
+    title: 'Remove a peer',
+    template: 'Remove the peer «peer» from the agent «name»',
+    destructive: true,
     description:
       'Disconnect a peer. For a peer of this Ranch the credential issued for ' +
       'the pair stops working — there is no other copy of it. Reversible: ' +
-      'connect it again later and a new credential is minted.',
+      'connect it again later and a new credential is minted. ' +
+      CONFIRM_SENTENCE,
     parameters: z.object({
       agentId: z.string(),
       peerId: z
         .string()
         .describe('Connection id from list_agent_peers (not the agent id)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
     }),
   })
   async removeAgentPeer(
-    { agentId, peerId }: { agentId: string; peerId: string },
+    args: { agentId: string; peerId: string; confirm?: boolean },
     _context: unknown,
     httpRequest: Request,
   ): Promise<ToolResult> {
     this.requireOperator(httpRequest);
+    const { agentId, peerId } = args;
+    const refusal = confirmed(args, `disconnect peer ${peerId} from agent ${agentId}`);
+    if (refusal) return refusal;
     return this.guard(async () => {
       await this.peers.remove(agentId, peerId);
       this.logger.log(
diff --git a/api/src/slices/agent/peer/peerSelf.tool.spec.ts b/api/src/slices/agent/peer/peerSelf.tool.spec.ts
index 37c2df1f..4962b0b9 100644
--- a/api/src/slices/agent/peer/peerSelf.tool.spec.ts
+++ b/api/src/slices/agent/peer/peerSelf.tool.spec.ts
@@ -298,17 +298,37 @@ describe('PeerSelfTool — reading and dropping', () => {
     const { tool, peers } = harness();
     peers.list.mockResolvedValue([view({ peerName: 'Skyhunter' })]);
     const text = textOf(
-      await tool.removeMyPeer({ peerId: 'peer-1' }, null, agentRequest()),
+      await tool.removeMyPeer(
+        { peerId: 'peer-1', confirm: true },
+        null,
+        agentRequest(),
+      ),
     );
     expect(peers.remove).toHaveBeenCalledWith('agent-me', 'peer-1');
     expect(text).toContain('«Skyhunter»');
   });
 
+  it('refuses to drop a peer without the confirmation argument (CLEAN-109)', async () => {
+    const { tool, peers } = harness();
+    const result = await tool.removeMyPeer(
+      { peerId: 'peer-1' },
+      null,
+      agentRequest(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(peers.remove).not.toHaveBeenCalled();
+  });
+
   it('says the ask_agent tool itself goes away with the last colleague', async () => {
     const { tool, peers } = harness();
     peers.list.mockResolvedValue([]);
     const text = textOf(
-      await tool.removeMyPeer({ peerId: 'peer-1' }, null, agentRequest()),
+      await tool.removeMyPeer(
+        { peerId: 'peer-1', confirm: true },
+        null,
+        agentRequest(),
+      ),
     );
     expect(text).toContain('last colleague');
     expect(text).toContain('ask_agent');
diff --git a/api/src/slices/agent/peer/peerSelf.tool.ts b/api/src/slices/agent/peer/peerSelf.tool.ts
index 2ec35d51..23436ab1 100644
--- a/api/src/slices/agent/peer/peerSelf.tool.ts
+++ b/api/src/slices/agent/peer/peerSelf.tool.ts
@@ -1,7 +1,8 @@
 import { ForbiddenException, Injectable, Logger } from '@nestjs/common';
 import { Request } from 'express';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
+import { CONFIRM_SENTENCE, confirmed } from '#/mcp/tooling';
 import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
 import { ISettingGateway } from '#/setting/domain';
 import { PeerService } from './domain/peer.service';
@@ -111,6 +112,9 @@ export class PeerSelfTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'list_my_peers',
+    topic: ToolTopics.Peers,
+    title: 'My peers',
+    template: 'Who are your peers?',
     description:
       'The colleagues you can delegate to, with what each one advertises. ' +
       'Read this before connecting anything someone asks for — you may have ' +
@@ -138,6 +142,9 @@ export class PeerSelfTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'list_ranch_agents',
+    topic: ToolTopics.Peers,
+    title: 'Agents of this Ranch',
+    template: 'Which agents on this Ranch could you ask for help?',
     description:
       'The other agents living on this Ranch, each marked with whether it is ' +
       'already your colleague. Use it to turn a name a person said into the ' +
@@ -158,6 +165,9 @@ export class PeerSelfTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'preview_agent_card_by_address',
+    topic: ToolTopics.Peers,
+    title: 'Preview a card by address',
+    template: 'What does the agent at «url» say it can do?',
     description:
       'Read another agent’s A2A card from its address WITHOUT connecting ' +
       'anything — its name, what it says it does, the skills it publishes. ' +
@@ -194,6 +204,9 @@ export class PeerSelfTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'connect_my_peer',
+    topic: ToolTopics.Peers,
+    title: 'Connect a peer for yourself',
+    template: 'Add the agent «name» as your peer',
     description:
       'Take an agent of this Ranch as your colleague, so you can hand it ' +
       'tasks with ask_agent. Directed: it gains nothing in return. Nothing is ' +
@@ -226,6 +239,9 @@ export class PeerSelfTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'import_my_peer_by_address',
+    topic: ToolTopics.Peers,
+    title: 'Import a peer by address',
+    template: 'Add the external agent at «url» as your peer',
     description:
       'Take an A2A agent from outside this Ranch as your colleague, by its ' +
       'address. This is what a pasted /.well-known/agent-card.json link is ' +
@@ -272,21 +288,32 @@ export class PeerSelfTool implements IConditionallyListedTool {
 
   @Tool({
     name: 'remove_my_peer',
+    topic: ToolTopics.Peers,
+    title: 'Remove one of my peers',
+    template: 'Drop your peer «name»',
+    destructive: true,
     description:
       'Drop one of your colleagues. For an agent of this Ranch the credential ' +
-      'issued for the pair stops working. Reversible — connect it again later.',
+      'issued for the pair stops working. Reversible — connect it again later. ' +
+      CONFIRM_SENTENCE,
     parameters: z.object({
       peerId: z
         .string()
         .describe('Connection id from list_my_peers (not the agent id)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
     }),
   })
   async removeMyPeer(
-    { peerId }: { peerId: string },
+    args: { peerId: string; confirm?: boolean },
     _context: unknown,
     httpRequest: Request,
   ): Promise<ToolResult> {
     const agentId = await this.requireSelf(httpRequest);
+    const { peerId } = args;
+    const refusal = confirmed(args, `drop your peer connection ${peerId}`);
+    if (refusal) return refusal;
     return withRefusalAdvice(async () => {
       await this.peers.remove(agentId, peerId);
       this.logger.log(
diff --git a/api/src/slices/agent/peer/toolSupport.ts b/api/src/slices/agent/peer/toolSupport.ts
index 610575cc..e3fdf247 100644
--- a/api/src/slices/agent/peer/toolSupport.ts
+++ b/api/src/slices/agent/peer/toolSupport.ts
@@ -1,42 +1,17 @@
 import { HttpException } from '@nestjs/common';
-import type { Request } from 'express';
-import type { IAuthTokenPayload } from '#/user/auth/domain/auth.types';
-import { UserRoleTypes } from '#/user/user/domain';
+import { err, type ToolResult } from '#/mcp/tooling';
 import { PeerErrorCodes, type IAgentPeerView } from './domain/peer.types';
 
-/** What an MCP tool hands back. The shape the SDK expects, nothing more. */
-export interface ToolResult {
-  content: { type: 'text'; text: string }[];
-  isError?: boolean;
-}
-
-export const ok = (value: unknown): ToolResult => ({
-  content: [
-    {
-      type: 'text',
-      text: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
-    },
-  ],
-});
-
-export const err = (text: string): ToolResult => ({
-  content: [{ type: 'text', text }],
-  isError: true,
-});
-
-/** Agent service tokens carry `sub = agent:<id>`; anything else is not an agent. */
-export function callerAgentId(httpRequest: Request): string | null {
-  const user = (httpRequest as Request & { user?: IAuthTokenPayload }).user;
-  const sub = user?.sub ?? '';
-  if (!sub.startsWith('agent:')) return null;
-  return sub.slice('agent:'.length);
-}
-
-/** Admin agents hold the Owner role; plain agents hold `Agent` (auth.service). */
-export function callerIsOperator(httpRequest: Request): boolean {
-  const user = (httpRequest as Request & { user?: IAuthTokenPayload }).user;
-  return (user?.roles ?? []).includes(UserRoleTypes.Owner);
-}
+// The result shape and caller helpers moved to the shared `#/mcp/tooling`
+// (CLEAN-109) so every tool file speaks the same vocabulary; re-exported here
+// so the peer tools and their specs read as before.
+export {
+  ok,
+  err,
+  callerAgentId,
+  callerIsOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
 
 /** Peers as a model needs them: what it is, what it claims, is it usable. */
 export function toToolPeer(view: IAgentPeerView) {
diff --git a/api/src/slices/agent/secret/secret.module.ts b/api/src/slices/agent/secret/secret.module.ts
index eb729473..b8341775 100644
--- a/api/src/slices/agent/secret/secret.module.ts
+++ b/api/src/slices/agent/secret/secret.module.ts
@@ -2,6 +2,7 @@ import { Module } from '@nestjs/common';
 import { AgentModule } from '#/agent/agent/agent.module';
 import { SettingModule } from '#/setting/setting.module';
 import { SecretController } from './secret.controller';
+import { SecretTool } from './secret.tool';
 import { ISecretGateway } from './domain';
 import { SecretGateway } from './data/secret.gateway';
 import { AwsSecretGateway } from './data/awsSecret.gateway';
@@ -17,6 +18,7 @@ import { FileSecretGateway } from './data/fileSecret.gateway';
       provide: ISecretGateway,
       useClass: SecretGateway,
     },
+    SecretTool,
   ],
   exports: [ISecretGateway],
 })
diff --git a/api/src/slices/agent/secret/secret.tool.spec.ts b/api/src/slices/agent/secret/secret.tool.spec.ts
new file mode 100644
index 00000000..b2ffd299
--- /dev/null
+++ b/api/src/slices/agent/secret/secret.tool.spec.ts
@@ -0,0 +1,334 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { SecretTool } from './secret.tool';
+import type { IAgentGateway } from '#/agent/agent/domain';
+import type { ISecretGateway } from './domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * These tools put credentials within a model's reach. The property worth
+ * more than any happy path is therefore that a value written through a tool
+ * never comes back out of one — not in a listing, not in an acknowledgement,
+ * not in a refusal. The sentinel below is the canary for that.
+ */
+const SENTINEL = 'SENTINEL-SECRET-42';
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+const agentRow = { id: 'agent-a', name: 'Support Bot' };
+
+const listing = (...entries: [string, string][]) => ({
+  provider: 'file' as const,
+  secrets: entries.map(([name, value]) => ({
+    name,
+    value,
+    updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  })),
+});
+
+interface Harness {
+  tool: SecretTool;
+  agents: { findById: jest.Mock };
+  secrets: {
+    list: jest.Mock;
+    set: jest.Mock;
+    delete: jest.Mock;
+    replaceAll: jest.Mock;
+  };
+}
+
+function harness(): Harness {
+  const agents = { findById: jest.fn().mockResolvedValue(agentRow) };
+  const secrets = {
+    list: jest
+      .fn()
+      .mockResolvedValue(
+        listing(['instagram:password', SENTINEL], ['paypal:api_token', 'sk-1']),
+      ),
+    set: jest.fn().mockResolvedValue(undefined),
+    delete: jest.fn().mockResolvedValue(undefined),
+    replaceAll: jest.fn().mockResolvedValue(undefined),
+  };
+  const tool = new SecretTool(
+    agents as unknown as IAgentGateway,
+    secrets as unknown as ISecretGateway,
+  );
+  return { tool, agents, secrets };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('SecretTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, secrets } = harness();
+    await expect(
+      tool.setAgentSecret(
+        { agentId: 'agent-a', key: 'k', value: SENTINEL },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(secrets.set).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool } = harness();
+    await expect(
+      tool.listAgentSecrets({ agentId: 'agent-a' }, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('SecretTool — listing', () => {
+  it('lists names and timestamps, never values', async () => {
+    const { tool, secrets } = harness();
+    const text = textOf(
+      await tool.listAgentSecrets({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(secrets.list).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('instagram:password');
+    expect(text).toContain('paypal:api_token');
+    expect(text).toContain('2026-09-17T10:00:00.000Z');
+    expect(text).toContain('"provider": "file"');
+    expect(text).toContain('Support Bot');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('sk-1');
+    expect(text).not.toContain('"value"');
+  });
+
+  it('names the next move when the agent does not exist', async () => {
+    const { tool, agents, secrets } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.listAgentSecrets({ agentId: 'agent-x' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_agents');
+    expect(secrets.list).not.toHaveBeenCalled();
+  });
+});
+
+describe('SecretTool — setting', () => {
+  it('writes through the gateway and acknowledges the key only', async () => {
+    const { tool, secrets } = harness();
+    const text = textOf(
+      await tool.setAgentSecret(
+        { agentId: 'agent-a', key: 'instagram:password', value: SENTINEL },
+        null,
+        operator(),
+      ),
+    );
+    expect(secrets.set).toHaveBeenCalledWith(
+      'agent-a',
+      'instagram:password',
+      SENTINEL,
+    );
+    expect(text).toContain('"ok": true');
+    expect(text).toContain('"agentId": "agent-a"');
+    expect(text).toContain('"key": "instagram:password"');
+    expect(text).toContain('restart_agent with id=agent-a');
+  });
+
+  it('never echoes the value it just stored, even though the store lists it', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.setAgentSecret(
+        { agentId: 'agent-a', key: 'instagram:password', value: SENTINEL },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('"value"');
+  });
+
+  it('does not write for an agent that does not exist', async () => {
+    const { tool, agents, secrets } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.setAgentSecret(
+        { agentId: 'agent-x', key: 'k', value: SENTINEL },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(text).not.toContain(SENTINEL);
+    expect(secrets.set).not.toHaveBeenCalled();
+  });
+});
+
+describe('SecretTool — deleting', () => {
+  it('deletes through the gateway once confirmed and lists what remains', async () => {
+    const { tool, secrets } = harness();
+    secrets.list.mockResolvedValue(listing(['paypal:api_token', 'sk-1']));
+    const text = textOf(
+      await tool.deleteAgentSecret(
+        { agentId: 'agent-a', key: 'instagram:password', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(secrets.delete).toHaveBeenCalledWith(
+      'agent-a',
+      'instagram:password',
+    );
+    expect(text).toContain('"key": "instagram:password"');
+    expect(text).toContain('paypal:api_token');
+    expect(text).not.toContain('sk-1');
+  });
+
+  it('refuses without the confirmation argument and touches nothing (CLEAN-109)', async () => {
+    const { tool, secrets } = harness();
+    const result = await tool.deleteAgentSecret(
+      { agentId: 'agent-a', key: 'instagram:password' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(textOf(result)).toContain('«instagram:password»');
+    expect(textOf(result)).toContain('«Support Bot»');
+    expect(secrets.delete).not.toHaveBeenCalled();
+  });
+
+  it('reports a missing agent before asking for confirmation', async () => {
+    const { tool, agents, secrets } = harness();
+    agents.findById.mockResolvedValue(null);
+    const result = await tool.deleteAgentSecret(
+      { agentId: 'agent-x', key: 'k' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(secrets.delete).not.toHaveBeenCalled();
+  });
+});
+
+describe('SecretTool — replacing the whole store', () => {
+  it('replaces through the gateway once confirmed and lists the new names', async () => {
+    const { tool, secrets } = harness();
+    secrets.list.mockResolvedValue(
+      listing(['a:key', SENTINEL], ['b:key', 'other']),
+    );
+    const text = textOf(
+      await tool.replaceAgentSecrets(
+        {
+          agentId: 'agent-a',
+          store: { 'a:key': SENTINEL, 'b:key': 'other' },
+          confirm: true,
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(secrets.replaceAll).toHaveBeenCalledWith('agent-a', {
+      'a:key': SENTINEL,
+      'b:key': 'other',
+    });
+    expect(text).toContain('"ok": true');
+    expect(text).toContain('a:key');
+    expect(text).toContain('b:key');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('other');
+  });
+
+  it('refuses without the confirmation argument, naming the keys and the loss', async () => {
+    const { tool, secrets } = harness();
+    const result = await tool.replaceAgentSecrets(
+      { agentId: 'agent-a', store: { 'a:key': SENTINEL } },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('a:key');
+    expect(textOf(result)).toContain('«Support Bot»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(textOf(result)).not.toContain(SENTINEL);
+    expect(secrets.replaceAll).not.toHaveBeenCalled();
+  });
+
+  it('spells out that an empty map clears the store', async () => {
+    const { tool } = harness();
+    const result = await tool.replaceAgentSecrets(
+      { agentId: 'agent-a', store: {} },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('remove every secret');
+  });
+
+  it('reports a missing agent before asking for confirmation', async () => {
+    const { tool, agents, secrets } = harness();
+    agents.findById.mockResolvedValue(null);
+    const result = await tool.replaceAgentSecrets(
+      { agentId: 'agent-x', store: {} },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('not found');
+    expect(secrets.replaceAll).not.toHaveBeenCalled();
+  });
+});
+
+describe('SecretTool — a value never leaves through any tool', () => {
+  it('keeps the sentinel out of every result text, refusals included', async () => {
+    const { tool } = harness();
+    const req = operator();
+    const results = [
+      await tool.listAgentSecrets({ agentId: 'agent-a' }, null, req),
+      await tool.setAgentSecret(
+        { agentId: 'agent-a', key: 'k', value: SENTINEL },
+        null,
+        req,
+      ),
+      await tool.deleteAgentSecret({ agentId: 'agent-a', key: 'k' }, null, req),
+      await tool.deleteAgentSecret(
+        { agentId: 'agent-a', key: 'k', confirm: true },
+        null,
+        req,
+      ),
+      await tool.replaceAgentSecrets(
+        { agentId: 'agent-a', store: { k: SENTINEL } },
+        null,
+        req,
+      ),
+      await tool.replaceAgentSecrets(
+        { agentId: 'agent-a', store: { k: SENTINEL }, confirm: true },
+        null,
+        req,
+      ),
+    ];
+    for (const result of results) {
+      for (const part of result.content) {
+        expect(part.text).not.toContain(SENTINEL);
+      }
+    }
+  });
+
+  it('lets a store failure escape, so the MCP layer reports it as an error', async () => {
+    const { tool, secrets } = harness();
+    secrets.list.mockRejectedValue(new Error('bucket unreachable'));
+    await expect(
+      tool.listAgentSecrets({ agentId: 'agent-a' }, null, operator()),
+    ).rejects.toThrow('bucket unreachable');
+  });
+});
diff --git a/api/src/slices/agent/secret/secret.tool.ts b/api/src/slices/agent/secret/secret.tool.ts
new file mode 100644
index 00000000..9459247c
--- /dev/null
+++ b/api/src/slices/agent/secret/secret.tool.ts
@@ -0,0 +1,271 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import type { IAuthTokenPayload } from '#/user/auth/domain';
+import { IAgentGateway } from '#/agent/agent/domain';
+import type { IAgentData } from '#/agent/agent/domain';
+import { ISecretGateway } from './domain';
+import type { ISecretListData } from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** What `SetSecretDto` / `DeleteSecretDto` allow for a key. */
+const MAX_KEY_LENGTH = 256;
+
+const keySchema = z
+  .string()
+  .min(1)
+  .max(MAX_KEY_LENGTH)
+  .describe('Secret key, e.g. instagram:password');
+
+/** What `ReplaceSecretsDto` allows: a flat string→string map, {} to clear. */
+const storeSchema = z
+  .record(z.string().min(1).max(MAX_KEY_LENGTH), z.string())
+  .describe(
+    'The complete new store as {KEY: value}. Pass {} to remove every secret.',
+  );
+
+/**
+ * An agent's secrets from the chat, the way the Secrets tab does it
+ * (CLEAN-109). Every call goes through `ISecretGateway`, the same facade
+ * `SecretController` uses, so the AWS-vs-file choice and the store format
+ * are decided in one place.
+ *
+ * The one rule that is this file's own: a value goes IN through a tool and
+ * never comes OUT. The console lists values because a person is looking; a
+ * tool result lands in a model's context and from there in a transcript, so
+ * listings carry names and timestamps only and a set acknowledges without
+ * echoing (FR-004).
+ *
+ * Operator agents only: a plain agent holds these secrets and must not be
+ * able to read, rewrite or erase its own credentials on a prompt's say-so.
+ */
+@Injectable()
+export class SecretTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(SecretTool.name);
+
+  constructor(
+    private readonly agents: IAgentGateway,
+    private readonly secrets: ISecretGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'list_agent_secrets',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'List secret names',
+    template: 'Which secrets does the agent «name» have?',
+    description:
+      'The names of the secrets stored for an agent and when each was last ' +
+      'changed — never the values; those are only ever written. Also says ' +
+      'which store holds them (aws or file). Read this before setting or ' +
+      'deleting a key to see what exists. Takes the agent id: list_agents ' +
+      'turns a name into one.',
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+    }),
+  })
+  async listAgentSecrets(
+    { agentId }: { agentId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    return ok(await this.summary(agent));
+  }
+
+  @Tool({
+    name: 'set_agent_secret',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Set a secret',
+    template: 'Set the secret «KEY» of the agent «name» to «value»',
+    description:
+      'Create or overwrite one secret of an agent (upsert). The result ' +
+      'acknowledges the key and lists the names now in the store; the value ' +
+      'is never repeated back, so do not expect to read it afterwards. The ' +
+      'store is written directly — no restart is triggered here. An agent ' +
+      'that already loaded this key when it started sees the new value ' +
+      'after restart_agent.',
+    parameters: z.object({
+      agentId: z.string().describe('Agent id (list_agents has them)'),
+      key: keySchema,
+      value: z.string().min(1).describe('The secret value to store'),
+    }),
+  })
+  async setAgentSecret(
+    { agentId, key, value }: { agentId: string; key: string; value: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    await this.secrets.set(agentId, key, value);
+    // Log the key, never the value: the API log is not a secret store.
+    this.logger.log(`Secret set through MCP: agent=${agentId} key=${key}`);
+    const data = await this.secrets.list(agentId);
+    return ok({
+      ok: true,
+      agentId,
+      key,
+      provider: data.provider,
+      secrets: names(data),
+      note: restartNote(agentId),
+    });
+  }
+
+  @Tool({
+    name: 'delete_agent_secret',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Delete a secret',
+    template: 'Delete the secret «KEY» of the agent «name»',
+    destructive: true,
+    description:
+      'Remove one secret from an agent. There is no other copy of the value, ' +
+      'so it cannot be restored — only set again if the person still has it. ' +
+      'A key that does not exist is a no-op. The result lists the names ' +
+      'that remain. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      agentId: z.string().describe('Agent id (list_agents has them)'),
+      key: keySchema,
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteAgentSecret(
+    args: { agentId: string; key: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { agentId, key } = args;
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    const refusal = confirmed(
+      args,
+      `delete the secret «${key}» of the agent «${agent.name}» — its value cannot be recovered`,
+    );
+    if (refusal) return refusal;
+    await this.secrets.delete(agentId, key);
+    this.logger.log(`Secret deleted through MCP: agent=${agentId} key=${key}`);
+    const data = await this.secrets.list(agentId);
+    return ok({
+      ok: true,
+      agentId,
+      key,
+      provider: data.provider,
+      secrets: names(data),
+      note: restartNote(agentId),
+    });
+  }
+
+  @Tool({
+    name: 'replace_agent_secrets',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Replace all secrets',
+    template: 'Replace all secrets of the agent «name» with: «KEY=value, …»',
+    destructive: true,
+    description:
+      "Replace an agent's whole secret store at once: every key not in the " +
+      'new map is removed, and removed values cannot be recovered. Pass {} ' +
+      'to clear the store. To change one key without touching the others use ' +
+      'set_agent_secret instead. The result lists the key names now stored, ' +
+      'never the values. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      agentId: z.string().describe('Agent id (list_agents has them)'),
+      store: storeSchema,
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async replaceAgentSecrets(
+    args: { agentId: string; store: Record<string, string>; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { agentId, store } = args;
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    const keys = Object.keys(store);
+    const refusal = confirmed(
+      args,
+      keys.length === 0
+        ? `remove every secret of the agent «${agent.name}»`
+        : `replace every secret of the agent «${agent.name}» with exactly ${keys.length} ` +
+            `(${keys.join(', ')}) — any other key is removed for good`,
+    );
+    if (refusal) return refusal;
+    await this.secrets.replaceAll(agentId, store);
+    this.logger.log(
+      `Secrets replaced through MCP: agent=${agentId} keys=${keys.length}`,
+    );
+    const data = await this.secrets.list(agentId);
+    return ok({
+      ok: true,
+      agentId,
+      provider: data.provider,
+      secrets: names(data),
+      note: restartNote(agentId),
+    });
+  }
+
+  /** The listing shape: names and timestamps, the values left in the store. */
+  private async summary(agent: IAgentData) {
+    const data = await this.secrets.list(agent.id);
+    return {
+      agentId: agent.id,
+      agentName: agent.name,
+      provider: data.provider,
+      secrets: data.secrets.map((s) => ({
+        name: s.name,
+        updatedAt: s.updatedAt ? s.updatedAt.toISOString() : null,
+      })),
+    };
+  }
+}
+
+function notFound(agentId: string): ToolResult {
+  return ok({
+    error: `Agent ${agentId} not found — call list_agents to find the id`,
+  });
+}
+
+/** Key names only, sorted so two listings of the same store read the same. */
+function names(data: ISecretListData): string[] {
+  return data.secrets.map((s) => s.name).sort();
+}
+
+/**
+ * The API writes the store and stops there; it is the runtime that reads
+ * secrets, and one that read a key at startup keeps what it read. Say so
+ * rather than let the model promise the person an instant effect.
+ */
+function restartNote(agentId: string): string {
+  return (
+    'Written to the store directly; no restart was triggered. If the running ' +
+    'agent already loaded this key when it started, it sees the change after ' +
+    `restart_agent with id=${agentId}.`
+  );
+}
diff --git a/api/src/slices/agent/shareLink/shareLink.module.ts b/api/src/slices/agent/shareLink/shareLink.module.ts
index 39bd7958..478a3a94 100644
--- a/api/src/slices/agent/shareLink/shareLink.module.ts
+++ b/api/src/slices/agent/shareLink/shareLink.module.ts
@@ -7,6 +7,7 @@ import { ShareLinkGateway } from './data/shareLink.gateway';
 import { ShareLinkMapper } from './data/shareLink.mapper';
 import { ShareLinkController } from './shareLink.controller';
 import { ShareController } from './share.controller';
+import { ShareLinkTool } from './shareLink.tool';
 
 // AgentModule must be a forwardRef here because BridleModule (which imports
 // ShareLinkModule for chat-time token validation) is itself imported by
@@ -24,6 +25,7 @@ import { ShareController } from './share.controller';
   providers: [
     ShareLinkMapper,
     ShareLinkService,
+    ShareLinkTool,
     {
       provide: IShareLinkGateway,
       useClass: ShareLinkGateway,
diff --git a/api/src/slices/agent/shareLink/shareLink.tool.spec.ts b/api/src/slices/agent/shareLink/shareLink.tool.spec.ts
new file mode 100644
index 00000000..ba59d4b0
--- /dev/null
+++ b/api/src/slices/agent/shareLink/shareLink.tool.spec.ts
@@ -0,0 +1,361 @@
+import { ForbiddenException, NotFoundException } from '@nestjs/common';
+import type { Request } from 'express';
+import { ShareLinkTool, resolveAppOrigin } from './shareLink.tool';
+import type { IShareLinkState, ShareLinkService } from './domain';
+import type { IAgentGateway } from '#/agent/agent/domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * A share link is a credential anyone can use, so the checks that matter are
+ * about who can mint one and what leaves the tool: a plain agent gets
+ * nothing, a destructive call waits for the person, the link comes back as
+ * the URL the person will hand out and never as a bare token, and a dead
+ * link shows no token at all.
+ */
+const TOKEN = 'sl_mCV1jC5G3nre2dz7hEx7Y8PnbwfyZTVaTKJ8L2SAaDU';
+const APP_URL = 'https://ranch.example';
+
+const active = (overrides: Partial<IShareLinkState> = {}): IShareLinkState => ({
+  active: true,
+  token: TOKEN,
+  createdAt: '2026-09-17T10:00:00.000Z',
+  revokedAt: null,
+  rotatedAt: null,
+  rotationCount: 0,
+  ...overrides,
+});
+
+const revoked = (): IShareLinkState =>
+  active({ active: false, token: null, revokedAt: '2026-09-18T10:00:00.000Z' });
+
+const neverShared = (): IShareLinkState => ({
+  active: false,
+  token: null,
+  createdAt: null,
+  revokedAt: null,
+  rotatedAt: null,
+  rotationCount: 0,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: ShareLinkTool;
+  shareLinks: {
+    getState: jest.Mock;
+    share: jest.Mock;
+    regenerate: jest.Mock;
+    revoke: jest.Mock;
+  };
+  agents: { findById: jest.Mock };
+}
+
+function harness(): Harness {
+  const shareLinks = {
+    getState: jest.fn().mockResolvedValue(active()),
+    share: jest.fn().mockResolvedValue(active()),
+    regenerate: jest.fn().mockResolvedValue(
+      active({
+        token: 'sl_NEWTOKENxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+        rotatedAt: '2026-09-18T10:00:00.000Z',
+        rotationCount: 1,
+      }),
+    ),
+    revoke: jest.fn().mockResolvedValue(revoked()),
+  };
+  const agents = {
+    findById: jest
+      .fn()
+      .mockResolvedValue({ id: 'agent-a', name: 'Support Bot' }),
+  };
+  const tool = new ShareLinkTool(
+    shareLinks as unknown as ShareLinkService,
+    agents as unknown as IAgentGateway,
+  );
+  return { tool, shareLinks, agents };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+const ENV_KEYS = ['PUBLIC_APP_URL', 'ADMIN_URL', 'ADMIN_BASE_URL'] as const;
+const savedEnv: Partial<Record<(typeof ENV_KEYS)[number], string | undefined>> =
+  {};
+
+beforeEach(() => {
+  for (const key of ENV_KEYS) {
+    savedEnv[key] = process.env[key];
+    delete process.env[key];
+  }
+  process.env.PUBLIC_APP_URL = APP_URL;
+});
+
+afterEach(() => {
+  for (const key of ENV_KEYS) {
+    if (savedEnv[key] === undefined) delete process.env[key];
+    else process.env[key] = savedEnv[key];
+  }
+});
+
+describe('ShareLinkTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a plain agent even by name, before touching the service', async () => {
+    const { tool, shareLinks } = harness();
+    await expect(
+      tool.createShareLink({ agentId: 'agent-a' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(
+      tool.getShareLink({ agentId: 'agent-a' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(shareLinks.share).not.toHaveBeenCalled();
+    expect(shareLinks.getState).not.toHaveBeenCalled();
+  });
+
+  it('refuses to record a write with no token subject, as the controller does', async () => {
+    const { tool, shareLinks } = harness();
+    const noSub = {
+      user: { email: '', roles: [UserRoleTypes.Owner] },
+    } as unknown as Request;
+    await expect(
+      tool.createShareLink({ agentId: 'agent-a' }, null, noSub),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(shareLinks.share).not.toHaveBeenCalled();
+  });
+});
+
+describe('ShareLinkTool — reading', () => {
+  it('returns the link as the URL a visitor opens, never as a bare token', async () => {
+    const { tool, shareLinks } = harness();
+    const text = textOf(
+      await tool.getShareLink({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(shareLinks.getState).toHaveBeenCalledWith('agent-a');
+    expect(text).toContain('"active": true');
+    expect(text).toContain(`"shareUrl": "${APP_URL}/share?token=${TOKEN}"`);
+    expect(text).toContain('Support Bot');
+    expect(text).not.toContain('"token"');
+  });
+
+  it('shows a never-shared agent as inactive with no link', async () => {
+    const { tool, shareLinks } = harness();
+    shareLinks.getState.mockResolvedValue(neverShared());
+    const text = textOf(
+      await tool.getShareLink({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('"active": false');
+    expect(text).toContain('"shareUrl": null');
+    expect(text).not.toContain('sl_');
+  });
+
+  it('hands back the path with a note when no app origin is known', async () => {
+    delete process.env.PUBLIC_APP_URL;
+    const { tool } = harness();
+    const text = textOf(
+      await tool.getShareLink({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('"shareUrl": null');
+    expect(text).toContain(`"sharePath": "/share?token=${TOKEN}"`);
+    expect(text).toContain('PUBLIC_APP_URL');
+  });
+
+  it('names the next move when the agent does not exist', async () => {
+    const { tool, shareLinks, agents } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getShareLink({ agentId: 'agent-x' }, null, operator()),
+    );
+    expect(text).toContain('Agent agent-x not found');
+    expect(text).toContain('list_agents');
+    expect(shareLinks.getState).not.toHaveBeenCalled();
+  });
+
+  it('turns a 404 from the service into the same not-found answer', async () => {
+    const { tool, shareLinks } = harness();
+    shareLinks.getState.mockRejectedValue(
+      new NotFoundException('Agent not found'),
+    );
+    const text = textOf(
+      await tool.getShareLink({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_agents');
+  });
+});
+
+describe('ShareLinkTool — creating', () => {
+  it('shares as the calling subject and returns the URL', async () => {
+    const { tool, shareLinks } = harness();
+    const text = textOf(
+      await tool.createShareLink({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(shareLinks.share).toHaveBeenCalledWith('agent-a', 'agent:agent-ops');
+    expect(text).toContain(`${APP_URL}/share?token=${TOKEN}`);
+    expect(text).not.toContain('"token"');
+  });
+
+  it('does not share an agent that does not exist', async () => {
+    const { tool, shareLinks, agents } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.createShareLink({ agentId: 'agent-x' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(shareLinks.share).not.toHaveBeenCalled();
+  });
+});
+
+describe('ShareLinkTool — regenerating', () => {
+  it('refuses without the confirmation argument and mints nothing', async () => {
+    const { tool, shareLinks } = harness();
+    const result = await tool.regenerateShareLink(
+      { agentId: 'agent-a' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(textOf(result)).toContain('«Support Bot»');
+    expect(shareLinks.regenerate).not.toHaveBeenCalled();
+  });
+
+  it('reports a missing agent before asking for a confirmation', async () => {
+    const { tool, shareLinks, agents } = harness();
+    agents.findById.mockResolvedValue(null);
+    const result = await tool.regenerateShareLink(
+      { agentId: 'agent-x' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(shareLinks.regenerate).not.toHaveBeenCalled();
+  });
+
+  it('rotates once confirmed and returns only the new link', async () => {
+    const { tool, shareLinks } = harness();
+    const text = textOf(
+      await tool.regenerateShareLink(
+        { agentId: 'agent-a', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(shareLinks.regenerate).toHaveBeenCalledWith(
+      'agent-a',
+      'agent:agent-ops',
+    );
+    expect(text).toContain('sl_NEWTOKEN');
+    expect(text).not.toContain(TOKEN);
+    expect(text).toContain('"rotationCount": 1');
+    expect(text).toContain('previous link no longer works');
+  });
+});
+
+describe('ShareLinkTool — revoking', () => {
+  it('refuses without the confirmation argument and revokes nothing', async () => {
+    const { tool, shareLinks } = harness();
+    const result = await tool.revokeShareLink(
+      { agentId: 'agent-a' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(shareLinks.revoke).not.toHaveBeenCalled();
+  });
+
+  it('revokes once confirmed and shows no token afterwards', async () => {
+    const { tool, shareLinks } = harness();
+    const text = textOf(
+      await tool.revokeShareLink(
+        { agentId: 'agent-a', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(shareLinks.revoke).toHaveBeenCalledWith(
+      'agent-a',
+      'agent:agent-ops',
+    );
+    expect(text).toContain('"active": false');
+    expect(text).toContain('"shareUrl": null');
+    expect(text).toContain('create_share_link');
+    expect(text).not.toContain('sl_');
+  });
+
+  it('says so when there was nothing to revoke', async () => {
+    const { tool, shareLinks } = harness();
+    shareLinks.revoke.mockResolvedValue(neverShared());
+    const text = textOf(
+      await tool.revokeShareLink(
+        { agentId: 'agent-a', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('was not shared');
+  });
+
+  it('does not revoke for an agent that does not exist', async () => {
+    const { tool, shareLinks, agents } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.revokeShareLink(
+        { agentId: 'agent-x', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(shareLinks.revoke).not.toHaveBeenCalled();
+  });
+});
+
+describe('resolveAppOrigin — the same rule the admin console uses', () => {
+  it('prefers an explicit PUBLIC_APP_URL, keeping a sub-path and dropping the slash', () => {
+    expect(
+      resolveAppOrigin({ PUBLIC_APP_URL: 'https://ranch.example/app/' }),
+    ).toBe('https://ranch.example/app');
+  });
+
+  it('ignores a PUBLIC_APP_URL that is not http(s)', () => {
+    expect(resolveAppOrigin({ PUBLIC_APP_URL: 'ftp://ranch.example' })).toBe(
+      null,
+    );
+  });
+
+  it('derives <domain> from admin.<domain>', () => {
+    expect(resolveAppOrigin({ ADMIN_URL: 'https://admin.ranch.example' })).toBe(
+      'https://ranch.example',
+    );
+  });
+
+  it('points a local admin at the app dev port', () => {
+    expect(resolveAppOrigin({ ADMIN_URL: 'http://localhost:3001' })).toBe(
+      'http://localhost:3000',
+    );
+  });
+
+  it('guesses nothing for an admin host it cannot read', () => {
+    expect(resolveAppOrigin({ ADMIN_URL: 'https://console.example' })).toBe(
+      null,
+    );
+    expect(resolveAppOrigin({ ADMIN_URL: 'https://admin.com' })).toBe(null);
+    expect(resolveAppOrigin({})).toBe(null);
+  });
+});
diff --git a/api/src/slices/agent/shareLink/shareLink.tool.ts b/api/src/slices/agent/shareLink/shareLink.tool.ts
new file mode 100644
index 00000000..56c983ee
--- /dev/null
+++ b/api/src/slices/agent/shareLink/shareLink.tool.ts
@@ -0,0 +1,342 @@
+import {
+  ForbiddenException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { ShareLinkService, type IShareLinkState } from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** The app page a share link opens (`app/pages/share.vue`). */
+const SHARE_PATH = '/share';
+
+/** Port `app` listens on under `ranch dev` (`app/package.json`). */
+const DEV_APP_PORT = 3000;
+
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+
+/** Admin is served from `admin.<domain>`, the app from `<domain>` itself
+ *  (`terraform/modules/apps/main.tf`: `admin_host` / `app_host`). */
+const ADMIN_HOST_PREFIX = 'admin.';
+
+/**
+ * Where the app console lives, as an origin with no trailing slash, or null
+ * when the API has no way to know.
+ *
+ * The API never builds share URLs for the console: the app reads its own
+ * address bar and admin derives the app's address from its own
+ * (`admin/slices/share/utils/shareUrl.ts`). A chat has no address bar, so
+ * the tool applies admin's rule from the API's side: `PUBLIC_APP_URL` when
+ * set (the API-side twin of admin's `NUXT_PUBLIC_APP_URL`), else derived from
+ * `ADMIN_URL` exactly as admin derives it — `admin.<domain>` → `<domain>`,
+ * localhost → the app's dev port. Anything else is null: a wrong guess is a
+ * link that looks fine and opens nothing, so the tool hands back the path
+ * and says so instead.
+ */
+export function resolveAppOrigin(
+  env: NodeJS.ProcessEnv = process.env,
+): string | null {
+  const explicit = toHttpBase(env.PUBLIC_APP_URL);
+  if (explicit) return explicit;
+
+  const admin = toUrl(env.ADMIN_URL ?? env.ADMIN_BASE_URL);
+  if (!admin) return null;
+  if (LOCAL_HOSTS.has(admin.hostname)) {
+    return `${admin.protocol}//${admin.hostname}:${DEV_APP_PORT}`;
+  }
+  if (admin.hostname.startsWith(ADMIN_HOST_PREFIX)) {
+    const appHost = admin.host.slice(ADMIN_HOST_PREFIX.length);
+    // `admin.com` is somebody's whole domain, not an admin subdomain of `com`.
+    if (appHost.includes('.')) return `${admin.protocol}//${appHost}`;
+  }
+  return null;
+}
+
+function toUrl(value: string | null | undefined): URL | null {
+  if (!value) return null;
+  try {
+    return new URL(value.trim());
+  } catch {
+    return null;
+  }
+}
+
+/** Accepts only http(s); keeps a sub-path if the app is served under one. */
+function toHttpBase(value: string | null | undefined): string | null {
+  const url = toUrl(value);
+  if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:')) {
+    return null;
+  }
+  return `${url.origin}${url.pathname}`.replace(/\/+$/, '');
+}
+
+/**
+ * The public share link of an agent, from the chat (CLEAN-109). Mirrors
+ * `ShareLinkController` call for call: the same `ShareLinkService`, the same
+ * actor (the caller's token subject, recorded as who created or revoked the
+ * link), the same 404 for an unknown agent.
+ *
+ * Operator-only. The controller lets any console user share an agent but
+ * keeps the `Agent` role out: a runtime must not mint or revoke public links
+ * to itself or to a colleague. An admin agent holds Owner and acts as the
+ * operator; for a plain agent these tools are not listed and not callable.
+ *
+ * The share URL is the product — the person asked for a link to hand out —
+ * so an active link comes back as the full URL. Nothing else about the token
+ * is returned: no bare `token` field, and a revoked link shows no token at
+ * all, because the service already withholds a dead one.
+ */
+@Injectable()
+export class ShareLinkTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(ShareLinkTool.name);
+
+  constructor(
+    private readonly shareLinks: ShareLinkService,
+    private readonly agents: IAgentGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'get_share_link',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Show the share link',
+    template: 'Does the agent «name» have a public share link?',
+    description:
+      'Whether an agent is publicly shared, and if so the link visitors ' +
+      'open to chat with it, plus when it was created and last regenerated. ' +
+      'Not shared or revoked: active false and no link. Takes the agent id ' +
+      '— resolve a name with list_agents first.',
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+    }),
+  })
+  async getShareLink(
+    { agentId }: { agentId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    return this.guard(agentId, async () =>
+      present(agent, await this.shareLinks.getState(agentId)),
+    );
+  }
+
+  @Tool({
+    name: 'create_share_link',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Create a share link',
+    template: 'Create a public share link for the agent «name»',
+    description:
+      'Share the agent publicly: anyone who opens the returned link can ' +
+      'chat with it, no account needed. Idempotent — an agent that is ' +
+      'already shared gets its existing link back unchanged, so this never ' +
+      'invalidates a link already in circulation (use regenerate_share_link ' +
+      'for that). Takes the agent id — resolve a name with list_agents first.',
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+    }),
+  })
+  async createShareLink(
+    { agentId }: { agentId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const userId = requireSub(httpRequest);
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    return this.guard(agentId, async () => {
+      const state = await this.shareLinks.share(agentId, userId);
+      this.logger.log(`Share link ensured through MCP: agent=${agentId}`);
+      return present(agent, state);
+    });
+  }
+
+  @Tool({
+    name: 'regenerate_share_link',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Regenerate the share link',
+    template: 'Regenerate the share link of the agent «name»',
+    destructive: true,
+    description:
+      'Replace the share link with a new one. The old link stops working ' +
+      'in the same write, so everyone holding it loses access immediately; ' +
+      'a revoked link is revived with the new address. Returns the new link. ' +
+      'Takes the agent id — resolve a name with list_agents first. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async regenerateShareLink(
+    args: { agentId: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const userId = requireSub(httpRequest);
+    const { agentId } = args;
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    const refusal = confirmed(
+      args,
+      `regenerate the share link of agent «${agent.name}» — the current ` +
+        'link stops working immediately for everyone who has it',
+    );
+    if (refusal) return refusal;
+    return this.guard(agentId, async () => {
+      const state = await this.shareLinks.regenerate(agentId, userId);
+      this.logger.log(`Share link regenerated through MCP: agent=${agentId}`);
+      return present(agent, state, 'The previous link no longer works.');
+    });
+  }
+
+  @Tool({
+    name: 'revoke_share_link',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Revoke the share link',
+    template: 'Revoke the share link of the agent «name»',
+    destructive: true,
+    description:
+      'Stop sharing the agent. Visitors are cut off on their very next ' +
+      'request; the old link is dead for good — create_share_link later ' +
+      'mints a different one. Revoking an agent that is not shared changes ' +
+      'nothing and is not an error. Takes the agent id — resolve a name with ' +
+      'list_agents first. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async revokeShareLink(
+    args: { agentId: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const userId = requireSub(httpRequest);
+    const { agentId } = args;
+    const agent = await this.agents.findById(agentId);
+    if (!agent) return notFound(agentId);
+    const refusal = confirmed(
+      args,
+      `revoke the share link of agent «${agent.name}» — visitors are cut ` +
+        'off on their next request',
+    );
+    if (refusal) return refusal;
+    return this.guard(agentId, async () => {
+      const state = await this.shareLinks.revoke(agentId, userId);
+      this.logger.log(`Share link revoked through MCP: agent=${agentId}`);
+      return present(
+        agent,
+        state,
+        state.revokedAt
+          ? 'The link is dead; create_share_link mints a new one when wanted.'
+          : 'Nothing to revoke — this agent was not shared.',
+      );
+    });
+  }
+
+  /**
+   * The agent was resolved a moment ago, but the service checks again and
+   * 404s if it vanished in between. That is a not-found for the model, not a
+   * crash.
+   */
+  private async guard(
+    agentId: string,
+    run: () => Promise<ToolResult>,
+  ): Promise<ToolResult> {
+    try {
+      return await run();
+    } catch (err) {
+      if (err instanceof NotFoundException) return notFound(agentId);
+      throw err;
+    }
+  }
+}
+
+/** Same belt-and-braces read as `ShareLinkController.requireSub`: the actor
+ *  recorded on the row must never be `undefined`. */
+function requireSub(httpRequest: AuthedRequest): string {
+  const sub = httpRequest.user?.sub;
+  if (!sub) throw new ForbiddenException('No authenticated user');
+  return sub;
+}
+
+function notFound(agentId: string): ToolResult {
+  return ok({
+    error: `Agent ${agentId} not found — call list_agents to find the id`,
+  });
+}
+
+/**
+ * The owner-facing state as the console shows it: a link when active, the
+ * dates always, the raw token never as its own field. Without a known app
+ * origin the path is handed back with a note, so the person still gets
+ * something they can complete by hand.
+ */
+function present(
+  agent: { id: string; name: string },
+  state: IShareLinkState,
+  note?: string,
+): ToolResult {
+  const base = {
+    agentId: agent.id,
+    agentName: agent.name,
+    active: state.active,
+    createdAt: state.createdAt,
+    revokedAt: state.revokedAt,
+    rotatedAt: state.rotatedAt,
+    rotationCount: state.rotationCount,
+  };
+  if (!state.active || !state.token) {
+    return ok({ ...base, shareUrl: null, note: note ?? 'Not shared.' });
+  }
+  const path = `${SHARE_PATH}?token=${encodeURIComponent(state.token)}`;
+  const origin = resolveAppOrigin();
+  if (origin) {
+    return ok({ ...base, shareUrl: `${origin}${path}`, note });
+  }
+  return ok({
+    ...base,
+    shareUrl: null,
+    sharePath: path,
+    note:
+      `${note ? `${note} ` : ''}The API does not know the app console's ` +
+      'address, so prefix this path with it (or set PUBLIC_APP_URL on the API).',
+  });
+}
diff --git a/api/src/slices/agent/template/template.module.ts b/api/src/slices/agent/template/template.module.ts
index f854ce66..07bb0b6e 100644
--- a/api/src/slices/agent/template/template.module.ts
+++ b/api/src/slices/agent/template/template.module.ts
@@ -1,12 +1,16 @@
-import { Module } from '@nestjs/common';
+import { forwardRef, Module } from '@nestjs/common';
 import { SettingModule } from '#/setting/setting.module';
+import { AgentModule } from '#/agent/agent/agent.module';
 import { TemplateController } from './template.controller';
 import { ITemplateGateway } from './domain/template.gateway';
 import { TemplateGateway } from './data/template.gateway';
 import { TemplateMapper } from './data/template.mapper';
+import { TemplateAdminTool } from './templateAdmin.tool';
 
 @Module({
-  imports: [SettingModule],
+  // AgentModule imports this module; the tool's restart-by-template needs
+  // AgentModule back, so the reference is deferred to break the cycle.
+  imports: [SettingModule, forwardRef(() => AgentModule)],
   controllers: [TemplateController],
   providers: [
     TemplateMapper,
@@ -14,6 +18,7 @@ import { TemplateMapper } from './data/template.mapper';
       provide: ITemplateGateway,
       useClass: TemplateGateway,
     },
+    TemplateAdminTool,
   ],
   exports: [ITemplateGateway],
 })
diff --git a/api/src/slices/agent/template/templateAdmin.tool.spec.ts b/api/src/slices/agent/template/templateAdmin.tool.spec.ts
new file mode 100644
index 00000000..a22c221f
--- /dev/null
+++ b/api/src/slices/agent/template/templateAdmin.tool.spec.ts
@@ -0,0 +1,313 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { TemplateAdminTool } from './templateAdmin.tool';
+import type { ITemplateData } from './domain';
+import type { ITemplateGateway } from './domain';
+import type { IAgentGateway } from '#/agent/agent/domain/agent.gateway';
+import type { AgentDeployService } from '#/agent/agent/domain/agentDeploy.service';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Two of these tools take agents down (delete a template, restart every
+ * agent on it), so the tests care most that a plain agent cannot reach them,
+ * that nothing mutates before the person confirmed, and that every refusal
+ * names what to do next.
+ */
+const templateRow = (
+  overrides: Partial<ITemplateData> = {},
+): ITemplateData => ({
+  id: 'tpl-1',
+  name: 'Support Template',
+  description: 'Answers order questions.',
+  image: 'ghcr.io/org/agent:latest',
+  defaultConfig: {},
+  defaultResources: { cpu: '500m', memory: '512Mi' },
+  paddockConfig: {},
+  defaultKnowledgeIds: [],
+  sourceUrl: null,
+  sourceType: null,
+  manifestJson: null,
+  version: null,
+  skillIds: [],
+  mcpServerIds: [],
+  createdAt: new Date('2026-09-17T10:00:00.000Z'),
+  updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  ...overrides,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: TemplateAdminTool;
+  templates: {
+    findById: jest.Mock;
+    create: jest.Mock;
+    setMcps: jest.Mock;
+    countAgents: jest.Mock;
+    delete: jest.Mock;
+  };
+  agents: { findByTemplateId: jest.Mock };
+  deploy: { restartAgent: jest.Mock };
+}
+
+function harness(): Harness {
+  const templates = {
+    findById: jest.fn().mockResolvedValue(templateRow()),
+    create: jest
+      .fn()
+      .mockImplementation(async (data) =>
+        templateRow({ id: 'tpl-new', ...data }),
+      ),
+    setMcps: jest
+      .fn()
+      .mockImplementation(async (id, mcpServerIds) =>
+        templateRow({ id, mcpServerIds }),
+      ),
+    countAgents: jest.fn().mockResolvedValue(0),
+    delete: jest.fn().mockResolvedValue(undefined),
+  };
+  const agents = {
+    findByTemplateId: jest
+      .fn()
+      .mockResolvedValue([{ id: 'agent-a' }, { id: 'agent-b' }]),
+  };
+  const deploy = { restartAgent: jest.fn().mockResolvedValue(undefined) };
+
+  const tool = new TemplateAdminTool(
+    templates as unknown as ITemplateGateway,
+    agents as unknown as IAgentGateway,
+    deploy as unknown as AgentDeployService,
+  );
+  return { tool, templates, agents, deploy };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('TemplateAdminTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, templates } = harness();
+    await expect(
+      tool.createTemplate(
+        { name: 'x', description: 'y', image: 'img' },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(templates.create).not.toHaveBeenCalled();
+  });
+
+  it('refuses a restart from a plain agent before touching any agent', async () => {
+    const { tool, deploy } = harness();
+    await expect(
+      tool.restartTemplateAgents(
+        { templateId: 'tpl-1', confirm: true },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(deploy.restartAgent).not.toHaveBeenCalled();
+  });
+});
+
+describe('create_template', () => {
+  it('creates the template with exactly the fields given', async () => {
+    const { tool, templates } = harness();
+    const args = {
+      name: 'Sales Template',
+      description: 'Handles quotes.',
+      image: 'ghcr.io/org/sales:1',
+      defaultResources: { cpu: '1', memory: '1Gi' },
+      defaultKnowledgeIds: ['kb-1'],
+    };
+    const text = textOf(await tool.createTemplate(args, null, operator()));
+    expect(templates.create).toHaveBeenCalledWith(args);
+    expect(text).toContain('"id": "tpl-new"');
+    expect(text).toContain('Sales Template');
+    expect(text).toContain('create_agent with templateId=tpl-new');
+  });
+});
+
+describe('delete_template', () => {
+  it('reports an unknown template with the way to find the id', async () => {
+    const { tool, templates } = harness();
+    templates.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.deleteTemplate(
+        { id: 'nope', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_templates');
+    expect(templates.delete).not.toHaveBeenCalled();
+  });
+
+  it('refuses without confirm, naming the template, and deletes nothing', async () => {
+    const { tool, templates } = harness();
+    const result = await tool.deleteTemplate({ id: 'tpl-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('delete the template «Support Template»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(templates.countAgents).not.toHaveBeenCalled();
+    expect(templates.delete).not.toHaveBeenCalled();
+  });
+
+  it('refuses while agents still use the template and says what to do', async () => {
+    const { tool, templates } = harness();
+    templates.countAgents.mockResolvedValue(2);
+    const result = await tool.deleteTemplate(
+      { id: 'tpl-1', confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('2 agents still using it');
+    expect(textOf(result)).toContain('list_agents');
+    expect(templates.delete).not.toHaveBeenCalled();
+  });
+
+  it('deletes a confirmed, unused template', async () => {
+    const { tool, templates } = harness();
+    const text = textOf(
+      await tool.deleteTemplate(
+        { id: 'tpl-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(templates.delete).toHaveBeenCalledWith('tpl-1');
+    expect(text).toContain('"id": "tpl-1"');
+    expect(text).toContain('deleted');
+  });
+});
+
+describe('set_template_mcps', () => {
+  it('replaces the MCP set and reminds that agents need a restart', async () => {
+    const { tool, templates } = harness();
+    const text = textOf(
+      await tool.setTemplateMcps(
+        { id: 'tpl-1', mcpServerIds: ['mcp-1', 'mcp-2'] },
+        null,
+        operator(),
+      ),
+    );
+    expect(templates.setMcps).toHaveBeenCalledWith('tpl-1', ['mcp-1', 'mcp-2']);
+    expect(text).toContain('"mcp-1"');
+    expect(text).toContain('2 MCP servers');
+    expect(text).toContain('restart_template_agents with templateId=tpl-1');
+  });
+
+  it('reports an unknown template without writing', async () => {
+    const { tool, templates } = harness();
+    templates.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.setTemplateMcps(
+        { id: 'nope', mcpServerIds: [] },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_templates');
+    expect(templates.setMcps).not.toHaveBeenCalled();
+  });
+});
+
+describe('restart_template_agents', () => {
+  it('reports an unknown template before asking for confirmation', async () => {
+    const { tool, templates, agents } = harness();
+    templates.findById.mockResolvedValue(null);
+    const result = await tool.restartTemplateAgents(
+      { templateId: 'nope' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(agents.findByTemplateId).not.toHaveBeenCalled();
+  });
+
+  it('refuses without confirm and restarts nothing', async () => {
+    const { tool, agents, deploy } = harness();
+    const result = await tool.restartTemplateAgents(
+      { templateId: 'tpl-1' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain(
+      'restart every agent of the template «Support Template»',
+    );
+    expect(agents.findByTemplateId).not.toHaveBeenCalled();
+    expect(deploy.restartAgent).not.toHaveBeenCalled();
+  });
+
+  it('restarts every agent of the template and reports the counts', async () => {
+    const { tool, agents, deploy } = harness();
+    const text = textOf(
+      await tool.restartTemplateAgents(
+        { templateId: 'tpl-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(agents.findByTemplateId).toHaveBeenCalledWith('tpl-1');
+    expect(deploy.restartAgent).toHaveBeenCalledTimes(2);
+    expect(deploy.restartAgent).toHaveBeenCalledWith('agent-a');
+    expect(deploy.restartAgent).toHaveBeenCalledWith('agent-b');
+    expect(text).toContain('"restarted": 2');
+    expect(text).toContain('"failed": 0');
+    expect(text).toContain('"total": 2');
+  });
+
+  it('counts a failed restart without stopping the others', async () => {
+    const { tool, deploy } = harness();
+    deploy.restartAgent.mockImplementation(async (id: string) => {
+      if (id === 'agent-a') throw new Error('argo down');
+    });
+    const text = textOf(
+      await tool.restartTemplateAgents(
+        { templateId: 'tpl-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(deploy.restartAgent).toHaveBeenCalledTimes(2);
+    expect(text).toContain('"restarted": 1');
+    expect(text).toContain('"failed": 1');
+    expect(text).toContain('restart_agent');
+  });
+
+  it('says so when no agent uses the template', async () => {
+    const { tool, agents, deploy } = harness();
+    agents.findByTemplateId.mockResolvedValue([]);
+    const text = textOf(
+      await tool.restartTemplateAgents(
+        { templateId: 'tpl-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(deploy.restartAgent).not.toHaveBeenCalled();
+    expect(text).toContain('"total": 0');
+    expect(text).toContain('nothing to restart');
+  });
+});
diff --git a/api/src/slices/agent/template/templateAdmin.tool.ts b/api/src/slices/agent/template/templateAdmin.tool.ts
new file mode 100644
index 00000000..678d43fb
--- /dev/null
+++ b/api/src/slices/agent/template/templateAdmin.tool.ts
@@ -0,0 +1,283 @@
+import { forwardRef, Inject, Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import type { IAuthTokenPayload } from '#/user/auth/domain';
+import { IAgentGateway } from '#/agent/agent/domain/agent.gateway';
+import { AgentDeployService } from '#/agent/agent/domain/agentDeploy.service';
+import { ITemplateGateway } from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/**
+ * How many agents restart at once in `restart_template_agents`. The same cap
+ * as `AgentController.restartByTemplate` — one template can own dozens of
+ * agents, and redeploying them all in one burst would swamp the cluster.
+ */
+const RESTART_CONCURRENCY = 5;
+
+const NOT_FOUND = (id: string) =>
+  ok({
+    error: `Template ${id} not found — call list_templates to find the id`,
+  });
+
+/**
+ * The template capabilities the console has and `rancher.tool.ts` lacks
+ * (CLEAN-109): create, delete, attach MCP servers, restart every agent of a
+ * template. Listing, reading, updating, skills and template files stay in
+ * `rancher.tool.ts` — this class only fills the gap.
+ *
+ * Every call goes through the gateways `TemplateController` and
+ * `AgentController` use, and keeps their rules: a template still used by
+ * agents cannot be deleted, and a restart-by-template redeploys with the
+ * same concurrency cap and reports the same counts.
+ *
+ * Operator only. A plain agent does not see these tools and cannot call them
+ * by name either (`requireOperator` on every method).
+ */
+@Injectable()
+export class TemplateAdminTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(TemplateAdminTool.name);
+
+  constructor(
+    private templates: ITemplateGateway,
+    // AgentModule imports TemplateModule, so the way back is a cycle —
+    // forwardRef on both the module import and these two injections.
+    @Inject(forwardRef(() => IAgentGateway))
+    private agents: IAgentGateway,
+    @Inject(forwardRef(() => AgentDeployService))
+    private agentDeploy: AgentDeployService,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return callerIsOperator(httpRequest);
+  }
+
+  @Tool({
+    name: 'create_template',
+    topic: ToolTopics.Templates,
+    title: 'Create a template',
+    template:
+      'Create a template «name» with image «image» described as «description»',
+    description:
+      'Create an agent template: the container image and defaults that ' +
+      'agents are spawned from. Returns the new template with its id. ' +
+      'Attach skills with set_template_skills and MCP servers with ' +
+      'set_template_mcps, then create_agent from it.',
+    parameters: z.object({
+      name: z.string(),
+      description: z.string(),
+      image: z
+        .string()
+        .describe('Container image, e.g. ghcr.io/org/agent:latest'),
+      defaultConfig: z.record(z.unknown()).optional(),
+      defaultResources: z
+        .object({ cpu: z.string(), memory: z.string() })
+        .optional(),
+      paddockConfig: z.record(z.unknown()).optional(),
+      defaultKnowledgeIds: z
+        .array(z.string())
+        .optional()
+        .describe('Knowledge base ids new agents get by default'),
+    }),
+  })
+  async createTemplate(
+    args: {
+      name: string;
+      description: string;
+      image: string;
+      defaultConfig?: Record<string, unknown>;
+      defaultResources?: { cpu: string; memory: string };
+      paddockConfig?: Record<string, unknown>;
+      defaultKnowledgeIds?: string[];
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const template = await this.templates.create(args);
+    this.logger.log(`Template created through MCP: ${template.id}`);
+    return ok({
+      ok: true,
+      template,
+      message:
+        `Template «${template.name}» created. Attach skills with ` +
+        'set_template_skills, MCP servers with set_template_mcps, then ' +
+        `create_agent with templateId=${template.id}.`,
+    });
+  }
+
+  @Tool({
+    name: 'delete_template',
+    topic: ToolTopics.Templates,
+    title: 'Delete a template',
+    template: 'Delete the template «name»',
+    destructive: true,
+    description:
+      'Delete a template. Refused while agents still use it — delete or ' +
+      'move those agents first (list_agents shows which template each one ' +
+      'uses). Resolve the id with list_templates. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteTemplate(
+    args: { id: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const template = await this.templates.findById(args.id);
+    if (!template) return NOT_FOUND(args.id);
+    const refusal = confirmed(args, `delete the template «${template.name}»`);
+    if (refusal) return refusal;
+    // Same rule as the console: a template with agents on it stays.
+    const agentCount = await this.templates.countAgents(args.id);
+    if (agentCount > 0) {
+      return err(
+        `Cannot delete template «${template.name}» — ${agentCount} agent` +
+          `${agentCount === 1 ? '' : 's'} still using it. Delete those ` +
+          'agents (delete_agent) or move them to another template first; ' +
+          'list_agents shows which ones they are.',
+      );
+    }
+    await this.templates.delete(args.id);
+    this.logger.log(`Template deleted through MCP: ${args.id}`);
+    return ok({ id: args.id, message: `Template «${template.name}» deleted.` });
+  }
+
+  @Tool({
+    name: 'set_template_mcps',
+    topic: ToolTopics.Templates,
+    title: 'Attach MCP servers to a template',
+    template: 'Attach the MCP servers «server list» to the template «name»',
+    description:
+      'Replace the full set of MCP servers attached to a template. The list ' +
+      'is exhaustive — omitted ids are detached (get_template shows the ' +
+      'current mcpServerIds, list_mcp_servers the available servers). Agents ' +
+      'read the set at deploy time, so existing agents of the template see ' +
+      'the change only after restart_template_agents.',
+    parameters: z.object({
+      id: z.string(),
+      mcpServerIds: z
+        .array(z.string())
+        .describe(
+          'FULL desired list of MCP server ids (replaces, not appends)',
+        ),
+    }),
+  })
+  async setTemplateMcps(
+    { id, mcpServerIds }: { id: string; mcpServerIds: string[] },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const template = await this.templates.findById(id);
+    if (!template) return NOT_FOUND(id);
+    const updated = await this.templates.setMcps(id, mcpServerIds);
+    return ok({
+      template: updated,
+      message:
+        `Template «${updated.name}» now has ${mcpServerIds.length} MCP ` +
+        `server${mcpServerIds.length === 1 ? '' : 's'}. Agents inherit the ` +
+        'set when they deploy, so running agents of this template keep the ' +
+        `old one until restart_template_agents with templateId=${id}.`,
+    });
+  }
+
+  @Tool({
+    name: 'restart_template_agents',
+    topic: ToolTopics.Templates,
+    title: 'Restart every agent of a template',
+    template: 'Restart all agents of the template «name»',
+    destructive: true,
+    description:
+      'Restart every agent that uses a template: each one pulls the latest ' +
+      'template-owned files and redeploys, keeping its runtime state. At ' +
+      'most 5 restart at once. Returns how many restarted, failed and were ' +
+      'found in total. Interrupts running conversations on those agents. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      templateId: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async restartTemplateAgents(
+    args: { templateId: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { templateId } = args;
+    const template = await this.templates.findById(templateId);
+    if (!template) return NOT_FOUND(templateId);
+    const refusal = confirmed(
+      args,
+      `restart every agent of the template «${template.name}»`,
+    );
+    if (refusal) return refusal;
+
+    const agents = await this.agents.findByTemplateId(templateId);
+    if (agents.length === 0) {
+      return ok({
+        restarted: 0,
+        failed: 0,
+        total: 0,
+        message: `No agents use template «${template.name}» — nothing to restart.`,
+      });
+    }
+
+    // Mirrors AgentController.restartByTemplate: a small worker pool over the
+    // agent list, one failure never stops the others.
+    let index = 0;
+    let restarted = 0;
+    let failed = 0;
+    const worker = async (): Promise<void> => {
+      while (index < agents.length) {
+        const agent = agents[index++];
+        try {
+          await this.agentDeploy.restartAgent(agent.id);
+          restarted += 1;
+        } catch (e) {
+          failed += 1;
+          this.logger.warn(
+            `Restart-by-template ${templateId}: agent ${agent.id} failed — ${(e as Error).message}`,
+          );
+        }
+      }
+    };
+    const workers = Math.min(RESTART_CONCURRENCY, agents.length);
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+
+    this.logger.log(
+      `Restart-by-template ${templateId} through MCP: ${restarted} restarted, ${failed} failed of ${agents.length} total`,
+    );
+    return ok({
+      restarted,
+      failed,
+      total: agents.length,
+      message:
+        `${restarted} of ${agents.length} agent${agents.length === 1 ? '' : 's'} ` +
+        `of template «${template.name}» restarting` +
+        (failed > 0
+          ? `; ${failed} failed — get_agent_status on each to see why, then restart_agent one by one.`
+          : '. They will boot shortly; get_agent_status to follow.'),
+    });
+  }
+}
diff --git a/api/src/slices/agent/templateInstall/templateInstall.module.ts b/api/src/slices/agent/templateInstall/templateInstall.module.ts
index 41e6e5f6..3abc1297 100644
--- a/api/src/slices/agent/templateInstall/templateInstall.module.ts
+++ b/api/src/slices/agent/templateInstall/templateInstall.module.ts
@@ -6,6 +6,7 @@ import { SkillModule } from '#/skill/skill.module';
 import { PaddockScenarioModule } from '#/paddock/scenario/scenario.module';
 import { TemplateInstallController } from './templateInstall.controller';
 import { TemplateExportController } from './templateExport.controller';
+import { TemplateInstallTool } from './templateInstall.tool';
 import { TemplateInstallService } from './domain/templateInstall.service';
 import { TemplateExportService } from './domain/templateExport.service';
 import { IManifestGateway } from './domain/manifest.gateway';
@@ -27,6 +28,7 @@ import { GitGateway } from './data/git.gateway';
   providers: [
     TemplateInstallService,
     TemplateExportService,
+    TemplateInstallTool,
     { provide: IManifestGateway, useClass: ManifestGateway },
     { provide: IArchiveGateway, useClass: ArchiveGateway },
     { provide: IGitGateway, useClass: GitGateway },
diff --git a/api/src/slices/agent/templateInstall/templateInstall.tool.spec.ts b/api/src/slices/agent/templateInstall/templateInstall.tool.spec.ts
new file mode 100644
index 00000000..4358cafa
--- /dev/null
+++ b/api/src/slices/agent/templateInstall/templateInstall.tool.spec.ts
@@ -0,0 +1,276 @@
+import { BadRequestException, ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { TemplateInstallTool } from './templateInstall.tool';
+import type { TemplateInstallService } from './domain/templateInstall.service';
+import type { ITemplateGateway, ITemplateData } from '#/agent/template/domain';
+import type { IInstallPreview, IInstallResult } from './domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Installing a template writes to the database and S3 on the strength of a
+ * URL, so the two things that matter most here are that a plain agent can
+ * neither see nor call these tools, and that a secret handed to an install
+ * never comes back out through the result — not from the install, and not
+ * from a manifest that spelled a credential out instead of `$secret:NAME`.
+ */
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+const GIT_URL = 'https://github.com/CleanSlice/agent-templates.git';
+const SECRET = 'sk-live-do-not-leak-me';
+
+const preview = (): IInstallPreview =>
+  ({
+    manifest: {
+      apiVersion: 'ranch/v1',
+      kind: 'AgentTemplate',
+      metadata: { id: 'support-bot', name: 'Support Bot', version: '1.2.0' },
+      mcp: [{ id: 'mcp-ranch', authValue: SECRET }],
+      secrets: [{ name: 'MCP_RANCH_AUTH', required: true }],
+    },
+    willCreate: true,
+    willUpgrade: false,
+    declared: {
+      skills: [{ id: 'returns', resolved: true }],
+      mcp: [{ id: 'mcp-ranch', resolved: false }],
+      secrets: [{ name: 'MCP_RANCH_AUTH', required: true }],
+    },
+    files: { agentFiles: 4, scenarioFiles: 2 },
+    warnings: ['mcp "mcp-ranch" is not registered on this Ranch'],
+  }) as unknown as IInstallPreview;
+
+const installed = (): IInstallResult => ({
+  templateId: 'support-bot',
+  templateName: 'Support Bot',
+  filesUploaded: 4,
+  scenariosSeeded: 2,
+  mcpAttached: ['mcp-ranch'],
+  skillsAttached: ['returns'],
+  unresolvedMcp: [],
+  unresolvedSkills: [],
+  warnings: [],
+});
+
+const template = (): ITemplateData =>
+  ({
+    id: 'support-bot',
+    name: 'Support Bot',
+    version: '1.2.0',
+    skillIds: [],
+    mcpServerIds: [],
+  }) as unknown as ITemplateData;
+
+interface Harness {
+  tool: TemplateInstallTool;
+  installs: { previewFromGit: jest.Mock; installFromGit: jest.Mock };
+  templates: { findById: jest.Mock };
+}
+
+function harness(): Harness {
+  const installs = {
+    previewFromGit: jest.fn().mockResolvedValue(preview()),
+    installFromGit: jest.fn().mockResolvedValue(installed()),
+  };
+  const templates = { findById: jest.fn().mockResolvedValue(template()) };
+  const tool = new TemplateInstallTool(
+    installs as unknown as TemplateInstallService,
+    templates as unknown as ITemplateGateway,
+  );
+  return { tool, installs, templates };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('TemplateInstallTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses an install from a plain agent even by name', async () => {
+    const { tool, installs } = harness();
+    await expect(
+      tool.installTemplateFromGit({ gitUrl: GIT_URL }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(installs.installFromGit).not.toHaveBeenCalled();
+  });
+
+  it('refuses a preview and an export from a plain agent too', async () => {
+    const { tool, installs, templates } = harness();
+    await expect(
+      tool.previewTemplateInstallFromGit(
+        { gitUrl: GIT_URL },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(
+      tool.exportTemplate({ templateId: 'support-bot' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(installs.previewFromGit).not.toHaveBeenCalled();
+    expect(templates.findById).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool } = harness();
+    await expect(
+      tool.exportTemplate({ templateId: 'support-bot' }, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('TemplateInstallTool — preview_template_install_from_git', () => {
+  it('passes url, ref and params to the service and returns what the controller would', async () => {
+    const { tool, installs } = harness();
+    const text = textOf(
+      await tool.previewTemplateInstallFromGit(
+        { gitUrl: GIT_URL, gitRef: 'v1.2.0', params: { language: 'ru' } },
+        null,
+        operator(),
+      ),
+    );
+    expect(installs.previewFromGit).toHaveBeenCalledWith(GIT_URL, 'v1.2.0', {
+      language: 'ru',
+    });
+    expect(text).toContain('"willCreate": true');
+    expect(text).toContain('"agentFiles": 4');
+    expect(text).toContain('MCP_RANCH_AUTH');
+    expect(text).toContain('not registered on this Ranch');
+  });
+
+  it('defaults ref to the remote default branch and params to none', async () => {
+    const { tool, installs } = harness();
+    await tool.previewTemplateInstallFromGit(
+      { gitUrl: GIT_URL },
+      null,
+      operator(),
+    );
+    expect(installs.previewFromGit).toHaveBeenCalledWith(
+      GIT_URL,
+      undefined,
+      {},
+    );
+  });
+
+  it('keeps declared secret names but never a credential spelled out in the manifest', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.previewTemplateInstallFromGit(
+        { gitUrl: GIT_URL },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).not.toContain(SECRET);
+    expect(text).not.toContain('authValue');
+    expect(text).toContain('"name": "MCP_RANCH_AUTH"');
+  });
+
+  it('lets the service refuse a bad URL, as the console would see it', async () => {
+    const { tool, installs } = harness();
+    installs.previewFromGit.mockRejectedValue(
+      new BadRequestException('gitUrl contains forbidden characters'),
+    );
+    await expect(
+      tool.previewTemplateInstallFromGit(
+        { gitUrl: 'https://x.test/a;rm -rf' },
+        null,
+        operator(),
+      ),
+    ).rejects.toBeInstanceOf(BadRequestException);
+  });
+});
+
+describe('TemplateInstallTool — install_template_from_git', () => {
+  it('installs with params and secrets and reports what was attached', async () => {
+    const { tool, installs } = harness();
+    const text = textOf(
+      await tool.installTemplateFromGit(
+        {
+          gitUrl: GIT_URL,
+          gitRef: 'main',
+          params: { language: 'ru' },
+          secrets: { MCP_RANCH_AUTH: SECRET },
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(installs.installFromGit).toHaveBeenCalledWith(
+      GIT_URL,
+      'main',
+      { language: 'ru' },
+      { MCP_RANCH_AUTH: SECRET },
+    );
+    expect(text).toContain('"templateId": "support-bot"');
+    expect(text).toContain('"filesUploaded": 4');
+    expect(text).toContain('mcp-ranch');
+  });
+
+  it('never echoes a supplied secret', async () => {
+    const { tool, installs } = harness();
+    // Even if a future result grew a field carrying it back.
+    installs.installFromGit.mockResolvedValue({
+      ...installed(),
+      authValue: SECRET,
+    });
+    const text = textOf(
+      await tool.installTemplateFromGit(
+        { gitUrl: GIT_URL, secrets: { MCP_RANCH_AUTH: SECRET } },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).not.toContain(SECRET);
+  });
+
+  it('defaults params and secrets to empty objects like the controller', async () => {
+    const { tool, installs } = harness();
+    await tool.installTemplateFromGit({ gitUrl: GIT_URL }, null, operator());
+    expect(installs.installFromGit).toHaveBeenCalledWith(
+      GIT_URL,
+      undefined,
+      {},
+      {},
+    );
+  });
+});
+
+describe('TemplateInstallTool — export_template', () => {
+  it('returns the console download path for a template that exists', async () => {
+    const { tool, templates } = harness();
+    const text = textOf(
+      await tool.exportTemplate(
+        { templateId: 'support-bot' },
+        null,
+        operator(),
+      ),
+    );
+    expect(templates.findById).toHaveBeenCalledWith('support-bot');
+    expect(text).toContain('"downloadPath": "/templates/support-bot/download"');
+    expect(text).toContain('"name": "Support Bot"');
+    expect(text).toContain('needs your login');
+  });
+
+  it('names the next move when the template does not exist', async () => {
+    const { tool, templates } = harness();
+    templates.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.exportTemplate({ templateId: 'nope' }, null, operator()),
+    );
+    expect(text).toContain('Template nope not found');
+    expect(text).toContain('list_templates');
+    expect(text).not.toContain('downloadPath');
+  });
+});
diff --git a/api/src/slices/agent/templateInstall/templateInstall.tool.ts b/api/src/slices/agent/templateInstall/templateInstall.tool.ts
new file mode 100644
index 00000000..a5f42241
--- /dev/null
+++ b/api/src/slices/agent/templateInstall/templateInstall.tool.ts
@@ -0,0 +1,210 @@
+import { Injectable } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  ok,
+  requireOperator,
+  stripSecrets,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { ITemplateGateway } from '#/agent/template/domain';
+import { TemplateInstallService } from './domain/templateInstall.service';
+import { IInstallParamValues, IInstallSecretValues } from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** The body of `POST templates/install/from-git` and its preview, as zod. */
+const gitInstallParameters = z.object({
+  gitUrl: z
+    .string()
+    .min(1)
+    .max(1000)
+    .describe(
+      'Git URL of the template repository — https://, http://, git@host:... ' +
+        'or ssh://host/.../repo.git',
+    ),
+  gitRef: z
+    .string()
+    .max(100)
+    .optional()
+    .describe('Branch, tag or short SHA. Omit for the remote default branch.'),
+  params: z
+    .record(z.union([z.string(), z.number(), z.boolean()]))
+    .optional()
+    .describe(
+      'Operator-supplied params the manifest declares, e.g. {"language":"ru"}. ' +
+        'Validated against the manifest.',
+    ),
+});
+
+/**
+ * Installing and exporting templates from the chat (CLEAN-109), the way the
+ * console's Install page and download button do it.
+ *
+ * Every install goes through `TemplateInstallService`, the same service the
+ * controller calls: URL vetting, the clone timeout, manifest validation and
+ * secret resolution live there, and nothing of it is re-implemented here.
+ *
+ * Two console capabilities stay out on purpose. A zip on a person's machine
+ * cannot travel through a tool call, so zip install remains console-only; a
+ * git URL covers the same source without a browser. And a tool cannot hand
+ * back bytes, so `export_template` does the existence check
+ * `TemplateExportService.exportZip` starts with and returns the download
+ * path the console serves rather than the archive itself.
+ *
+ * Operator-only: installing a template writes to the database and S3, and a
+ * plain agent must never be able to bring a new agent template into the
+ * Ranch, least of all one a prompt injection pointed it at.
+ */
+@Injectable()
+export class TemplateInstallTool implements IConditionallyListedTool {
+  constructor(
+    private readonly installs: TemplateInstallService,
+    private readonly templates: ITemplateGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'preview_template_install_from_git',
+    topic: ToolTopics.Templates,
+    title: 'Preview a git template',
+    template:
+      'What would installing the template from «git url» at «ref» bring?',
+    description:
+      'Clone a template repository and report what installing it would do, ' +
+      'without writing anything: the parsed manifest, whether it would ' +
+      'create a new template or upgrade an existing one (and which), the ' +
+      'skills and MCP servers it declares and whether each resolves on this ' +
+      'Ranch, the secrets it needs, file counts and warnings. Call this ' +
+      'before install_template_from_git and show the person the outcome; ' +
+      'unresolved skills or MCP servers and required secrets are what they ' +
+      'need to decide on.',
+    parameters: gitInstallParameters,
+  })
+  async previewTemplateInstallFromGit(
+    args: {
+      gitUrl: string;
+      gitRef?: string;
+      params?: IInstallParamValues;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const result = await this.installs.previewFromGit(
+      args.gitUrl,
+      args.gitRef,
+      args.params ?? {},
+    );
+    // Same shape the controller returns. A manifest may carry a literal
+    // credential where the author should have written `$secret:NAME`;
+    // the declared secret names survive, the values do not (FR-004).
+    return ok(
+      stripSecrets({
+        manifest: result.manifest as unknown as Record<string, unknown>,
+        willCreate: result.willCreate,
+        willUpgrade: result.willUpgrade,
+        existingTemplateId: result.existingTemplateId,
+        declared: result.declared,
+        files: result.files,
+        warnings: result.warnings,
+      }),
+    );
+  }
+
+  @Tool({
+    name: 'install_template_from_git',
+    topic: ToolTopics.Templates,
+    title: 'Install a template from git',
+    template: 'Install the template from «git url» at «ref»',
+    description:
+      'Clone a template repository and install it on this Ranch: creates ' +
+      'the template or upgrades the one with the same manifest id, uploads ' +
+      'its files, seeds its Paddock scenarios and attaches the skills and ' +
+      'MCP servers it declares. Pass the params and secrets the preview ' +
+      'listed; secrets are used once to resolve $secret:NAME references and ' +
+      'never echoed. Returns the template id and name plus what was ' +
+      'attached, what stayed unresolved and any warnings — the template is ' +
+      'ready for create_agent afterwards. Run ' +
+      'preview_template_install_from_git first. For a zip on your computer ' +
+      "use the console's Install page; a tool call cannot carry a file.",
+    parameters: gitInstallParameters.extend({
+      secrets: z
+        .record(z.string())
+        .optional()
+        .describe(
+          'Operator-supplied secrets by name, e.g. {"MCP_RANCH_AUTH":"..."} ' +
+            '— resolves $secret:NAME references in the manifest. Never ' +
+            'echoed back.',
+        ),
+    }),
+  })
+  async installTemplateFromGit(
+    args: {
+      gitUrl: string;
+      gitRef?: string;
+      params?: IInstallParamValues;
+      secrets?: IInstallSecretValues;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const result = await this.installs.installFromGit(
+      args.gitUrl,
+      args.gitRef,
+      args.params ?? {},
+      args.secrets ?? {},
+    );
+    // The install result names ids and counts only, never the secrets it
+    // consumed; stripping is belt and braces should that ever change.
+    return ok(stripSecrets(result));
+  }
+
+  @Tool({
+    name: 'export_template',
+    topic: ToolTopics.Templates,
+    title: 'Export a template',
+    template: 'Export the template «name»',
+    description:
+      'Export a template as an installable zip: agent.yaml, .agent/* files, ' +
+      'bundled skills, .paddock/config.json and scenarios. MCP credentials ' +
+      'are never included. A tool call cannot carry the archive, so this ' +
+      'confirms the template exists and returns the console path that ' +
+      'serves the download; give that path to the person. Takes the ' +
+      'template id — list_templates has it when you only know the name.',
+    parameters: z.object({
+      templateId: z.string().describe('Template id (list_templates has them)'),
+    }),
+  })
+  async exportTemplate(
+    args: { templateId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    // The export service looks the template up the same way before it
+    // builds the archive; checking here spares building a zip nobody
+    // receives.
+    const template = await this.templates.findById(args.templateId);
+    if (!template) {
+      return ok({
+        error: `Template ${args.templateId} not found — call list_templates to find the id`,
+      });
+    }
+    return ok({
+      templateId: template.id,
+      name: template.name,
+      version: template.version,
+      downloadPath: `/templates/${template.id}/download`,
+      note: 'Open this path in the console (it needs your login) to download the zip.',
+    });
+  }
+}
diff --git a/api/src/slices/agent/toolCatalog/data/toolListing.gateway.ts b/api/src/slices/agent/toolCatalog/data/toolListing.gateway.ts
new file mode 100644
index 00000000..7388a84f
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/data/toolListing.gateway.ts
@@ -0,0 +1,44 @@
+import { Injectable } from '@nestjs/common';
+import type { Prisma } from '@prisma/client';
+import { PrismaService } from '#/setup/prisma/prisma.service';
+import type { IToolListingRecorder } from '#/mcp/interfaces/tool-listing-recorder.interface';
+import {
+  IAgentToolListingData,
+  IToolListingGateway,
+} from '../domain/toolCatalog.types';
+
+/**
+ * One row per agent, overwritten on every tools/list the pod makes. The
+ * upsert is the whole write path: a pod that boots twice leaves one row,
+ * stamped with the later listing.
+ */
+@Injectable()
+export class ToolListingGateway
+  extends IToolListingGateway
+  implements IToolListingRecorder
+{
+  constructor(private prisma: PrismaService) {
+    super();
+  }
+
+  async record(agentId: string, toolNames: string[]): Promise<void> {
+    const names = toolNames as unknown as Prisma.InputJsonValue;
+    await this.prisma.agentToolListing.upsert({
+      where: { agentId },
+      create: { agentId, toolNames: names, listedAt: new Date() },
+      update: { toolNames: names, listedAt: new Date() },
+    });
+  }
+
+  async findByAgent(agentId: string): Promise<IAgentToolListingData | null> {
+    const row = await this.prisma.agentToolListing.findUnique({
+      where: { agentId },
+    });
+    if (!row) return null;
+    const raw = row.toolNames;
+    const toolNames = Array.isArray(raw)
+      ? raw.filter((n): n is string => typeof n === 'string')
+      : [];
+    return { agentId: row.agentId, toolNames, listedAt: row.listedAt };
+  }
+}
diff --git a/api/src/slices/agent/toolCatalog/domain/index.ts b/api/src/slices/agent/toolCatalog/domain/index.ts
new file mode 100644
index 00000000..684a863e
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/domain/index.ts
@@ -0,0 +1,2 @@
+export * from './toolCatalog.types';
+export * from './toolCatalog.service';
diff --git a/api/src/slices/agent/toolCatalog/domain/toolCatalog.service.spec.ts b/api/src/slices/agent/toolCatalog/domain/toolCatalog.service.spec.ts
new file mode 100644
index 00000000..31eef6e6
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/domain/toolCatalog.service.spec.ts
@@ -0,0 +1,180 @@
+import { NotFoundException } from '@nestjs/common';
+import { ToolCatalogService, agentPrincipal } from './toolCatalog.service';
+import type { IListedTool } from '#/mcp/services/tool-catalog.service';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * The catalogue must say exactly what the pod would see, and be honest about
+ * whether the running pod already has each tool (data-model.md §3).
+ */
+const listed = (
+  name: string,
+  topic: string,
+  extra: Partial<IListedTool['metadata']> = {},
+): IListedTool => ({
+  name,
+  description: `desc of ${name}`,
+  inputSchema: {},
+  metadata: {
+    name,
+    description: `desc of ${name}`,
+    topic: topic as never,
+    title: `Title ${name}`,
+    template: `Do «${name}»`,
+    ...extra,
+  },
+});
+
+const POD_START = '2026-09-22T10:00:00.000Z';
+
+interface Options {
+  agent?: { id: string; isAdmin: boolean } | null;
+  tools?: IListedTool[];
+  snapshot?: { toolNames: string[]; listedAt: Date } | null;
+  pod?: boolean;
+  servers?: Array<{
+    id: string;
+    name: string;
+    description: string | null;
+    updatedAt: Date;
+    url?: string;
+    authValue?: string | null;
+  }>;
+}
+
+function harness(opts: Options = {}) {
+  const agent = opts.agent === undefined ? { id: 'agent-1', isAdmin: true } : opts.agent;
+  const agents = { findById: jest.fn(async () => agent) };
+  const pods = {
+    list: jest.fn(async () =>
+      opts.pod === false ? [] : [{ agentId: 'agent-1', startedAt: POD_START }],
+    ),
+  };
+  const resolver = {
+    resolveForAgent: jest.fn(async () =>
+      (opts.servers ?? []).map((s) => ({
+        url: 'http://secret.internal',
+        authValue: 'bearer-secret',
+        ...s,
+      })),
+    ),
+  };
+  const listing = {
+    listFor: jest.fn(async () => opts.tools ?? [listed('list_agents', 'agents')]),
+  };
+  const listings = {
+    record: jest.fn(),
+    findByAgent: jest.fn(async () =>
+      opts.snapshot === undefined
+        ? { agentId: 'agent-1', toolNames: ['list_agents'], listedAt: new Date(POD_START) }
+        : opts.snapshot
+          ? { agentId: 'agent-1', ...opts.snapshot }
+          : null,
+    ),
+  };
+  const service = new ToolCatalogService(
+    agents as never,
+    pods as never,
+    resolver as never,
+    listing as never,
+    listings as never,
+  );
+  return { service, listing, agents };
+}
+
+describe('agentPrincipal', () => {
+  it('mints the shape issueAgentServiceToken signs', () => {
+    expect(agentPrincipal({ id: 'x', isAdmin: true })).toEqual({
+      sub: 'agent:x',
+      email: 'agent-x@ranch.local',
+      roles: [UserRoleTypes.Owner],
+    });
+    expect(agentPrincipal({ id: 'y', isAdmin: false }).roles).toEqual([UserRoleTypes.Agent]);
+  });
+});
+
+describe('ToolCatalogService.forAgent', () => {
+  it('404s an unknown agent', async () => {
+    const { service } = harness({ agent: null });
+    await expect(service.forAgent('nope')).rejects.toThrow(NotFoundException);
+  });
+
+  it('lists with the principal the pod would carry', async () => {
+    const { service, listing } = harness({ agent: { id: 'agent-1', isAdmin: false } });
+    await service.forAgent('agent-1');
+    const req = (listing.listFor as jest.Mock).mock.calls[0][0] as {
+      user: { sub: string; roles: string[] };
+    };
+    expect(req.user.sub).toBe('agent:agent-1');
+    expect(req.user.roles).toEqual([UserRoleTypes.Agent]);
+  });
+
+  it('groups by topic in panel order, drops empty topics, sorts tools by title', async () => {
+    const { service } = harness({
+      tools: [
+        listed('zeta', 'settings'),
+        listed('list_agents', 'agents'),
+        listed('alpha', 'settings'),
+      ],
+    });
+    const { groups } = await service.forAgent('agent-1');
+    expect(groups.map((g) => g.key)).toEqual(['agents', 'settings']);
+    expect(groups[1].tools.map((t) => t.name)).toEqual(['alpha', 'zeta']);
+    expect(groups[0]).toMatchObject({ title: 'Agents', kind: 'builtin' });
+    expect(groups[0].tools[0]).toMatchObject({
+      name: 'list_agents',
+      title: 'Title list_agents',
+      description: 'desc of list_agents',
+      template: 'Do «list_agents»',
+      destructive: false,
+    });
+  });
+
+  it('inPod: null without a pod, false for a pod that never listed, per name otherwise', async () => {
+    const tools = [listed('old', 'agents'), listed('new', 'agents')];
+
+    const noPod = await harness({ tools, pod: false }).service.forAgent('agent-1');
+    expect(noPod.podStartedAt).toBeNull();
+    expect(noPod.groups[0].tools.map((t) => t.inPod)).toEqual([null, null]);
+    expect(noPod.groups[0].afterRestart).toBe(false);
+
+    const neverListed = await harness({ tools, snapshot: null }).service.forAgent('agent-1');
+    expect(neverListed.listedAt).toBeNull();
+    expect(neverListed.groups[0].tools.map((t) => t.inPod)).toEqual([false, false]);
+    expect(neverListed.groups[0].afterRestart).toBe(true);
+
+    const partial = await harness({
+      tools,
+      snapshot: { toolNames: ['old'], listedAt: new Date(POD_START) },
+    }).service.forAgent('agent-1');
+    const byName = Object.fromEntries(partial.groups[0].tools.map((t) => [t.name, t.inPod]));
+    expect(byName).toEqual({ old: true, new: false });
+    expect(partial.groups[0].afterRestart).toBe(true);
+    expect(partial.listedAt).toBe(POD_START);
+  });
+
+  it('appends external servers as opaque groups without url or auth, with drift', async () => {
+    const { service } = harness({
+      servers: [
+        { id: 'mcp-ranch', name: 'Ranch', description: 'built-in', updatedAt: new Date('2026-09-23T00:00:00Z') },
+        { id: 'srv-1', name: 'GitHub', description: 'GitHub MCP', updatedAt: new Date('2026-09-21T00:00:00Z') },
+        { id: 'srv-2', name: 'Jira', description: null, updatedAt: new Date('2026-09-23T00:00:00Z') },
+      ],
+    });
+    const { groups } = await service.forAgent('agent-1');
+    const external = groups.filter((g) => g.kind === 'external');
+    expect(external.map((g) => g.key)).toEqual(['mcp:srv-1', 'mcp:srv-2']);
+    expect(external[0]).toMatchObject({ title: 'GitHub', description: 'GitHub MCP', afterRestart: false, tools: [] });
+    expect(external[1].afterRestart).toBe(true);
+    expect(external[1].description).toBeUndefined();
+    expect(JSON.stringify(groups)).not.toContain('secret');
+  });
+
+  it('marks destructive tools', async () => {
+    const { service } = harness({
+      tools: [listed('delete_agent', 'agents', { destructive: true })],
+    });
+    const { groups } = await service.forAgent('agent-1');
+    expect(groups[0].tools[0].destructive).toBe(true);
+  });
+});
diff --git a/api/src/slices/agent/toolCatalog/domain/toolCatalog.service.ts b/api/src/slices/agent/toolCatalog/domain/toolCatalog.service.ts
new file mode 100644
index 00000000..b2c3865f
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/domain/toolCatalog.service.ts
@@ -0,0 +1,146 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import type { Request } from 'express';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IPodGateway } from '#/agent/pod/domain';
+import { detectMcpConfigDrift } from '#/agent/agent/domain/mcpConfigDrift';
+import { AgentMcpResolver } from '#/mcpServer/domain/agentMcpResolver.service';
+import {
+  CLEANSLICE_MCP_ID,
+  DOCUMENTS_MCP_ID,
+  KNOWLEDGE_MCP_ID,
+  RANCH_MCP_ID,
+} from '#/mcpServer/domain/mcpServer.seeder';
+import { ToolCatalogService as McpToolCatalogService } from '#/mcp/services/tool-catalog.service';
+import { TOOL_TOPIC_INFO, isToolTopic, orderedTopics } from '#/mcp/decorators/topics';
+import type { IAuthTokenPayload } from '#/user/auth/domain/auth.types';
+import { UserRoleTypes } from '#/user/user/domain';
+import {
+  IAgentToolCatalog,
+  IAgentToolEntry,
+  IAgentToolGroup,
+  IToolListingGateway,
+} from './toolCatalog.types';
+
+/**
+ * The built-in servers the API hosts itself (plus the CleanSlice docs
+ * server): their tools come from this API's registry, so they are the
+ * `builtin` groups of the catalogue. Everything else on the agent's list is
+ * an external server the console shows as an opaque group.
+ */
+export const BUILT_IN_MCP_IDS: readonly string[] = [
+  RANCH_MCP_ID,
+  KNOWLEDGE_MCP_ID,
+  DOCUMENTS_MCP_ID,
+  CLEANSLICE_MCP_ID,
+];
+
+/**
+ * The principal a pod's service token carries — the same shape
+ * `issueAgentServiceToken` signs (auth.service): admin agents act as Ranch
+ * operators, plain agents hold the Agent role. Listing with it yields exactly
+ * what the pod sees.
+ */
+export function agentPrincipal(agent: {
+  id: string;
+  isAdmin: boolean;
+}): IAuthTokenPayload {
+  return {
+    sub: `agent:${agent.id}`,
+    email: `agent-${agent.id}@ranch.local`,
+    roles: agent.isAdmin ? [UserRoleTypes.Owner] : [UserRoleTypes.Agent],
+  };
+}
+
+@Injectable()
+export class ToolCatalogService {
+  constructor(
+    private readonly agents: IAgentGateway,
+    private readonly pods: IPodGateway,
+    private readonly mcpResolver: AgentMcpResolver,
+    private readonly listing: McpToolCatalogService,
+    private readonly listings: IToolListingGateway,
+  ) {}
+
+  async forAgent(agentId: string): Promise<IAgentToolCatalog> {
+    const agent = await this.agents.findById(agentId);
+    if (!agent) throw new NotFoundException('Agent not found');
+
+    const [tools, snapshot, pods, servers] = await Promise.all([
+      this.listing.listFor({
+        user: agentPrincipal(agent),
+      } as unknown as Request),
+      this.listings.findByAgent(agentId),
+      this.pods.list(),
+      this.mcpResolver.resolveForAgent(agent),
+    ]);
+
+    const pod = pods.find((p) => p.agentId === agentId) ?? null;
+    const podStartedAt = pod?.startedAt ?? null;
+    const known = snapshot ? new Set(snapshot.toolNames) : null;
+
+    const inPodOf = (name: string): boolean | null => {
+      // No pod: nothing to restart, so no marker (data-model.md §3).
+      if (!podStartedAt) return null;
+      // A pod that never listed predates this feature — it needs a restart
+      // to receive anything new, so every tool reads as absent.
+      if (!known) return false;
+      return known.has(name);
+    };
+
+    const byTopic = new Map<string, IAgentToolEntry[]>();
+    for (const tool of tools) {
+      const topic = isToolTopic(tool.metadata.topic)
+        ? tool.metadata.topic
+        : 'platform';
+      const entries = byTopic.get(topic) ?? [];
+      entries.push({
+        name: tool.name,
+        title: tool.metadata.title,
+        description: tool.description,
+        template: tool.metadata.template,
+        destructive: tool.metadata.destructive === true,
+        inPod: inPodOf(tool.name),
+      });
+      byTopic.set(topic, entries);
+    }
+
+    const groups: IAgentToolGroup[] = [];
+    for (const topic of orderedTopics()) {
+      const entries = byTopic.get(topic.key);
+      if (!entries?.length) continue;
+      entries.sort((a, b) => a.title.localeCompare(b.title));
+      groups.push({
+        key: topic.key,
+        title: TOOL_TOPIC_INFO[topic.key].title,
+        kind: 'builtin',
+        afterRestart: entries.some((e) => e.inPod === false),
+        tools: entries,
+      });
+    }
+
+    const external = servers.filter((s) => !BUILT_IN_MCP_IDS.includes(s.id));
+    for (const server of external) {
+      const drift = detectMcpConfigDrift({
+        servers: [
+          { id: server.id, name: server.name, updatedAt: server.updatedAt },
+        ],
+        podStartedAt: podStartedAt ? new Date(podStartedAt) : null,
+      });
+      groups.push({
+        key: `mcp:${server.id}`,
+        title: server.name,
+        kind: 'external',
+        ...(server.description ? { description: server.description } : {}),
+        afterRestart: drift.restartRequired,
+        tools: [],
+      });
+    }
+
+    return {
+      agentId,
+      podStartedAt,
+      listedAt: snapshot ? snapshot.listedAt.toISOString() : null,
+      groups,
+    };
+  }
+}
diff --git a/api/src/slices/agent/toolCatalog/domain/toolCatalog.types.ts b/api/src/slices/agent/toolCatalog/domain/toolCatalog.types.ts
new file mode 100644
index 00000000..5f76d5da
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/domain/toolCatalog.types.ts
@@ -0,0 +1,56 @@
+/**
+ * The Tools panel's data (CLEAN-109): what this agent's runtime would receive
+ * from the built-in Ranch MCP server, grouped by topic, plus its external MCP
+ * servers as opaque groups. See specs/016-agent-tool-parity/data-model.md §3.
+ */
+
+export type AgentToolGroupKinds = 'builtin' | 'external';
+
+export interface IAgentToolEntry {
+  name: string;
+  title: string;
+  /** The per-caller description, exactly what the runtime would be given. */
+  description: string;
+  /** Starter prompt with «…» placeholders. */
+  template: string;
+  destructive: boolean;
+  /** null — no pod; false — the running pod did not list it; true — it did. */
+  inPod: boolean | null;
+}
+
+export interface IAgentToolGroup {
+  /** Topic key, or `mcp:<serverId>` for an external server. */
+  key: string;
+  title: string;
+  kind: AgentToolGroupKinds;
+  /** External servers only — the row's description. Never url or auth. */
+  description?: string;
+  /**
+   * builtin — at least one tool has inPod === false; external — the server
+   * row changed after the pod started (the mcp-status rule).
+   */
+  afterRestart: boolean;
+  /** Empty for external groups; their tools are served by the server itself. */
+  tools: IAgentToolEntry[];
+}
+
+export interface IAgentToolCatalog {
+  agentId: string;
+  /** ISO; null when no pod runs. */
+  podStartedAt: string | null;
+  /** ISO of the last tools/list the pod made; null if it never did. */
+  listedAt: string | null;
+  groups: IAgentToolGroup[];
+}
+
+/** The snapshot row: what the pod was last told it has. */
+export interface IAgentToolListingData {
+  agentId: string;
+  toolNames: string[];
+  listedAt: Date;
+}
+
+export abstract class IToolListingGateway {
+  abstract record(agentId: string, toolNames: string[]): Promise<void>;
+  abstract findByAgent(agentId: string): Promise<IAgentToolListingData | null>;
+}
diff --git a/api/src/slices/agent/toolCatalog/dto/agentToolCatalog.dto.ts b/api/src/slices/agent/toolCatalog/dto/agentToolCatalog.dto.ts
new file mode 100644
index 00000000..71b7a18d
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/dto/agentToolCatalog.dto.ts
@@ -0,0 +1,93 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+/**
+ * GET /agents/:id/tools (CLEAN-109). The tools this agent's runtime would
+ * receive, grouped for the chat's Tools panel, with a per-tool flag saying
+ * whether the running pod already has it. Contract:
+ * specs/016-agent-tool-parity/contracts/agent-tools.openapi.yaml.
+ */
+export class AgentToolEntryDto {
+  @ApiProperty({ description: 'Technical MCP tool name.', example: 'register_mcp_server' })
+  name: string;
+
+  @ApiProperty({ example: 'Register an MCP server' })
+  title: string;
+
+  @ApiProperty({
+    description: 'The per-caller description, exactly what the runtime would be given.',
+  })
+  description: string;
+
+  @ApiProperty({
+    description: 'Starter prompt with «…» placeholders.',
+    example: 'Register the MCP server at «url» named «name»',
+  })
+  template: string;
+
+  @ApiProperty({ description: 'The tool removes, revokes or interrupts something and needs confirm: true.' })
+  destructive: boolean;
+
+  @ApiProperty({
+    nullable: true,
+    type: Boolean,
+    description:
+      'null — no pod runs; false — the running pod did not list this tool (restart needed); true — it did.',
+  })
+  inPod: boolean | null;
+}
+
+export class AgentToolGroupDto {
+  @ApiProperty({
+    description: 'Topic key (e.g. mcp_servers) or mcp:<serverId> for an external server.',
+    example: 'mcp_servers',
+  })
+  key: string;
+
+  @ApiProperty({ example: 'MCP servers' })
+  title: string;
+
+  @ApiProperty({ enum: ['builtin', 'external'] })
+  kind: 'builtin' | 'external';
+
+  @ApiProperty({
+    required: false,
+    description: "External servers only — the server row's description. Never its url or auth value.",
+  })
+  description?: string;
+
+  @ApiProperty({
+    description:
+      'builtin — at least one tool has inPod=false; external — the server row changed after the pod started.',
+  })
+  afterRestart: boolean;
+
+  @ApiProperty({
+    type: [AgentToolEntryDto],
+    description: 'Empty for external groups; their tools are served by the server itself.',
+  })
+  tools: AgentToolEntryDto[];
+}
+
+export class AgentToolCatalogDto {
+  @ApiProperty()
+  agentId: string;
+
+  @ApiProperty({
+    nullable: true,
+    type: String,
+    description: 'When the current pod started; null when no pod runs.',
+    example: '2026-09-22T10:33:00.000Z',
+  })
+  podStartedAt: string | null;
+
+  @ApiProperty({
+    nullable: true,
+    type: String,
+    description: 'When the pod last called tools/list; null if it never did.',
+    example: '2026-09-22T10:33:05.000Z',
+  })
+  listedAt: string | null;
+
+  @ApiProperty({ type: [AgentToolGroupDto] })
+  groups: AgentToolGroupDto[];
+}
diff --git a/api/src/slices/agent/toolCatalog/toolCatalog.controller.spec.ts b/api/src/slices/agent/toolCatalog/toolCatalog.controller.spec.ts
new file mode 100644
index 00000000..07b33a56
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/toolCatalog.controller.spec.ts
@@ -0,0 +1,23 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { ToolCatalogController } from './toolCatalog.controller';
+
+describe('ToolCatalogController', () => {
+  const catalog = {
+    forAgent: jest.fn(async (id: string) => ({ agentId: id, podStartedAt: null, listedAt: null, groups: [] })),
+  };
+  const controller = new ToolCatalogController(catalog as never);
+  const req = (sub: string) => ({ user: { sub, roles: ['owner'] } }) as unknown as Request;
+
+  it('answers a person with the catalogue', async () => {
+    const result = await controller.tools('agent-1', req('user-1'));
+    expect(result.agentId).toBe('agent-1');
+    expect(catalog.forAgent).toHaveBeenCalledWith('agent-1');
+  });
+
+  it('refuses an agent token even when it carries Owner', async () => {
+    await expect(controller.tools('agent-1', req('agent:admin'))).rejects.toThrow(
+      ForbiddenException,
+    );
+  });
+});
diff --git a/api/src/slices/agent/toolCatalog/toolCatalog.controller.ts b/api/src/slices/agent/toolCatalog/toolCatalog.controller.ts
new file mode 100644
index 00000000..e6e5c645
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/toolCatalog.controller.ts
@@ -0,0 +1,54 @@
+import {
+  Controller,
+  ForbiddenException,
+  Get,
+  Param,
+  Req,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiTags,
+} from '@nestjs/swagger';
+import type { Request } from 'express';
+import { JwtAuthGuard, Roles, RolesGuard } from '#/user/auth/guards';
+import { UserRoleTypes } from '#/user/user/domain';
+import type { IAuthTokenPayload } from '#/user/auth/domain/auth.types';
+import { ToolCatalogService } from './domain/toolCatalog.service';
+import { AgentToolCatalogDto } from './dto/agentToolCatalog.dto';
+
+@ApiTags('agents')
+@ApiBearerAuth()
+@Controller('agents/:id')
+@UseGuards(JwtAuthGuard, RolesGuard)
+@Roles(UserRoleTypes.Owner, UserRoleTypes.Admin)
+export class ToolCatalogController {
+  constructor(private readonly catalog: ToolCatalogService) {}
+
+  @Get('tools')
+  @ApiOperation({
+    operationId: 'getAgentTools',
+    summary:
+      "The tools this agent's runtime would receive from the built-in Ranch MCP " +
+      'server, grouped by topic for the chat\'s Tools panel, with a per-tool ' +
+      '"present in the running pod" flag, plus the agent\'s external MCP servers ' +
+      'as opaque groups. Owner or Admin only; agent tokens get their list from ' +
+      'MCP tools/list instead (CLEAN-109).',
+  })
+  @ApiOkResponse({ type: AgentToolCatalogDto })
+  async tools(
+    @Param('id') id: string,
+    @Req() req: Request & { user?: IAuthTokenPayload },
+  ): Promise<AgentToolCatalogDto> {
+    // An admin agent's token carries Owner, which the role guard admits; the
+    // catalogue is a console surface, so agents are sent to tools/list.
+    if ((req.user?.sub ?? '').startsWith('agent:')) {
+      throw new ForbiddenException(
+        'Agent tokens read their tools from MCP tools/list, not from this endpoint.',
+      );
+    }
+    return this.catalog.forAgent(id);
+  }
+}
diff --git a/api/src/slices/agent/toolCatalog/toolCatalog.module.ts b/api/src/slices/agent/toolCatalog/toolCatalog.module.ts
new file mode 100644
index 00000000..80df3261
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/toolCatalog.module.ts
@@ -0,0 +1,33 @@
+import { Module, forwardRef } from '@nestjs/common';
+import { AuthModule } from '#/user/auth/auth.module';
+import { AgentModule } from '#/agent/agent/agent.module';
+import { PodModule } from '#/agent/pod/pod.module';
+import { McpServerModule } from '#/mcpServer/mcpServer.module';
+import { TOOL_LISTING_RECORDER } from '#/mcp/interfaces/tool-listing-recorder.interface';
+import { ToolListingGateway } from './data/toolListing.gateway';
+import { IToolListingGateway } from './domain/toolCatalog.types';
+import { ToolCatalogService } from './domain/toolCatalog.service';
+import { ToolCatalogController } from './toolCatalog.controller';
+
+/**
+ * The chat's Tools panel, server side (CLEAN-109): GET /agents/:id/tools and
+ * the per-agent snapshot of the last tools/list a pod received. The mcp
+ * slice's listing service comes from the global McpModule; the snapshot is
+ * handed back to it under TOOL_LISTING_RECORDER.
+ */
+@Module({
+  imports: [
+    AuthModule,
+    forwardRef(() => AgentModule),
+    PodModule,
+    McpServerModule,
+  ],
+  controllers: [ToolCatalogController],
+  providers: [
+    ToolCatalogService,
+    { provide: IToolListingGateway, useClass: ToolListingGateway },
+    { provide: TOOL_LISTING_RECORDER, useExisting: IToolListingGateway },
+  ],
+  exports: [IToolListingGateway, TOOL_LISTING_RECORDER],
+})
+export class ToolCatalogModule {}
diff --git a/api/src/slices/agent/toolCatalog/toolCatalog.prisma b/api/src/slices/agent/toolCatalog/toolCatalog.prisma
new file mode 100644
index 00000000..a9f38e1f
--- /dev/null
+++ b/api/src/slices/agent/toolCatalog/toolCatalog.prisma
@@ -0,0 +1,15 @@
+import { Agent } from "../agent/agent"
+
+// The tool names the API last served to this agent's runtime on MCP
+// tools/list — i.e. what the running pod believes it has (CLEAN-109). A pod
+// reads its tools once at boot, so a tool added to the API afterwards is not
+// in its hands until a restart; this row is how the console tells the two
+// apart. Written on every tools/list from an agent token (once per boot in
+// practice), read by GET /agents/:id/tools. Never read by the runtime.
+model AgentToolListing {
+  agentId   String   @id
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  // string[]
+  toolNames Json
+  listedAt  DateTime @default(now())
+}
diff --git a/api/src/slices/bridle/attachment.tool.ts b/api/src/slices/bridle/attachment.tool.ts
index 8f63c006..a5def948 100644
--- a/api/src/slices/bridle/attachment.tool.ts
+++ b/api/src/slices/bridle/attachment.tool.ts
@@ -2,7 +2,7 @@ import { Injectable, Logger } from '@nestjs/common';
 import { Request } from 'express';
 import type { Workbook } from 'exceljs';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
 import { IAuthTokenPayload } from '#/user/auth/domain';
 import { IBridleAttachmentGateway } from './domain/attachment.gateway';
 import { MAX_QUERY_CELLS } from './domain/attachment.constants';
@@ -131,7 +131,14 @@ export class BridleAttachmentTool {
 
   constructor(private readonly attachments: IBridleAttachmentGateway) {}
 
-  @Tool({ name: 'query_attachment', description: DESCRIPTION, parameters })
+  @Tool({
+    name: 'query_attachment',
+    topic: ToolTopics.Attachments,
+    title: 'Ask a question about an attached file',
+    template: 'In the attached file, «question»',
+    description: DESCRIPTION,
+    parameters,
+  })
   async query(
     args: Args,
     _context: unknown,
diff --git a/api/src/slices/browser/browser.tool.spec.ts b/api/src/slices/browser/browser.tool.spec.ts
new file mode 100644
index 00000000..18aa78bb
--- /dev/null
+++ b/api/src/slices/browser/browser.tool.spec.ts
@@ -0,0 +1,50 @@
+import { BrowserTool } from './browser.tool';
+
+/**
+ * The browser tools act for the calling user; what CLEAN-109 added is the
+ * confirmation gate on the two that interrupt a session.
+ */
+const harness = () => {
+  const gateway = {
+    openSession: jest.fn(),
+    closeSession: jest.fn(async () => undefined),
+    resetSession: jest.fn(async () => ({ cdpUrl: 'ws://fresh' })),
+    mintVncUrl: jest.fn(),
+    setStatus: jest.fn(),
+    listSessions: jest.fn(),
+  };
+  const tool = new BrowserTool(gateway as never);
+  return { tool, gateway };
+};
+
+const textOf = (r: { content: { text: string }[] }) => r.content[0].text;
+
+describe('BrowserTool — destructive tools require confirm', () => {
+  it('closes a session once confirmed', async () => {
+    const { tool, gateway } = harness();
+    const result = await tool.close({ userId: 'u', sessionId: 's', confirm: true });
+    expect(gateway.closeSession).toHaveBeenCalledWith('u', 's');
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('"sessionId": "s"');
+  });
+
+  it('refuses to close without confirm and names the session', async () => {
+    const { tool, gateway } = harness();
+    const result = await tool.close({ userId: 'u', sessionId: 's' });
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('close the browser session s');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(gateway.closeSession).not.toHaveBeenCalled();
+  });
+
+  it('resets a session once confirmed and refuses otherwise', async () => {
+    const { tool, gateway } = harness();
+    expect(
+      (await tool.reset({ userId: 'u', sessionId: 's' })).isError,
+    ).toBe(true);
+    expect(gateway.resetSession).not.toHaveBeenCalled();
+    const result = await tool.reset({ userId: 'u', sessionId: 's', confirm: true });
+    expect(gateway.resetSession).toHaveBeenCalledWith('u', 's');
+    expect(textOf(result)).toContain('ws://fresh');
+  });
+});
diff --git a/api/src/slices/browser/browser.tool.ts b/api/src/slices/browser/browser.tool.ts
index 75c53f5b..8295ae76 100644
--- a/api/src/slices/browser/browser.tool.ts
+++ b/api/src/slices/browser/browser.tool.ts
@@ -1,15 +1,9 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
+import { CONFIRM_SENTENCE, confirmed, ok } from '#/mcp/tooling';
 import { IBrowserGateway, BrowserSessionStatusTypes } from './domain';
 
-const asText = (value: unknown): string =>
-  typeof value === 'string' ? value : JSON.stringify(value, null, 2);
-
-const ok = (value: unknown) => ({
-  content: [{ type: 'text' as const, text: asText(value) }],
-});
-
 const accountKeyParam = z
   .string()
   .min(1)
@@ -39,6 +33,9 @@ export class BrowserTool {
 
   @Tool({
     name: 'browser_session_open',
+    topic: ToolTopics.Browser,
+    title: 'Open a browser session',
+    template: 'Open a browser session for «account» at «login url»',
     description:
       'Open or reuse a browser session for the given accountKey. Returns the session metadata and a VNC URL the user can open to finish a login manually. The runtime uses the returned cdpUrl internally — agents should not forward it anywhere. Pass loginUrl so the VNC view renders the right page immediately instead of about:blank.',
     parameters: z.object({
@@ -69,33 +66,58 @@ export class BrowserTool {
 
   @Tool({
     name: 'browser_session_close',
+    topic: ToolTopics.Browser,
+    title: 'Close a browser session',
+    template: 'Close the browser session «session»',
+    destructive: true,
     description:
-      'Close (release) a browser session. Profile data stays on disk.',
+      'Close (release) a browser session. Profile data stays on disk. ' +
+      CONFIRM_SENTENCE,
     parameters: z.object({
       userId: z.string(),
       sessionId: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
     }),
   })
-  async close({ userId, sessionId }: { userId: string; sessionId: string }) {
+  async close(args: { userId: string; sessionId: string; confirm?: boolean }) {
+    const { userId, sessionId } = args;
+    const refusal = confirmed(args, `close the browser session ${sessionId}`);
+    if (refusal) return refusal;
     await this.gateway.closeSession(userId, sessionId);
     return ok({ ok: true, sessionId });
   }
 
   @Tool({
     name: 'browser_session_reset',
+    topic: ToolTopics.Browser,
+    title: 'Reset a stuck browser session',
+    template: 'Reset the browser session «session»',
+    destructive: true,
     description:
-      'Hard-reset a stuck session (e.g. after browser_play timed out). Returns a fresh CDP URL on the same profile.',
+      'Hard-reset a stuck session (e.g. after browser_play timed out). Returns a fresh CDP URL on the same profile. ' +
+      CONFIRM_SENTENCE,
     parameters: z.object({
       userId: z.string(),
       sessionId: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
     }),
   })
-  async reset({ userId, sessionId }: { userId: string; sessionId: string }) {
+  async reset(args: { userId: string; sessionId: string; confirm?: boolean }) {
+    const { userId, sessionId } = args;
+    const refusal = confirmed(args, `reset the browser session ${sessionId}`);
+    if (refusal) return refusal;
     return ok(await this.gateway.resetSession(userId, sessionId));
   }
 
   @Tool({
     name: 'browser_session_login_url',
+    topic: ToolTopics.Browser,
+    title: 'Get a login link for a session',
+    template: 'Give me a link to log in to the browser session «session»',
     description:
       'Mint a short-lived VNC URL the user can open in a browser to log in manually (e.g. for 2FA / CAPTCHA). Call this when openSession or browser_play indicates the profile is not authenticated, then forward the URL to the user via Telegram or chat.',
     parameters: z.object({
@@ -110,6 +132,9 @@ export class BrowserTool {
 
   @Tool({
     name: 'browser_session_set_status',
+    topic: ToolTopics.Browser,
+    title: "Set a session's status",
+    template: 'Mark the browser session «session» as «status»',
     description:
       'Flip a session status flag — call after browser_play completes (idle / needs_login / stuck) so the admin UI reflects reality.',
     parameters: z.object({
@@ -132,6 +157,9 @@ export class BrowserTool {
 
   @Tool({
     name: 'browser_session_list',
+    topic: ToolTopics.Browser,
+    title: 'List browser sessions',
+    template: 'List the browser sessions of the user «user»',
     description: 'List browser sessions for a user.',
     parameters: z.object({
       userId: z.string(),
diff --git a/api/src/slices/chat/chat.module.ts b/api/src/slices/chat/chat.module.ts
index 8578fe00..a06c5b56 100644
--- a/api/src/slices/chat/chat.module.ts
+++ b/api/src/slices/chat/chat.module.ts
@@ -4,6 +4,7 @@ import { AgentModule } from '#/agent/agent/agent.module';
 import { LlmModule } from '#/llm/llm.module';
 import { ChatController } from './chat.controller';
 import { MyChatController } from './myChat.controller';
+import { ChatTool } from './chat.tool';
 import { IChatGateway, ChatSyncService, ChatInsightService } from './domain';
 import { ChatGateway } from './data/chat.gateway';
 import { ChatMapper } from './data/chat.mapper';
@@ -21,6 +22,7 @@ import { ChatMapper } from './data/chat.mapper';
     ChatMapper,
     ChatSyncService,
     ChatInsightService,
+    ChatTool,
     {
       provide: IChatGateway,
       useClass: ChatGateway,
diff --git a/api/src/slices/chat/chat.tool.spec.ts b/api/src/slices/chat/chat.tool.spec.ts
new file mode 100644
index 00000000..068d18b6
--- /dev/null
+++ b/api/src/slices/chat/chat.tool.spec.ts
@@ -0,0 +1,435 @@
+import {
+  BadGatewayException,
+  BadRequestException,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import type { Request } from 'express';
+import { ChatTool } from './chat.tool';
+import type { IChatGateway, IChatSessionData } from './domain';
+import type { ChatSyncService, ChatInsightService } from './domain';
+import type {
+  TranscriptReaderService,
+  TranscriptMessage,
+} from '#/agent/file/domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * A chat is somebody's conversation with an agent. Worth more than the happy
+ * path: that a plain agent cannot see or call these, that a transcript reply
+ * carries attachment metadata and never file contents, and that a summary
+ * that cannot be produced comes back as a sentence naming the next move.
+ */
+const session = (
+  overrides: Partial<IChatSessionData> = {},
+): IChatSessionData => ({
+  id: 'chat-1',
+  agentId: 'agent-a',
+  channel: 'bridle',
+  externalUserId: 'user-7',
+  sessionKey: 'bridle_user-7_2026-09-17',
+  title: 'Refund for order 42',
+  preview: 'Thanks, that solved it.',
+  lastRole: 'user',
+  lastMessageAt: new Date('2026-09-17T10:00:00.000Z'),
+  messageCount: 6,
+  userMessageCount: 3,
+  lastIndexedEventId: 'evt-6',
+  lastIndexedSize: 4096,
+  summary: null,
+  summaryAt: null,
+  insights: null,
+  archived: false,
+  createdAt: new Date('2026-09-17T09:00:00.000Z'),
+  updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  ...overrides,
+});
+
+const turns = (n: number): TranscriptMessage[] =>
+  Array.from({ length: n }, (_, i) => ({
+    id: `evt-${i + 1}`,
+    role: i % 2 === 0 ? 'user' : 'assistant',
+    text: `turn ${i + 1}`,
+    ts: 1_700_000_000_000 + i,
+  }));
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: ChatTool;
+  chats: jest.Mocked<Pick<IChatGateway, 'list' | 'findById'>>;
+  reader: jest.Mocked<Pick<TranscriptReaderService, 'read'>>;
+  sync: jest.Mocked<Pick<ChatSyncService, 'syncAll'>>;
+  insight: jest.Mocked<Pick<ChatInsightService, 'summarize'>>;
+}
+
+function harness(): Harness {
+  const chats = {
+    list: jest.fn().mockResolvedValue({ items: [session()], total: 1 }),
+    findById: jest.fn().mockResolvedValue(session()),
+  } as unknown as Harness['chats'];
+  const reader = {
+    read: jest.fn().mockResolvedValue(turns(6)),
+  } as unknown as Harness['reader'];
+  const sync = {
+    syncAll: jest.fn().mockResolvedValue({
+      scannedAgents: 1,
+      scannedFiles: 3,
+      upserted: 2,
+      skipped: 1,
+    }),
+  } as unknown as Harness['sync'];
+  const insight = {
+    summarize: jest.fn().mockResolvedValue(
+      session({
+        summary: 'The user asked for a refund and got it.',
+        summaryAt: new Date('2026-09-17T11:00:00.000Z'),
+        insights: {
+          topics: ['refund'],
+          sentiment: 'positive',
+          resolved: true,
+          language: 'en',
+        },
+      }),
+    ),
+  } as unknown as Harness['insight'];
+
+  const tool = new ChatTool(
+    chats as unknown as IChatGateway,
+    reader as unknown as TranscriptReaderService,
+    sync as unknown as ChatSyncService,
+    insight as unknown as ChatInsightService,
+  );
+  return { tool, chats, reader, sync, insight };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+/** Loose view of a JSON reply: the tests reach into whichever fields they check. */
+interface Body {
+  [key: string]: any;
+  messages: any[];
+  items: any[];
+}
+const parse = (result: { content: { text: string }[] }) =>
+  JSON.parse(textOf(result)) as Body;
+
+describe('ChatTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, chats, reader, sync, insight } = harness();
+    await expect(tool.listChats({}, null, plainAgent())).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+    await expect(
+      tool.getChat({ id: 'chat-1' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(
+      tool.getChatMessages({ id: 'chat-1' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(tool.syncChats({}, null, plainAgent())).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+    await expect(
+      tool.summarizeChat({ id: 'chat-1' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(
+      tool.exportChat({ id: 'chat-1' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(chats.list).not.toHaveBeenCalled();
+    expect(chats.findById).not.toHaveBeenCalled();
+    expect(reader.read).not.toHaveBeenCalled();
+    expect(sync.syncAll).not.toHaveBeenCalled();
+    expect(insight.summarize).not.toHaveBeenCalled();
+  });
+});
+
+describe('list_chats', () => {
+  it('lists with the console defaults and passes the filters through', async () => {
+    const { tool, chats } = harness();
+    const result = await tool.listChats(
+      { agentId: 'agent-a', search: 'refund' },
+      null,
+      operator(),
+    );
+    expect(chats.list).toHaveBeenCalledWith({
+      agentId: 'agent-a',
+      search: 'refund',
+      page: 1,
+      perPage: 50,
+    });
+    const body = parse(result);
+    expect(body.total).toBe(1);
+    expect(body.page).toBe(1);
+    expect(body.perPage).toBe(50);
+    expect(body.items[0].id).toBe('chat-1');
+    expect(body.items[0].title).toBe('Refund for order 42');
+    // Index bookkeeping is not something to show the person.
+    expect(body.items[0].lastIndexedEventId).toBeUndefined();
+  });
+
+  it('honours an explicit page and size', async () => {
+    const { tool, chats } = harness();
+    await tool.listChats({ page: 3, perPage: 10 }, null, operator());
+    expect(chats.list).toHaveBeenCalledWith(
+      expect.objectContaining({ page: 3, perPage: 10 }),
+    );
+  });
+});
+
+describe('get_chat', () => {
+  it('returns the session metadata', async () => {
+    const { tool, chats } = harness();
+    const result = await tool.getChat({ id: 'chat-1' }, null, operator());
+    expect(chats.findById).toHaveBeenCalledWith('chat-1');
+    const body = parse(result);
+    expect(body.id).toBe('chat-1');
+    expect(body.agentId).toBe('agent-a');
+    expect(body.userMessageCount).toBe(3);
+  });
+
+  it('names the next move when the chat does not exist', async () => {
+    const { tool, chats } = harness();
+    chats.findById.mockResolvedValue(null);
+    const result = await tool.getChat({ id: 'nope' }, null, operator());
+    expect(textOf(result)).toContain('Chat nope not found');
+    expect(textOf(result)).toContain('list_chats');
+  });
+});
+
+describe('get_chat_messages', () => {
+  it('reads the transcript the way the controller does and tails 20 by default', async () => {
+    const { tool, reader } = harness();
+    reader.read.mockResolvedValue(turns(25));
+    const result = await tool.getChatMessages(
+      { id: 'chat-1' },
+      null,
+      operator(),
+    );
+    expect(reader.read).toHaveBeenCalledWith(
+      'agent-a',
+      'data/sessions/bridle_user-7_2026-09-17.jsonl',
+      { types: ['user', 'assistant', 'summary'], filterTransient: true },
+    );
+    const body = parse(result);
+    expect(body.chatId).toBe('chat-1');
+    expect(body.messages).toHaveLength(20);
+    expect(body.messages[0].text).toBe('turn 6');
+    expect(body.messages[19].text).toBe('turn 25');
+    expect(body.hasMore).toBe(true);
+    expect(body.nextCursor).toBe('5');
+  });
+
+  it('returns role, text and ts per message, with attachment metadata and no model-facing text', async () => {
+    const { tool, reader } = harness();
+    reader.read.mockResolvedValue([
+      {
+        id: 'evt-1',
+        role: 'user',
+        text: 'Here is the invoice',
+        ts: 1_700_000_000_000,
+        agentText: 'Here is the invoice\n\n<file>THE WHOLE SPREADSHEET</file>',
+        attachments: [
+          {
+            id: 'att-1',
+            name: 'invoice.csv',
+            mimeType: 'text/csv',
+            size: 1234,
+            kind: 'text',
+          },
+        ],
+      },
+      {
+        id: 'evt-2',
+        role: 'assistant',
+        text: 'Got it.',
+        ts: 1_700_000_000_001,
+      },
+    ]);
+    const result = await tool.getChatMessages(
+      { id: 'chat-1', limit: 5 },
+      null,
+      operator(),
+    );
+    const body = parse(result);
+    expect(body.messages[0]).toEqual({
+      id: 'evt-1',
+      role: 'user',
+      text: 'Here is the invoice',
+      ts: 1_700_000_000_000,
+      attachments: [
+        {
+          id: 'att-1',
+          name: 'invoice.csv',
+          mimeType: 'text/csv',
+          size: 1234,
+          kind: 'text',
+        },
+      ],
+    });
+    expect(body.messages[1]).toEqual({
+      id: 'evt-2',
+      role: 'assistant',
+      text: 'Got it.',
+      ts: 1_700_000_000_001,
+    });
+    expect(textOf(result)).not.toContain('THE WHOLE SPREADSHEET');
+  });
+
+  it('passes an explicit limit, cursor and types through', async () => {
+    const { tool, reader } = harness();
+    reader.read.mockResolvedValue(turns(6));
+    const result = await tool.getChatMessages(
+      { id: 'chat-1', limit: 2, cursor: '4', types: ['user', 'tool_call'] },
+      null,
+      operator(),
+    );
+    expect(reader.read).toHaveBeenCalledWith(
+      'agent-a',
+      expect.any(String),
+      expect.objectContaining({ types: ['user', 'tool_call'] }),
+    );
+    const body = parse(result);
+    expect(body.messages.map((m: { text: string }) => m.text)).toEqual([
+      'turn 3',
+      'turn 4',
+    ]);
+    expect(body.nextCursor).toBe('2');
+  });
+
+  it('treats an unreadable transcript as empty, like the console', async () => {
+    const { tool, reader } = harness();
+    reader.read.mockRejectedValue(new Error('NoSuchKey'));
+    const result = await tool.getChatMessages(
+      { id: 'chat-1' },
+      null,
+      operator(),
+    );
+    const body = parse(result);
+    expect(body.messages).toEqual([]);
+    expect(body.hasMore).toBe(false);
+    expect(body.note).toContain('missing or unreadable');
+  });
+
+  it('names the next move when the chat does not exist', async () => {
+    const { tool, chats, reader } = harness();
+    chats.findById.mockResolvedValue(null);
+    const result = await tool.getChatMessages({ id: 'nope' }, null, operator());
+    expect(textOf(result)).toContain('Chat nope not found');
+    expect(reader.read).not.toHaveBeenCalled();
+  });
+});
+
+describe('sync_chats', () => {
+  it('reconciles one agent when given an id', async () => {
+    const { tool, sync } = harness();
+    const result = await tool.syncChats(
+      { agentId: 'agent-a' },
+      null,
+      operator(),
+    );
+    expect(sync.syncAll).toHaveBeenCalledWith('agent-a');
+    expect(parse(result)).toEqual({
+      scannedAgents: 1,
+      scannedFiles: 3,
+      upserted: 2,
+      skipped: 1,
+    });
+  });
+
+  it('reconciles every agent when no id is given', async () => {
+    const { tool, sync } = harness();
+    await tool.syncChats({}, null, operator());
+    expect(sync.syncAll).toHaveBeenCalledWith(undefined);
+  });
+});
+
+describe('summarize_chat', () => {
+  it('returns the session with its new summary and insights', async () => {
+    const { tool, insight } = harness();
+    const result = await tool.summarizeChat({ id: 'chat-1' }, null, operator());
+    expect(insight.summarize).toHaveBeenCalledWith('chat-1');
+    const body = parse(result);
+    expect(body.summary).toBe('The user asked for a refund and got it.');
+    expect(body.insights.sentiment).toBe('positive');
+    expect(body.note).toContain('stored');
+  });
+
+  it('names the next move when the chat does not exist', async () => {
+    const { tool, insight } = harness();
+    insight.summarize.mockRejectedValue(
+      new NotFoundException('Chat nope not found'),
+    );
+    const result = await tool.summarizeChat({ id: 'nope' }, null, operator());
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('Chat nope not found');
+    expect(textOf(result)).toContain('list_chats');
+  });
+
+  it('turns a missing or rejected credential into an error naming the fix', async () => {
+    const { tool, insight } = harness();
+    insight.summarize.mockRejectedValue(
+      new BadRequestException(
+        'No active Anthropic LLM credential — add one in Settings → LLM credentials.',
+      ),
+    );
+    const result = await tool.summarizeChat({ id: 'chat-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('No active Anthropic LLM credential');
+    expect(textOf(result)).toContain('list_llms');
+  });
+
+  it('turns a provider failure into an error that says to retry', async () => {
+    const { tool, insight } = harness();
+    insight.summarize.mockRejectedValue(
+      new BadGatewayException('Anthropic API 529: overloaded'),
+    );
+    const result = await tool.summarizeChat({ id: 'chat-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Anthropic API 529');
+    expect(textOf(result)).toContain('call summarize_chat again');
+  });
+
+  it('lets an unexpected failure surface', async () => {
+    const { tool, insight } = harness();
+    insight.summarize.mockRejectedValue(new Error('boom'));
+    await expect(
+      tool.summarizeChat({ id: 'chat-1' }, null, operator()),
+    ).rejects.toThrow('boom');
+  });
+});
+
+describe('export_chat', () => {
+  it('points at the console download once the chat is known to exist', async () => {
+    const { tool, chats } = harness();
+    const result = await tool.exportChat({ id: 'chat-1' }, null, operator());
+    expect(chats.findById).toHaveBeenCalledWith('chat-1');
+    const body = parse(result);
+    expect(body.downloadPath).toBe('/chats/chat-1/export');
+    expect(body.formats).toEqual(['json', 'markdown', 'csv']);
+    expect(body.note).toContain('needs your login');
+  });
+
+  it('names the next move when the chat does not exist', async () => {
+    const { tool, chats } = harness();
+    chats.findById.mockResolvedValue(null);
+    const result = await tool.exportChat({ id: 'nope' }, null, operator());
+    expect(textOf(result)).toContain('Chat nope not found');
+    expect(textOf(result)).not.toContain('downloadPath');
+  });
+});
diff --git a/api/src/slices/chat/chat.tool.ts b/api/src/slices/chat/chat.tool.ts
new file mode 100644
index 00000000..780c2565
--- /dev/null
+++ b/api/src/slices/chat/chat.tool.ts
@@ -0,0 +1,415 @@
+import {
+  BadGatewayException,
+  BadRequestException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import {
+  TranscriptReaderService,
+  TranscriptMessage,
+} from '#/agent/file/domain';
+import {
+  IChatGateway,
+  ChatSyncService,
+  ChatInsightService,
+  type IChatSessionData,
+} from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+const NOT_FOUND = (id: string) =>
+  ok({ error: `Chat ${id} not found — call list_chats to find the id` });
+
+/** Same defaults as `FilterChatsDto` / `ChatMessagesQueryDto`. */
+const DEFAULT_PAGE = 1;
+const DEFAULT_PER_PAGE = 50;
+const MAX_PER_PAGE = 100;
+/** The tool tails a chat: 20 last turns is a screenful, the console's 50 is not. */
+const DEFAULT_MESSAGE_LIMIT = 20;
+const MAX_MESSAGE_LIMIT = 200;
+
+const MESSAGE_TYPES = [
+  'user',
+  'assistant',
+  'summary',
+  'tool_call',
+  'tool_result',
+  'system',
+] as const;
+const DEFAULT_TYPES: TranscriptMessage['role'][] = [
+  'user',
+  'assistant',
+  'summary',
+];
+
+/**
+ * The index row without its bookkeeping. `sessionKey` stays: it names the
+ * transcript file and export filename, and the person may recognise it from
+ * the console.
+ */
+function toToolChat(s: IChatSessionData) {
+  return {
+    id: s.id,
+    agentId: s.agentId,
+    channel: s.channel,
+    externalUserId: s.externalUserId,
+    sessionKey: s.sessionKey,
+    title: s.title,
+    preview: s.preview,
+    lastRole: s.lastRole,
+    lastMessageAt: s.lastMessageAt,
+    messageCount: s.messageCount,
+    userMessageCount: s.userMessageCount,
+    summary: s.summary,
+    summaryAt: s.summaryAt,
+    insights: s.insights,
+    archived: s.archived,
+    createdAt: s.createdAt,
+  };
+}
+
+/**
+ * The chat history the console shows under Chats, for the operator agent
+ * (CLEAN-109): list and read sessions, replay a transcript tail, reconcile
+ * the index against the runtimes' files, ask for an LLM summary, and point
+ * at the export download.
+ *
+ * Every call goes through the same four things `ChatController` injects —
+ * `IChatGateway`, `TranscriptReaderService`, `ChatSyncService`,
+ * `ChatInsightService` — and calls them the way the controller does: the
+ * transcript path is built from the session's key, an unreadable file is an
+ * empty transcript rather than a failure, and the model-facing text of a
+ * user turn only rides along when tool events were asked for.
+ *
+ * Operator-only: a chat is somebody's conversation with an agent, and a plain
+ * agent must not be able to read other people's sessions.
+ */
+@Injectable()
+export class ChatTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(ChatTool.name);
+
+  constructor(
+    private readonly chats: IChatGateway,
+    private readonly reader: TranscriptReaderService,
+    private readonly sync: ChatSyncService,
+    private readonly insight: ChatInsightService,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  // ─── Reading ─────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'list_chats',
+    topic: ToolTopics.ChatsUsage,
+    title: 'List chats',
+    template: 'List the recent chats «of agent name»',
+    description:
+      'Chat sessions from the index, most recently active first, with the ' +
+      'title, preview, counts and any stored summary of each. Filter by ' +
+      'agent id (list_agents resolves a name), channel or a search over ' +
+      'title / preview / end-user id; archived and internal (cron, ' +
+      'heartbeat) sessions are hidden unless asked for. Paged: `total` says ' +
+      'how many match. Use the `id` of a row with get_chat, ' +
+      'get_chat_messages, summarize_chat or export_chat.',
+    parameters: z.object({
+      agentId: z.string().optional().describe('Restrict to one agent'),
+      channel: z
+        .enum(['bridle', 'telegram', 'slack', 'internal'])
+        .optional()
+        .describe('Restrict to one channel'),
+      search: z
+        .string()
+        .optional()
+        .describe('Matches title / preview / externalUserId'),
+      archived: z
+        .boolean()
+        .optional()
+        .describe('Show archived sessions instead (default false)'),
+      includeInternal: z
+        .boolean()
+        .optional()
+        .describe('Include internal cron/heartbeat sessions (default false)'),
+      page: z.number().int().min(1).optional().describe('Page, from 1'),
+      perPage: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PER_PAGE)
+        .optional()
+        .describe(`Rows per page (default ${DEFAULT_PER_PAGE})`),
+    }),
+  })
+  async listChats(
+    args: {
+      agentId?: string;
+      channel?: string;
+      search?: string;
+      archived?: boolean;
+      includeInternal?: boolean;
+      page?: number;
+      perPage?: number;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const page = args.page ?? DEFAULT_PAGE;
+    const perPage = args.perPage ?? DEFAULT_PER_PAGE;
+    const { items, total } = await this.chats.list({
+      ...args,
+      page,
+      perPage,
+    });
+    return ok({ items: items.map(toToolChat), total, page, perPage });
+  }
+
+  @Tool({
+    name: 'get_chat',
+    topic: ToolTopics.ChatsUsage,
+    title: 'Show a chat',
+    template: 'Show the chat «id»',
+    description:
+      'One chat session from the index: agent, channel, end user, title, ' +
+      'preview, message counts, when it was last active, and the stored ' +
+      'summary and insights if summarize_chat (or the nightly batch) has ' +
+      'run. Metadata only — read the turns with get_chat_messages.',
+    parameters: z.object({
+      id: z.string().describe('Chat session id (list_chats has them)'),
+    }),
+  })
+  async getChat(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const session = await this.chats.findById(id);
+    if (!session) return NOT_FOUND(id);
+    return ok(toToolChat(session));
+  }
+
+  @Tool({
+    name: 'get_chat_messages',
+    topic: ToolTopics.ChatsUsage,
+    title: 'Read chat messages',
+    template: 'Show the last «20» messages of chat «id»',
+    description:
+      'Replay the transcript of a chat, tail first: the last `limit` turns ' +
+      '(default 20) with role, text and timestamp, plus the name, type and ' +
+      'size of any files the person attached (never their contents). ' +
+      '`summary` turns are compaction markers for older history. When ' +
+      '`hasMore` is true, pass `nextCursor` back to read the older page. ' +
+      'Add tool_call / tool_result to `types` only to debug what the agent ' +
+      'did — it makes the reply much larger.',
+    parameters: z.object({
+      id: z.string().describe('Chat session id (list_chats has them)'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_MESSAGE_LIMIT)
+        .optional()
+        .describe(
+          `How many of the latest messages to return (default ${DEFAULT_MESSAGE_LIMIT})`,
+        ),
+      cursor: z
+        .string()
+        .optional()
+        .describe('`nextCursor` from a previous page, to read older turns'),
+      types: z
+        .array(z.enum(MESSAGE_TYPES))
+        .optional()
+        .describe('Event types to include (default user, assistant, summary)'),
+    }),
+  })
+  async getChatMessages(
+    args: {
+      id: string;
+      limit?: number;
+      cursor?: string;
+      types?: TranscriptMessage['role'][];
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const session = await this.chats.findById(args.id);
+    if (!session) return NOT_FOUND(args.id);
+
+    const types = args.types?.length ? args.types : DEFAULT_TYPES;
+    const path = `data/sessions/${session.sessionKey}.jsonl`;
+    let all: TranscriptMessage[];
+    try {
+      all = await this.reader.read(session.agentId, path, {
+        types,
+        filterTransient: true,
+      });
+    } catch (e) {
+      // Same call as the controller: a row may predate its file, or the file
+      // was archived or reset. An empty transcript, not a failure.
+      this.logger.warn(
+        `transcript read failed for ${session.agentId}/${session.sessionKey}: ${(e as Error).message}`,
+      );
+      return ok({
+        chatId: session.id,
+        messages: [],
+        nextCursor: null,
+        hasMore: false,
+        note: 'The transcript file is missing or unreadable — the index row exists but there is nothing to replay.',
+      });
+    }
+
+    const page = TranscriptReaderService.page(
+      all,
+      args.cursor,
+      args.limit ?? DEFAULT_MESSAGE_LIMIT,
+    );
+    // The full model-facing text of a user turn is a debug artefact; it
+    // rides along only when tool events were asked for (the controller's
+    // debug signal).
+    const debug = types.includes('tool_call') || types.includes('tool_result');
+    const messages = debug
+      ? page.messages
+      : TranscriptReaderService.withoutAgentText(page.messages);
+    return ok({
+      chatId: session.id,
+      messages: messages.map((m) => ({
+        id: m.id,
+        role: m.role,
+        text: m.text,
+        ts: m.ts,
+        ...(m.attachments?.length ? { attachments: m.attachments } : {}),
+        ...(m.agentText !== undefined ? { agentText: m.agentText } : {}),
+      })),
+      nextCursor: page.nextCursor,
+      hasMore: page.hasMore,
+    });
+  }
+
+  // ─── Acting ──────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'sync_chats',
+    topic: ToolTopics.ChatsUsage,
+    title: 'Sync chats from runtimes',
+    template: 'Sync chats «of agent name» from their runtimes',
+    description:
+      'Reconcile the chat index against the session files the agent ' +
+      'runtimes keep in storage — for one agent, or every agent when no id ' +
+      'is given. Use it when a chat the person knows happened is missing ' +
+      'from list_chats. Returns how many agents and files were scanned and ' +
+      'how many rows were updated; all zeros with nothing scanned means a ' +
+      'sync was already running — try again in a minute.',
+    parameters: z.object({
+      agentId: z
+        .string()
+        .optional()
+        .describe('Reconcile only this agent; omit for all agents'),
+    }),
+  })
+  async syncChats(
+    { agentId }: { agentId?: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    return ok(await this.sync.syncAll(agentId));
+  }
+
+  @Tool({
+    name: 'summarize_chat',
+    topic: ToolTopics.ChatsUsage,
+    title: 'Summarize a chat',
+    template: 'Summarize the chat «id»',
+    description:
+      'Generate (or refresh) an LLM summary and structured insights — ' +
+      'topics, sentiment, resolved, language — for one chat, and store them ' +
+      'on the session. Needs an active Anthropic credential in Settings → ' +
+      'LLM credentials; the call reports it when one is missing or ' +
+      'rejected. Returns the session with its new summary. A chat whose ' +
+      'transcript is empty comes back unchanged.',
+    parameters: z.object({
+      id: z.string().describe('Chat session id (list_chats has them)'),
+    }),
+  })
+  async summarizeChat(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    try {
+      const session = await this.insight.summarize(id);
+      return ok({
+        ...toToolChat(session),
+        note: session.summary
+          ? 'Summary stored on the session.'
+          : 'No summary produced — the transcript is empty or unreadable.',
+      });
+    } catch (e) {
+      // The service speaks in HTTP exceptions for the console; turn the ones
+      // a person can act on into a sentence naming the next move, and let
+      // anything unexpected surface as an error.
+      if (e instanceof NotFoundException) return NOT_FOUND(id);
+      if (e instanceof BadRequestException) {
+        return err(
+          `${e.message} Add or fix the Anthropic credential (list_llms shows them), then call summarize_chat again.`,
+        );
+      }
+      if (e instanceof BadGatewayException) {
+        return err(
+          `${e.message} The provider did not answer — wait a moment and call summarize_chat again.`,
+        );
+      }
+      throw e;
+    }
+  }
+
+  @Tool({
+    name: 'export_chat',
+    topic: ToolTopics.ChatsUsage,
+    title: 'Export a chat',
+    template: 'Export the chat «id»',
+    description:
+      'Where to download a chat transcript as a file. The download itself ' +
+      'needs the person’s console login, so this returns the path to open ' +
+      'in the console (append ?format=markdown or ?format=csv for a ' +
+      'readable transcript; the default is json with every event) rather ' +
+      'than the file. Confirms the chat exists first.',
+    parameters: z.object({
+      id: z.string().describe('Chat session id (list_chats has them)'),
+    }),
+  })
+  async exportChat(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const session = await this.chats.findById(id);
+    if (!session) return NOT_FOUND(id);
+    return ok({
+      chatId: session.id,
+      title: session.title,
+      downloadPath: `/chats/${session.id}/export`,
+      formats: ['json', 'markdown', 'csv'],
+      note: 'Open this path in the console (it needs your login) to download.',
+    });
+  }
+}
diff --git a/api/src/slices/integration/integration.module.ts b/api/src/slices/integration/integration.module.ts
index 252d64b8..fc268a6c 100644
--- a/api/src/slices/integration/integration.module.ts
+++ b/api/src/slices/integration/integration.module.ts
@@ -7,6 +7,7 @@ import { UserSecretModule } from '#/user/secret/secret.module';
 import { UserBrowserStateModule } from '#/user/browserState/browserState.module';
 import { BridleApiKeyGuard } from '#/bridle/guards/bridleApiKey.guard';
 import { IntegrationController } from './integration.controller';
+import { IntegrationTool } from './integration.tool';
 import { IntegrationInternalController } from './integration.internal.controller';
 import { IntegrationExtensionController } from './integration.extension.controller';
 import { IntegrationService } from './domain/integration.service';
@@ -36,6 +37,7 @@ import { IntegrationMapper } from './data/integration.mapper';
   providers: [
     IntegrationMapper,
     IntegrationService,
+    IntegrationTool,
     BridleApiKeyGuard,
     {
       provide: IIntegrationGateway,
diff --git a/api/src/slices/integration/integration.tool.spec.ts b/api/src/slices/integration/integration.tool.spec.ts
new file mode 100644
index 00000000..a8eb6291
--- /dev/null
+++ b/api/src/slices/integration/integration.tool.spec.ts
@@ -0,0 +1,329 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import type { Request } from 'express';
+import { IntegrationTool } from './integration.tool';
+import type { IntegrationService } from './domain/integration.service';
+import type {
+  IIntegrationAccountData,
+  ILoginInstructionData,
+} from './domain/integration.types';
+import { UserRoleTypes } from '#/user/user/domain';
+import { MCP_TOOL_METADATA_KEY, ToolTopics } from '#/mcp/decorators';
+import type { ToolMetadata } from '#/mcp/decorators';
+import { toolMetadataProblems } from '#/mcp/services/mcp-registry.service';
+
+/**
+ * These tools hand an agent the user's integration accounts. Two things
+ * matter more than the happy path: that no credential ever comes back
+ * through them (the rows are metadata, but a sentinel proves the strip is
+ * real), and that disconnecting waits for the person's yes.
+ */
+const SENTINEL = 'SENTINEL-INTEGRATION';
+
+/**
+ * A row as the service would return it, plus every secret-shaped field a
+ * future column might add. The tool must drop all of them.
+ */
+const account = (
+  overrides: Partial<IIntegrationAccountData> = {},
+): IIntegrationAccountData =>
+  ({
+    id: 'acc-1',
+    userId: 'user-1',
+    service: 'instagram',
+    accountKey: 'miybot',
+    mechanism: 'browser',
+    label: 'Main IG',
+    status: 'pending',
+    createdAt: new Date('2026-09-17T10:00:00.000Z'),
+    updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+    secret: SENTINEL,
+    cookies: [{ name: 'sessionid', value: SENTINEL }],
+    token: SENTINEL,
+    password: SENTINEL,
+    ...overrides,
+  }) as IIntegrationAccountData;
+
+const loginInstruction = (): ILoginInstructionData => ({
+  accountId: 'acc-1',
+  siteUrl: 'https://www.instagram.com/accounts/login/',
+  helpUrl: 'https://admin.test/sessions',
+  instructions: 'Open Instagram and log in as @miybot.',
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const agent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: IntegrationTool;
+  service: {
+    listCatalogue: jest.Mock;
+    listAccounts: jest.Mock;
+    connect: jest.Mock;
+    openLogin: jest.Mock;
+    getAccount: jest.Mock;
+    disconnect: jest.Mock;
+  };
+}
+
+function harness(): Harness {
+  const service = {
+    listCatalogue: jest.fn().mockReturnValue([
+      {
+        service: 'instagram',
+        title: 'Instagram',
+        description: 'Post and read DMs.',
+        iconUrl: '/icons/integrations/instagram.svg',
+        mechanism: 'browser',
+        loginUrl: 'https://www.instagram.com/accounts/login/',
+      },
+      {
+        service: 'openai',
+        title: 'OpenAI',
+        description: 'API key.',
+        iconUrl: '/icons/integrations/openai.svg',
+        mechanism: 'secret',
+        secretEnvKey: 'OPENAI_API_KEY',
+      },
+    ]),
+    listAccounts: jest.fn().mockResolvedValue([account()]),
+    connect: jest.fn().mockResolvedValue(account()),
+    openLogin: jest.fn().mockResolvedValue(loginInstruction()),
+    getAccount: jest.fn().mockResolvedValue(account()),
+    disconnect: jest.fn().mockResolvedValue(undefined),
+  };
+  const tool = new IntegrationTool(service as unknown as IntegrationService);
+  return { tool, service };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('IntegrationTool — who may use it', () => {
+  it('has no listing gate, like the browser tools it sits beside', () => {
+    const { tool } = harness();
+    expect(
+      (tool as unknown as Record<string, unknown>).isListedForRequest,
+    ).toBeUndefined();
+  });
+});
+
+describe('IntegrationTool — panel metadata', () => {
+  const TOOL_METHODS = [
+    'listIntegrationCatalogue',
+    'listIntegrationAccounts',
+    'createIntegrationAccount',
+    'requestIntegrationLogin',
+    'deleteIntegrationAccount',
+  ] as const;
+
+  const metadataOf = (method: string): Partial<ToolMetadata> =>
+    Reflect.getMetadata(
+      MCP_TOOL_METADATA_KEY,
+      (IntegrationTool.prototype as unknown as Record<string, object>)[method],
+    ) as Partial<ToolMetadata>;
+
+  it('passes the registry check the API refuses to boot without', () => {
+    const problems = TOOL_METHODS.flatMap((m) =>
+      toolMetadataProblems(metadataOf(m)),
+    );
+    expect(problems).toEqual([]);
+  });
+
+  it('exposes exactly the five contract names under the browser topic', () => {
+    const names = TOOL_METHODS.map((m) => metadataOf(m).name).sort();
+    expect(names).toEqual([
+      'create_integration_account',
+      'delete_integration_account',
+      'list_integration_accounts',
+      'list_integration_catalogue',
+      'request_integration_login',
+    ]);
+    for (const m of TOOL_METHODS) {
+      expect(metadataOf(m).topic).toBe(ToolTopics.Browser);
+    }
+    expect(metadataOf('deleteIntegrationAccount').destructive).toBe(true);
+  });
+});
+
+describe('IntegrationTool — reading', () => {
+  it('lists the catalogue with service keys and mechanisms', async () => {
+    const { tool, service } = harness();
+    const text = textOf(await tool.listIntegrationCatalogue({}, null, agent()));
+    expect(service.listCatalogue).toHaveBeenCalled();
+    expect(text).toContain('"service": "instagram"');
+    expect(text).toContain('"mechanism": "secret"');
+    expect(text).toContain('OPENAI_API_KEY');
+  });
+
+  it('lists the accounts of the named user', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.listIntegrationAccounts({ userId: 'user-1' }, null, agent()),
+    );
+    expect(service.listAccounts).toHaveBeenCalledWith('user-1');
+    expect(text).toContain('"id": "acc-1"');
+    expect(text).toContain('"accountKey": "miybot"');
+    expect(text).toContain('"status": "pending"');
+  });
+
+  it('never returns cookies, secrets, tokens or passwords', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.listIntegrationAccounts({ userId: 'user-1' }, null, agent()),
+    );
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('cookies');
+    expect(text).not.toContain('"secret"');
+    expect(text).not.toContain('"token"');
+    expect(text).not.toContain('"password"');
+  });
+});
+
+describe('IntegrationTool — connecting', () => {
+  it('connects an account through the service with the mapped arguments', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.createIntegrationAccount(
+        {
+          userId: 'user-1',
+          service: 'instagram',
+          accountKey: 'miybot',
+          label: 'Main IG',
+        },
+        null,
+        agent(),
+      ),
+    );
+    expect(service.connect).toHaveBeenCalledWith(
+      'user-1',
+      'instagram',
+      'miybot',
+      'Main IG',
+    );
+    expect(text).toContain('"id": "acc-1"');
+    expect(text).toContain('"label": "Main IG"');
+    expect(text).not.toContain(SENTINEL);
+  });
+
+  it('points an unknown service at the catalogue tool', async () => {
+    const { tool, service } = harness();
+    service.connect.mockRejectedValue(
+      new BadRequestException('Unknown service "nope".'),
+    );
+    const result = await tool.createIntegrationAccount(
+      { userId: 'user-1', service: 'nope', accountKey: 'x' },
+      null,
+      agent(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Unknown service "nope"');
+    expect(textOf(result)).toContain('list_integration_catalogue');
+  });
+});
+
+describe('IntegrationTool — login', () => {
+  it('returns the site, help page and instructions for the person', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.requestIntegrationLogin(
+        { userId: 'user-1', id: 'acc-1' },
+        null,
+        agent(),
+      ),
+    );
+    expect(service.openLogin).toHaveBeenCalledWith('user-1', 'acc-1');
+    expect(text).toContain('https://www.instagram.com/accounts/login/');
+    expect(text).toContain('https://admin.test/sessions');
+    expect(text).toContain('log in as @miybot');
+  });
+
+  it('reports a missing account and names the list tool', async () => {
+    const { tool, service } = harness();
+    service.openLogin.mockRejectedValue(new NotFoundException());
+    const text = textOf(
+      await tool.requestIntegrationLogin(
+        { userId: 'user-1', id: 'ghost' },
+        null,
+        agent(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_integration_accounts');
+  });
+
+  it('explains that a secret-mechanism account has no login flow', async () => {
+    const { tool, service } = harness();
+    service.openLogin.mockRejectedValue(
+      new BadRequestException(
+        'Service "openai" uses mechanism "secret". Login flow is only available for browser-mechanism services.',
+      ),
+    );
+    const result = await tool.requestIntegrationLogin(
+      { userId: 'user-1', id: 'acc-2' },
+      null,
+      agent(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('mechanism "secret"');
+    expect(textOf(result)).toContain('console');
+  });
+});
+
+describe('IntegrationTool — disconnecting', () => {
+  it('disconnects once confirmed and names the account', async () => {
+    const { tool, service } = harness();
+    const result = await tool.deleteIntegrationAccount(
+      { userId: 'user-1', id: 'acc-1', confirm: true },
+      null,
+      agent(),
+    );
+    expect(service.getAccount).toHaveBeenCalledWith('user-1', 'acc-1');
+    expect(service.disconnect).toHaveBeenCalledWith('user-1', 'acc-1');
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('"ok": true');
+    expect(textOf(result)).toContain('Main IG');
+    expect(textOf(result)).not.toContain(SENTINEL);
+  });
+
+  it('refuses without confirm, names the account, and does not touch the service', async () => {
+    const { tool, service } = harness();
+    const result = await tool.deleteIntegrationAccount(
+      { userId: 'user-1', id: 'acc-1' },
+      null,
+      agent(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('instagram account «Main IG»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(service.disconnect).not.toHaveBeenCalled();
+  });
+
+  it('falls back to the accountKey when the account has no label', async () => {
+    const { tool, service } = harness();
+    service.getAccount.mockResolvedValue(account({ label: null }));
+    const result = await tool.deleteIntegrationAccount(
+      { userId: 'user-1', id: 'acc-1' },
+      null,
+      agent(),
+    );
+    expect(textOf(result)).toContain('«miybot»');
+  });
+
+  it('reports a missing account before asking for confirmation', async () => {
+    const { tool, service } = harness();
+    service.getAccount.mockRejectedValue(new NotFoundException());
+    const result = await tool.deleteIntegrationAccount(
+      { userId: 'user-1', id: 'ghost' },
+      null,
+      agent(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(textOf(result)).toContain('list_integration_accounts');
+    expect(service.disconnect).not.toHaveBeenCalled();
+  });
+});
diff --git a/api/src/slices/integration/integration.tool.ts b/api/src/slices/integration/integration.tool.ts
new file mode 100644
index 00000000..6082d278
--- /dev/null
+++ b/api/src/slices/integration/integration.tool.ts
@@ -0,0 +1,257 @@
+import {
+  BadRequestException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  stripSecrets,
+  type ToolResult,
+} from '#/mcp/tooling';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { IntegrationService } from './domain/integration.service';
+import type { IIntegrationAccountData } from './domain/integration.types';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/**
+ * Same convention as `browser.tool.ts`: an agent runtime holds a service
+ * token (`sub = agent:<id>`), not the user's identity, so it names the user
+ * it acts for. The rows and the credential stores are keyed by that user.
+ */
+const userIdParam = z
+  .string()
+  .min(1)
+  .describe('Owning user — must match the calling principal.');
+
+/** Same charset the console enforces in `ConnectIntegrationDto`. */
+const accountKeyParam = z
+  .string()
+  .min(1)
+  .max(80)
+  .regex(/^[a-zA-Z0-9_:.-]+$/, {
+    message:
+      'accountKey may only contain alphanumerics, underscore, colon, dot, dash',
+  })
+  .describe(
+    'Account handle on the service, e.g. the Instagram username. Becomes the «service:accountKey» profile browser_play uses.',
+  );
+
+/**
+ * Fields that must never leave through a tool result (FR-004). Integration
+ * rows carry lifecycle metadata only — cookies live in the browser-state
+ * store, API keys in the secret store — but the list is explicit so a
+ * future column with one of these names is dropped without anyone noticing
+ * it had to be.
+ */
+const INTEGRATION_SECRET_KEYS = [
+  'secret',
+  'cookies',
+  'token',
+  'password',
+  'passwordHash',
+  'apiKey',
+  'authValue',
+] as const;
+
+const NOT_FOUND =
+  'Integration account not found — call list_integration_accounts to find the id.';
+
+/**
+ * Integration accounts from the chat (CLEAN-109). What the console's
+ * Integrations page does — see which services exist, connect one, ask the
+ * person to log in, disconnect — an agent can now do for the user it acts
+ * for, through the same `IntegrationService` the controller calls. The
+ * catalogue check, the (user, service, accountKey) idempotency and the
+ * mechanism rules stay in the service; nothing is re-implemented here.
+ *
+ * The credential itself never passes through these tools: cookies arrive
+ * via the Ranch extension, secret values via the console. A login request
+ * returns what the person needs to complete it (site URL, help page,
+ * instructions) — that is for the person, and fine to forward.
+ */
+@Injectable()
+export class IntegrationTool {
+  constructor(private readonly service: IntegrationService) {}
+
+  @Tool({
+    name: 'list_integration_catalogue',
+    topic: ToolTopics.Browser,
+    title: 'Available integrations',
+    template: 'Which integrations can I connect?',
+    description:
+      'List the services Ranch can connect to: the stable service key, the title, and whether it is a browser login (cookies via the Ranch extension) or a secret (an API key entered in the console). Use the service key with create_integration_account.',
+    parameters: z.object({}),
+  })
+  async listIntegrationCatalogue(
+    _args: Record<string, never>,
+    _context: unknown,
+    _httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    return ok(this.service.listCatalogue());
+  }
+
+  @Tool({
+    name: 'list_integration_accounts',
+    topic: ToolTopics.Browser,
+    title: 'My integration accounts',
+    template: 'Which integration accounts does user «user» have?',
+    description:
+      'List the integration accounts connected for the user: id, service, accountKey, label, mechanism and status (pending, connected, needs_login, revoked). Never includes cookies or secret values. Use the id with request_integration_login or delete_integration_account.',
+    parameters: z.object({ userId: userIdParam }),
+  })
+  async listIntegrationAccounts(
+    { userId }: { userId: string },
+    _context: unknown,
+    _httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    return ok(this.present(await this.service.listAccounts(userId)));
+  }
+
+  @Tool({
+    name: 'create_integration_account',
+    topic: ToolTopics.Browser,
+    title: 'Connect an integration account',
+    template: 'Connect my «service» account «label»',
+    description:
+      'Start connecting an account on a catalogue service for the user. Idempotent on (userId, service, accountKey): calling again returns the existing row. The account stays "pending" until the credential is stored — for a browser service call request_integration_login next; for a secret service the person enters the value in the console. Returns the account without any credential.',
+    parameters: z.object({
+      userId: userIdParam,
+      service: z
+        .string()
+        .min(1)
+        .max(40)
+        .describe('Service key from list_integration_catalogue.'),
+      accountKey: accountKeyParam,
+      label: z
+        .string()
+        .max(120)
+        .optional()
+        .describe('Human-friendly label shown in the console.'),
+    }),
+  })
+  async createIntegrationAccount(
+    {
+      userId,
+      service,
+      accountKey,
+      label,
+    }: { userId: string; service: string; accountKey: string; label?: string },
+    _context: unknown,
+    _httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    try {
+      const account = await this.service.connect(
+        userId,
+        service,
+        accountKey,
+        label,
+      );
+      return ok(this.present(account));
+    } catch (e) {
+      // Unknown service key: the service names the catalogue, the tool
+      // names the tool that reads it.
+      if (e instanceof BadRequestException) {
+        return err(
+          `${e.message} Call list_integration_catalogue and use one of its service keys.`,
+        );
+      }
+      throw e;
+    }
+  }
+
+  @Tool({
+    name: 'request_integration_login',
+    topic: ToolTopics.Browser,
+    title: 'Ask for a login',
+    template: 'Ask me to log in to «service»',
+    description:
+      'Get what the person needs to log in to a browser-mechanism integration: the site URL, a help page and step-by-step instructions (log in in their own Chrome, send cookies via the Ranch extension). Forward these to the person; the account flips to "connected" once the extension posts the cookies. Only for browser services — a secret service takes its value in the console. Find the account id with list_integration_accounts.',
+    parameters: z.object({
+      userId: userIdParam,
+      id: z.string().min(1).describe('Integration account id.'),
+    }),
+  })
+  async requestIntegrationLogin(
+    { userId, id }: { userId: string; id: string },
+    _context: unknown,
+    _httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    try {
+      return ok(await this.service.openLogin(userId, id));
+    } catch (e) {
+      if (e instanceof NotFoundException) return ok({ error: NOT_FOUND });
+      if (e instanceof BadRequestException) {
+        return err(
+          `${e.message} A secret-mechanism account takes its value in the console's Integrations page.`,
+        );
+      }
+      throw e;
+    }
+  }
+
+  @Tool({
+    name: 'delete_integration_account',
+    topic: ToolTopics.Browser,
+    title: 'Disconnect an account',
+    template: 'Disconnect my «service» account',
+    destructive: true,
+    description:
+      'Disconnect an integration account for the user: removes the row and wipes its stored credential (browser cookies or the secret value). Agents that used the «service:accountKey» profile lose access. Find the id with list_integration_accounts. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      userId: userIdParam,
+      id: z.string().min(1).describe('Integration account id.'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteIntegrationAccount(
+    args: { userId: string; id: string; confirm?: boolean },
+    _context: unknown,
+    _httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    const { userId, id } = args;
+    // Resolve first so a wrong id is reported as such, not as a refusal to
+    // delete something that does not exist.
+    let account: IIntegrationAccountData;
+    try {
+      account = await this.service.getAccount(userId, id);
+    } catch (e) {
+      if (e instanceof NotFoundException) return ok({ error: NOT_FOUND });
+      throw e;
+    }
+
+    const refusal = confirmed(
+      args,
+      `disconnect the ${account.service} account «${this.displayName(account)}» and wipe its stored credential`,
+    );
+    if (refusal) return refusal;
+
+    await this.service.disconnect(userId, id);
+    return ok({
+      ok: true,
+      id,
+      service: account.service,
+      accountKey: account.accountKey,
+      message: `Disconnected ${account.service} account «${this.displayName(account)}».`,
+    });
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────
+
+  private present<T>(rows: T): T {
+    return stripSecrets(rows, INTEGRATION_SECRET_KEYS);
+  }
+
+  private displayName(account: IIntegrationAccountData): string {
+    return account.label ?? account.accountKey;
+  }
+}
diff --git a/api/src/slices/llm/domain/providers.ts b/api/src/slices/llm/domain/providers.ts
new file mode 100644
index 00000000..40c559fc
--- /dev/null
+++ b/api/src/slices/llm/domain/providers.ts
@@ -0,0 +1,84 @@
+// @scope:api
+// @slice:llm
+// @layer:domain
+// @type:catalogue
+
+/**
+ * The providers and models Ranch knows how to talk to. The console's
+ * credential form is built from the same list (`admin/slices/llm/data/
+ * providers.ts`); keep the two in step. A credential may still name a model
+ * that is not here — the list is what Ranch can vouch for, not a whitelist.
+ */
+export interface ILlmModelDef {
+  id: string;
+  label: string;
+  capabilities: { chat: boolean; embedding: boolean };
+}
+
+export interface ILlmProviderDef {
+  id: string;
+  label: string;
+  /** Other spellings a credential row may carry for this provider. */
+  aliases: string[];
+  models: ILlmModelDef[];
+}
+
+export const LLM_PROVIDERS: ILlmProviderDef[] = [
+  {
+    id: 'claude',
+    label: 'Anthropic',
+    aliases: ['anthropic'],
+    models: [
+      {
+        id: 'claude-opus-4-7',
+        label: 'Claude Opus 4.7',
+        capabilities: { chat: true, embedding: false },
+      },
+      {
+        id: 'claude-sonnet-4-6',
+        label: 'Claude Sonnet 4.6',
+        capabilities: { chat: true, embedding: false },
+      },
+      {
+        id: 'claude-haiku-4-5',
+        label: 'Claude Haiku 4.5',
+        capabilities: { chat: true, embedding: false },
+      },
+    ],
+  },
+  {
+    id: 'openai',
+    label: 'OpenAI',
+    aliases: [],
+    models: [
+      {
+        id: 'gpt-4o',
+        label: 'GPT-4o',
+        capabilities: { chat: true, embedding: false },
+      },
+      {
+        id: 'gpt-4o-mini',
+        label: 'GPT-4o mini',
+        capabilities: { chat: true, embedding: false },
+      },
+      {
+        id: 'text-embedding-3-small',
+        label: 'Embedding 3 small',
+        capabilities: { chat: false, embedding: true },
+      },
+      {
+        id: 'text-embedding-3-large',
+        label: 'Embedding 3 large',
+        capabilities: { chat: false, embedding: true },
+      },
+    ],
+  },
+];
+
+/** Case-insensitive, alias-aware: `Anthropic` and `claude` are one provider. */
+export function findLlmProvider(id: string): ILlmProviderDef | null {
+  const key = id.trim().toLowerCase();
+  return (
+    LLM_PROVIDERS.find((p) => p.id === key || p.aliases.includes(key)) ?? null
+  );
+}
diff --git a/api/src/slices/llm/llm.module.ts b/api/src/slices/llm/llm.module.ts
index 335ed8ab..3aae10b7 100644
--- a/api/src/slices/llm/llm.module.ts
+++ b/api/src/slices/llm/llm.module.ts
@@ -5,7 +5,16 @@ import { ILlmHealthGateway } from './domain/llmHealth.gateway';
 import { LlmGateway } from './data/llm.gateway';
 import { LlmHealthGateway } from './data/llmHealth.gateway';
 import { LlmMapper } from './data/llm.mapper';
+import { LlmTool } from './llm.tool';
 
+/**
+ * No `imports`: LlmModule is a leaf that Workflow, Chat, Usage and Knowledge
+ * all import plainly, and it is loaded while AgentModule is still being
+ * defined. Importing UsageModule or AgentModule from here closes that ring
+ * and leaves `undefined` entries in ChatModule's and UsageModule's imports
+ * at boot (verified). `LlmTool` reaches the usage and agent gateways through
+ * `ModuleRef` instead, see its constructor.
+ */
 @Module({
   controllers: [LlmController],
   providers: [
@@ -18,6 +27,7 @@ import { LlmMapper } from './data/llm.mapper';
       provide: ILlmHealthGateway,
       useClass: LlmHealthGateway,
     },
+    LlmTool,
   ],
   exports: [ILlmGateway, ILlmHealthGateway],
 })
diff --git a/api/src/slices/llm/llm.tool.spec.ts b/api/src/slices/llm/llm.tool.spec.ts
new file mode 100644
index 00000000..7b14a42e
--- /dev/null
+++ b/api/src/slices/llm/llm.tool.spec.ts
@@ -0,0 +1,430 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { ModuleRef } from '@nestjs/core';
+import type { Request } from 'express';
+import { LlmTool } from './llm.tool';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IUsageGateway } from '#/usage/domain';
+import type { IUsageData } from '#/usage/domain';
+import type { ILlmCredentialData } from './domain';
+import type { ILlmGateway, ILlmHealthGateway } from './domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Two things matter more here than the happy paths: that the key handed to
+ * create_llm/update_llm never comes back out of ANY tool (FR-004), and that a
+ * plain agent can neither see nor call these.
+ */
+const SENTINEL = 'SENTINEL-LLM-KEY';
+
+const credential = (
+  overrides: Partial<ILlmCredentialData> = {},
+): ILlmCredentialData => ({
+  id: 'llm-1',
+  provider: 'claude',
+  model: 'claude-sonnet-4-6',
+  fallbackModel: null,
+  label: 'Main Claude',
+  apiKey: SENTINEL,
+  status: 'active',
+  supportsChat: true,
+  supportsEmbedding: false,
+  createdAt: new Date('2026-09-01T00:00:00.000Z'),
+  updatedAt: new Date('2026-09-01T00:00:00.000Z'),
+  ...overrides,
+});
+
+const usageRow = (overrides: Partial<IUsageData> = {}): IUsageData => ({
+  id: 'u-1',
+  agentId: 'agent-a',
+  llmCredentialId: 'llm-1',
+  model: 'claude-sonnet-4-6',
+  date: new Date('2026-09-20T00:00:00.000Z'),
+  inputTokens: 1_000_000,
+  outputTokens: 0,
+  callCount: 3,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+  ...overrides,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: LlmTool;
+  llms: {
+    findById: jest.Mock;
+    create: jest.Mock;
+    update: jest.Mock;
+    delete: jest.Mock;
+  };
+  health: { check: jest.Mock };
+  usage: { findRecentForCredential: jest.Mock };
+  agents: { findAll: jest.Mock; findById: jest.Mock };
+}
+
+function harness(): Harness {
+  const llms = {
+    findById: jest.fn().mockResolvedValue(credential()),
+    create: jest.fn().mockResolvedValue(credential({ id: 'llm-new' })),
+    update: jest.fn().mockResolvedValue(credential({ label: 'Renamed' })),
+    delete: jest.fn().mockResolvedValue(undefined),
+  };
+  const health = {
+    check: jest.fn().mockResolvedValue({
+      ok: true,
+      latencyMs: 480,
+      provider: 'claude',
+      model: 'claude-sonnet-4-6',
+    }),
+  };
+  const usage = {
+    findRecentForCredential: jest.fn().mockResolvedValue([usageRow()]),
+  };
+  const agents = {
+    findAll: jest.fn().mockResolvedValue([]),
+    findById: jest
+      .fn()
+      .mockResolvedValue({ id: 'agent-a', name: 'Support Bot' }),
+  };
+  // LlmTool resolves the cross-slice gateways through ModuleRef (see the
+  // constructor comment); the fake hands back the token asked for.
+  const moduleRef = {
+    get: jest.fn((token: unknown) => {
+      if (token === IUsageGateway) return usage;
+      if (token === IAgentGateway) return agents;
+      throw new Error(`unexpected token ${String(token)}`);
+    }),
+  } as unknown as ModuleRef;
+
+  const tool = new LlmTool(
+    llms as unknown as ILlmGateway,
+    health as unknown as ILlmHealthGateway,
+    moduleRef,
+  );
+  return { tool, llms, health, usage, agents };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('LlmTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, llms } = harness();
+    await expect(
+      tool.getLlm({ id: 'llm-1' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    await expect(
+      tool.deleteLlm({ id: 'llm-1', confirm: true }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(llms.findById).not.toHaveBeenCalled();
+    expect(llms.delete).not.toHaveBeenCalled();
+  });
+});
+
+describe('LlmTool — the key never comes back (FR-004)', () => {
+  it('get_llm returns the row without the key', async () => {
+    const { tool, llms } = harness();
+    const text = textOf(await tool.getLlm({ id: 'llm-1' }, null, operator()));
+    expect(llms.findById).toHaveBeenCalledWith('llm-1');
+    expect(text).toContain('Main Claude');
+    expect(text).toContain('claude-sonnet-4-6');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('apiKey');
+  });
+
+  it('create_llm stores the key and does not echo it', async () => {
+    const { tool, llms } = harness();
+    const text = textOf(
+      await tool.createLlm(
+        {
+          provider: 'claude',
+          model: 'claude-sonnet-4-6',
+          apiKey: SENTINEL,
+          label: 'Main Claude',
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(llms.create).toHaveBeenCalledWith({
+      provider: 'claude',
+      model: 'claude-sonnet-4-6',
+      apiKey: SENTINEL,
+      label: 'Main Claude',
+    });
+    expect(text).toContain('llm-new');
+    expect(text).toContain('health_check_llm');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('apiKey');
+  });
+
+  it('create_llm normalises a pasted .env line, as the console does', async () => {
+    const { tool, llms } = harness();
+    await tool.createLlm(
+      {
+        provider: 'openai',
+        model: 'gpt-4o',
+        apiKey: `OPENAI_API_KEY="${SENTINEL}"`,
+      },
+      null,
+      operator(),
+    );
+    expect(llms.create).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKey: SENTINEL }),
+    );
+  });
+
+  it('update_llm replaces the key, acknowledges, and does not echo it', async () => {
+    const { tool, llms } = harness();
+    const text = textOf(
+      await tool.updateLlm(
+        { id: 'llm-1', apiKey: SENTINEL, label: 'Renamed' },
+        null,
+        operator(),
+      ),
+    );
+    expect(llms.update).toHaveBeenCalledWith('llm-1', {
+      apiKey: SENTINEL,
+      label: 'Renamed',
+    });
+    expect(text).toContain('Renamed');
+    expect(text).toContain('key was replaced');
+    expect(text).not.toContain(SENTINEL);
+    // `changed` may name the field; the row must not carry it.
+    expect(text).not.toContain('"apiKey":');
+  });
+
+  it('health_check_llm scrubs the key from a provider error that echoed it', async () => {
+    const { tool, health } = harness();
+    health.check.mockResolvedValue({
+      ok: false,
+      latencyMs: 12,
+      provider: 'claude',
+      model: 'claude-sonnet-4-6',
+      error: `Anthropic 401: key ${SENTINEL} is invalid`,
+    });
+    const text = textOf(
+      await tool.healthCheckLlm({ id: 'llm-1' }, null, operator()),
+    );
+    expect(text).toContain('"ok": false');
+    expect(text).toContain('[redacted]');
+    expect(text).not.toContain(SENTINEL);
+  });
+
+  it('llm_usage names the credential without its key', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.llmUsage({ id: 'llm-1' }, null, operator()));
+    expect(text).toContain('Main Claude');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('apiKey');
+  });
+});
+
+describe('LlmTool — reading', () => {
+  it('says a missing credential is not found and where to look', async () => {
+    const { tool, llms } = harness();
+    llms.findById.mockResolvedValue(null);
+    for (const call of [
+      () => tool.getLlm({ id: 'nope' }, null, operator()),
+      () => tool.healthCheckLlm({ id: 'nope' }, null, operator()),
+      () => tool.llmUsage({ id: 'nope' }, null, operator()),
+      () => tool.updateLlm({ id: 'nope', label: 'x' }, null, operator()),
+      () => tool.deleteLlm({ id: 'nope', confirm: true }, null, operator()),
+    ]) {
+      const text = textOf(await call());
+      expect(text).toContain('not found');
+      expect(text).toContain('list_llms');
+    }
+    expect(llms.update).not.toHaveBeenCalled();
+    expect(llms.delete).not.toHaveBeenCalled();
+  });
+
+  it('health-checks with the stored credential and passes the verdict through', async () => {
+    const { tool, health } = harness();
+    const text = textOf(
+      await tool.healthCheckLlm({ id: 'llm-1' }, null, operator()),
+    );
+    expect(health.check).toHaveBeenCalledWith(
+      expect.objectContaining({ id: 'llm-1', apiKey: SENTINEL }),
+    );
+    expect(text).toContain('"ok": true');
+    expect(text).toContain('"latencyMs": 480');
+  });
+
+  it('lists every known provider and its models', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.listLlmModels({}, null, operator()));
+    expect(text).toContain('"id": "claude"');
+    expect(text).toContain('"id": "openai"');
+    expect(text).toContain('claude-sonnet-4-6');
+    expect(text).toContain('text-embedding-3-small');
+  });
+
+  it('filters models by provider, accepting an alias', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.listLlmModels({ provider: 'Anthropic' }, null, operator()),
+    );
+    expect(text).toContain('claude-opus-4-7');
+    expect(text).not.toContain('gpt-4o');
+  });
+
+  it('names the known providers when asked about an unknown one', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.listLlmModels({ provider: 'mistral' }, null, operator()),
+    );
+    expect(text).toContain('Unknown provider «mistral»');
+    expect(text).toContain('claude');
+    expect(text).toContain('openai');
+  });
+
+  it('rolls usage up per day and per agent with cost, as the usage route does', async () => {
+    const { tool, usage, agents } = harness();
+    usage.findRecentForCredential.mockResolvedValue([
+      usageRow(),
+      usageRow({ id: 'u-2', agentId: 'agent-b', outputTokens: 1_000_000 }),
+      usageRow({
+        id: 'u-3',
+        agentId: 'agent-a',
+        model: 'gpt-4o',
+        date: new Date('2026-09-19T00:00:00.000Z'),
+        inputTokens: 10,
+        outputTokens: 0,
+        callCount: 1,
+      }),
+    ]);
+    agents.findById.mockImplementation(async (id: string) => {
+      if (id === 'agent-a') return { id, name: 'Support Bot' };
+      throw new Error('gone');
+    });
+    const result = JSON.parse(
+      textOf(await tool.llmUsage({ id: 'llm-1' }, null, operator())),
+    ) as {
+      days: number;
+      last30days: { date: string; model: string; costUsd: number }[];
+      totals: {
+        inputTokens: number;
+        outputTokens: number;
+        callCount: number;
+        costUsd: number;
+      };
+      topModel: string;
+      byAgent: { agentId: string; agentName: string; costUsd: number }[];
+    };
+    expect(usage.findRecentForCredential).toHaveBeenCalledWith('llm-1', 30);
+    expect(result.days).toBe(30);
+    // Two rows of the same day and model merge; newest day first.
+    expect(result.last30days.map((e) => `${e.date}|${e.model}`)).toEqual([
+      '2026-09-20|claude-sonnet-4-6',
+      '2026-09-19|gpt-4o',
+    ]);
+    // Sonnet: 2M input at $3/M + 1M output at $15/M.
+    expect(result.last30days[0].costUsd).toBeCloseTo(21, 6);
+    expect(result.totals.callCount).toBe(7);
+    expect(result.topModel).toBe('claude-sonnet-4-6');
+    // Sorted by cost, and a deleted agent keeps its id as its name.
+    expect(result.byAgent.map((a) => a.agentName)).toEqual([
+      'agent-b',
+      'Support Bot',
+    ]);
+    expect(result.byAgent[0].costUsd).toBeCloseTo(18, 6);
+  });
+});
+
+describe('LlmTool — changing', () => {
+  it('update_llm sends only the fields that were passed', async () => {
+    const { tool, llms } = harness();
+    const text = textOf(
+      await tool.updateLlm(
+        { id: 'llm-1', status: 'disabled', fallbackModel: null },
+        null,
+        operator(),
+      ),
+    );
+    expect(llms.update).toHaveBeenCalledWith('llm-1', {
+      status: 'disabled',
+      fallbackModel: null,
+    });
+    expect(text).toContain('"changed"');
+    expect(text).not.toContain('key was replaced');
+  });
+
+  it('update_llm refuses an empty change', async () => {
+    const { tool, llms } = harness();
+    const result = await tool.updateLlm({ id: 'llm-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(llms.update).not.toHaveBeenCalled();
+  });
+
+  it('delete_llm refuses without confirm and names the credential and its agents', async () => {
+    const { tool, llms, agents } = harness();
+    agents.findAll.mockResolvedValue([
+      { id: 'agent-a', name: 'Support Bot', llmCredentialId: 'llm-1' },
+      { id: 'agent-b', name: 'Other', llmCredentialId: 'llm-2' },
+    ]);
+    const result = await tool.deleteLlm({ id: 'llm-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    const text = textOf(result);
+    expect(text).toContain('«Main Claude»');
+    expect(text).toContain('«Support Bot»');
+    expect(text).not.toContain('«Other»');
+    expect(text).toContain('confirm: true');
+    expect(llms.delete).not.toHaveBeenCalled();
+  });
+
+  it('delete_llm deletes once confirmed and says what to do with orphaned agents', async () => {
+    const { tool, llms, agents } = harness();
+    agents.findAll.mockResolvedValue([
+      { id: 'agent-a', name: 'Support Bot', llmCredentialId: 'llm-1' },
+    ]);
+    const text = textOf(
+      await tool.deleteLlm({ id: 'llm-1', confirm: true }, null, operator()),
+    );
+    expect(llms.delete).toHaveBeenCalledWith('llm-1');
+    expect(text).toContain('deleted');
+    expect(text).toContain('«Support Bot» (agent-a)');
+    expect(text).toContain('update_agent');
+    expect(text).not.toContain(SENTINEL);
+  });
+
+  it('delete_llm surfaces a database refusal instead of a stack', async () => {
+    const { tool, llms } = harness();
+    llms.delete.mockRejectedValue(
+      Object.assign(new Error('Foreign key constraint failed'), {
+        code: 'P2003',
+      }),
+    );
+    const result = await tool.deleteLlm(
+      { id: 'llm-1', confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('still referenced');
+  });
+
+  it('lets an unexpected failure escape, so the MCP layer reports it', async () => {
+    const { tool, llms } = harness();
+    llms.findById.mockRejectedValue(new Error('database is down'));
+    await expect(
+      tool.getLlm({ id: 'llm-1' }, null, operator()),
+    ).rejects.toThrow('database is down');
+  });
+});
diff --git a/api/src/slices/llm/llm.tool.ts b/api/src/slices/llm/llm.tool.ts
new file mode 100644
index 00000000..2313141d
--- /dev/null
+++ b/api/src/slices/llm/llm.tool.ts
@@ -0,0 +1,560 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  CONFIRM_SENTENCE,
+  callerIsOperator,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  stripSecrets,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IUsageGateway, costUsd } from '#/usage/domain';
+import type {
+  ICredentialUsageResponse,
+  IUsageDailyEntry,
+  IUsageData,
+} from '#/usage/domain';
+import {
+  ILlmGateway,
+  ILlmHealthGateway,
+  normalizeCredential,
+  type ILlmCredentialData,
+  type IUpdateLlmCredentialData,
+} from './domain';
+import { LLM_PROVIDERS, findLlmProvider } from './domain/providers';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** The usage endpoints look back this far; the tool answers the same window. */
+const USAGE_DAYS = 30;
+
+const NOT_FOUND = 'LLM credential not found — call list_llms to find the id.';
+
+const STATUS = z.enum(['active', 'disabled']);
+
+/**
+ * LLM credentials from the chat, for the operator agent (CLEAN-109). Each
+ * tool mirrors one route of `LlmController` (and `GET llms/:id/usage` of
+ * `UsageController`) and calls the same gateways, so nothing about
+ * credential normalisation or health-checking is re-implemented here.
+ *
+ * The one rule this file owns is FR-004: a key goes in and never comes out.
+ * Every row passes through `stripSecrets` before it becomes tool text, and
+ * "set" operations acknowledge without echoing what was set.
+ *
+ * Operator agents only: a plain agent has no business reading which models
+ * the Ranch pays for, let alone deleting the credential it runs on.
+ */
+@Injectable()
+export class LlmTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(LlmTool.name);
+
+  /**
+   * Usage and agent gateways come from `ModuleRef` rather than the
+   * constructor: LlmModule is a leaf that Chat, Usage, Workflow and
+   * Knowledge import plainly while AgentModule is still loading, so an
+   * `imports: [UsageModule, AgentModule]` here — forwardRef or not — leaves
+   * `undefined` in ChatModule's and UsageModule's imports at boot. Resolving
+   * the two tokens at call time keeps the module graph as it is.
+   */
+  constructor(
+    private readonly llms: ILlmGateway,
+    private readonly health: ILlmHealthGateway,
+    private readonly moduleRef: ModuleRef,
+  ) {}
+
+  private get usage(): IUsageGateway {
+    return this.moduleRef.get(IUsageGateway, { strict: false });
+  }
+
+  private get agents(): IAgentGateway {
+    return this.moduleRef.get(IAgentGateway, { strict: false });
+  }
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  // ─── Reading ─────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'get_llm',
+    topic: ToolTopics.Llm,
+    title: 'Show a credential',
+    template: 'Show the LLM credential «name»',
+    description:
+      'One LLM credential: provider, model, fallback model, label, status and ' +
+      'which capabilities (chat, embedding) it is registered for. The key is ' +
+      'never returned. Takes the id — list_llms turns a name into one.',
+    parameters: z.object({
+      id: z.string().describe('Credential id, from list_llms'),
+    }),
+  })
+  async getLlm(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const record = await this.llms.findById(id);
+    if (!record) return ok({ error: NOT_FOUND });
+    return ok(stripSecrets(record));
+  }
+
+  @Tool({
+    name: 'list_llm_models',
+    topic: ToolTopics.Llm,
+    title: 'List known models',
+    template: 'Which models can I use with «provider»?',
+    description:
+      'The providers and models Ranch knows: for each, the model ids to put ' +
+      'in create_llm or update_llm and whether it does chat or embeddings. ' +
+      'Optional provider filter (claude/anthropic, openai). A credential may ' +
+      'still name a model that is not listed — this is what Ranch vouches ' +
+      'for, not a whitelist.',
+    parameters: z.object({
+      provider: z
+        .string()
+        .optional()
+        .describe('Only this provider, e.g. "claude" or "openai"'),
+    }),
+  })
+  async listLlmModels(
+    { provider }: { provider?: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    if (provider !== undefined) {
+      const found = findLlmProvider(provider);
+      if (!found) {
+        return ok({
+          error:
+            `Unknown provider «${provider}» — known: ` +
+            LLM_PROVIDERS.map((p) => `${p.id} (${p.label})`).join(', ') +
+            '.',
+        });
+      }
+      return ok({ providers: [found] });
+    }
+    return ok({ providers: LLM_PROVIDERS });
+  }
+
+  @Tool({
+    name: 'llm_usage',
+    topic: ToolTopics.Llm,
+    title: 'Usage of a credential',
+    template: 'How much did the credential «name» cost in the last 30 days?',
+    description:
+      'Token usage and estimated cost of one LLM credential over the last 30 ' +
+      'days, across every agent that used it: a daily breakdown per model, ' +
+      'totals, the model that consumed most, and a per-agent split sorted by ' +
+      'cost. Only usage the agents have reported (daily); today may be ' +
+      'incomplete. Takes the id — list_llms turns a name into one.',
+    parameters: z.object({
+      id: z.string().describe('Credential id, from list_llms'),
+    }),
+  })
+  async llmUsage(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const credential = await this.llms.findById(id);
+    if (!credential) return ok({ error: NOT_FOUND });
+    const rows = await this.usage.findRecentForCredential(id, USAGE_DAYS);
+    const { last30days, totals, topModel, agentTotals } =
+      rollUpAcrossAgents(rows);
+    const byAgent = await this.resolveAgentNames(agentTotals);
+    return ok({
+      credential: describe(credential),
+      days: USAGE_DAYS,
+      last30days,
+      totals,
+      topModel,
+      byAgent,
+    });
+  }
+
+  // ─── Changing ────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'create_llm',
+    topic: ToolTopics.Llm,
+    title: 'Create a credential',
+    template: 'Create an LLM credential «name» for «provider» with key «key»',
+    description:
+      'Register an API key for a provider and model, so agents can be ' +
+      'pointed at it (update_agent with llmCredentialId). Pass the key ' +
+      'exactly as the person gave it — a pasted `NAME=` prefix or quotes ' +
+      'are stripped, as the console does. Returns the new row without the ' +
+      'key; health_check_llm tells whether it actually works. ' +
+      'list_llm_models has the model ids.',
+    parameters: z.object({
+      provider: z.string().describe('Provider id, e.g. "claude" or "openai"'),
+      model: z.string().describe('Model id, e.g. "claude-sonnet-4-6"'),
+      apiKey: z.string().describe('The API key. Stored, never read back.'),
+      fallbackModel: z
+        .string()
+        .optional()
+        .describe('Model to fall back to when the main one is unavailable'),
+      label: z.string().optional().describe('Human name for the credential'),
+      status: STATUS.optional().describe('Default active'),
+      supportsChat: z.boolean().optional().describe('Default true'),
+      supportsEmbedding: z.boolean().optional().describe('Default false'),
+    }),
+  })
+  async createLlm(
+    args: {
+      provider: string;
+      model: string;
+      apiKey: string;
+      fallbackModel?: string;
+      label?: string;
+      status?: 'active' | 'disabled';
+      supportsChat?: boolean;
+      supportsEmbedding?: boolean;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const created = await this.llms.create({
+      ...args,
+      // The DTO normalises a pasted `.env` line before persisting; the tool
+      // must too, or the same paste works in the console and fails here.
+      apiKey: normalizeCredential(args.apiKey),
+    });
+    this.logger.log(
+      `LLM credential created through MCP: ${created.id} ${created.provider}/${created.model}`,
+    );
+    return ok({
+      created: stripSecrets(created),
+      note:
+        'The key is stored and will not be shown again. Call ' +
+        `health_check_llm with id=${created.id} to verify it works.`,
+    });
+  }
+
+  @Tool({
+    name: 'update_llm',
+    topic: ToolTopics.Llm,
+    title: 'Update a credential',
+    template: 'Change the LLM credential «name»: «what to change»',
+    description:
+      'Change any field of a credential: provider, model, fallback model, ' +
+      'label, status (active/disabled) or capabilities, or replace the key. ' +
+      'Only the fields passed change. Returns the row without the key. ' +
+      'Agents already running keep the old values until restarted ' +
+      '(restart_agent).',
+    parameters: z.object({
+      id: z.string().describe('Credential id, from list_llms'),
+      provider: z.string().optional(),
+      model: z.string().optional(),
+      apiKey: z
+        .string()
+        .optional()
+        .describe('New API key. Stored, never read back.'),
+      fallbackModel: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('null clears it'),
+      label: z.string().nullable().optional().describe('null clears it'),
+      status: STATUS.optional(),
+      supportsChat: z.boolean().optional(),
+      supportsEmbedding: z.boolean().optional(),
+    }),
+  })
+  async updateLlm(
+    {
+      id,
+      ...changes
+    }: { id: string } & {
+      provider?: string;
+      model?: string;
+      apiKey?: string;
+      fallbackModel?: string | null;
+      label?: string | null;
+      status?: 'active' | 'disabled';
+      supportsChat?: boolean;
+      supportsEmbedding?: boolean;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const existing = await this.llms.findById(id);
+    if (!existing) return ok({ error: NOT_FOUND });
+    // Only what was passed: prisma would treat an explicit undefined as
+    // "leave alone" anyway, but the `changed` list below must be honest.
+    const data = Object.fromEntries(
+      Object.entries(changes).filter(([, v]) => v !== undefined),
+    ) as IUpdateLlmCredentialData;
+    if (data.apiKey !== undefined) {
+      data.apiKey = normalizeCredential(data.apiKey);
+    }
+    if (Object.keys(data).length === 0) {
+      return err('Nothing to change — pass at least one field besides id.');
+    }
+    const updated = await this.llms.update(id, data);
+    this.logger.log(
+      `LLM credential updated through MCP: ${id} fields=${Object.keys(data).join(',')}`,
+    );
+    return ok({
+      updated: stripSecrets(updated),
+      changed: Object.keys(data),
+      ...(data.apiKey !== undefined
+        ? { note: 'The key was replaced and will not be shown.' }
+        : {}),
+    });
+  }
+
+  @Tool({
+    name: 'delete_llm',
+    topic: ToolTopics.Llm,
+    title: 'Delete a credential',
+    template: 'Delete the LLM credential «name»',
+    destructive: true,
+    description:
+      'Remove an LLM credential. Agents that use it are left without one ' +
+      'and will fail to start until update_agent points them at another; ' +
+      'the tool names them before asking. The key is gone for good — there ' +
+      'is no other copy. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string().describe('Credential id, from list_llms'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteLlm(
+    args: { id: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { id } = args;
+    const credential = await this.llms.findById(id);
+    if (!credential) return ok({ error: NOT_FOUND });
+
+    // Name the agents that would be orphaned in the confirmation itself, so
+    // the person says yes to the real consequence, not to an id.
+    const users = (await this.agents.findAll()).filter(
+      (a) => a.llmCredentialId === id,
+    );
+    const name = displayName(credential);
+    const inUse =
+      users.length > 0
+        ? `, which ${users.length === 1 ? 'agent' : 'agents'} ` +
+          `${users.map((a) => `«${a.name}»`).join(', ')} still ` +
+          `${users.length === 1 ? 'uses' : 'use'} — ` +
+          `${users.length === 1 ? 'it' : 'they'} would be left without a model`
+        : '';
+    const refusal = confirmed(
+      args,
+      `delete the LLM credential ${name} (${id})${inUse}`,
+    );
+    if (refusal) return refusal;
+
+    try {
+      await this.llms.delete(id);
+    } catch (e) {
+      // The schema unlinks agents and usage rows on delete, so a foreign-key
+      // refusal means a reference this tool does not know about. Say so
+      // rather than hand the model a Prisma stack.
+      if ((e as { code?: string }).code === 'P2003') {
+        return err(
+          `The credential ${name} is still referenced and the database ` +
+            'refused to delete it. Point everything that uses it elsewhere ' +
+            'first (list_agents shows llmCredentialId), then try again.',
+        );
+      }
+      throw e;
+    }
+    this.logger.log(`LLM credential deleted through MCP: ${id}`);
+    return ok(
+      `LLM credential ${name} (${id}) deleted.` +
+        (users.length > 0
+          ? ` ${users.map((a) => `«${a.name}» (${a.id})`).join(', ')} ` +
+            'now ' +
+            `${users.length === 1 ? 'has' : 'have'} no credential: assign ` +
+            'another with update_agent (llmCredentialId) and restart_agent.'
+          : ''),
+    );
+  }
+
+  @Tool({
+    name: 'health_check_llm',
+    topic: ToolTopics.Llm,
+    title: 'Health-check a credential',
+    template: 'Check that the LLM credential «name» works',
+    description:
+      'Send a one-token request to the provider with this credential and ' +
+      'report whether it answered, how long it took, and the provider error ' +
+      'if not (an invalid key, an unknown model, a provider Ranch cannot ' +
+      'check). Costs one tiny call. Takes the id — list_llms turns a name ' +
+      'into one.',
+    parameters: z.object({
+      id: z.string().describe('Credential id, from list_llms'),
+    }),
+  })
+  async healthCheckLlm(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const credential = await this.llms.findById(id);
+    if (!credential) return ok({ error: NOT_FOUND });
+    const result = await this.health.check(credential);
+    // The result carries no key by design; the provider's error text is the
+    // one field we do not author, so scrub the key from it just in case.
+    const error =
+      result.error && credential.apiKey
+        ? result.error.split(credential.apiKey).join('[redacted]')
+        : result.error;
+    return ok({
+      ...result,
+      ...(error !== undefined ? { error } : {}),
+      credential: describe(credential),
+    });
+  }
+
+  /** As `UsageController.resolveAgentNames`: a deleted agent keeps its id. */
+  private async resolveAgentNames(
+    agentTotals: IAgentTotals[],
+  ): Promise<ICredentialUsageResponse['byAgent']> {
+    return Promise.all(
+      agentTotals.map(async (entry) => {
+        const agent = await this.agents
+          .findById(entry.agentId)
+          .catch(() => null);
+        return { ...entry, agentName: agent?.name ?? entry.agentId };
+      }),
+    );
+  }
+}
+
+/** The public identity of a credential, for headers and sentences. */
+function describe(c: ILlmCredentialData) {
+  return {
+    id: c.id,
+    provider: c.provider,
+    model: c.model,
+    label: c.label,
+    status: c.status,
+  };
+}
+
+function displayName(c: ILlmCredentialData): string {
+  return `«${c.label ?? `${c.provider}/${c.model}`}»`;
+}
+
+interface IAgentTotals {
+  agentId: string;
+  inputTokens: number;
+  outputTokens: number;
+  callCount: number;
+  costUsd: number;
+}
+
+interface ITotals {
+  inputTokens: number;
+  outputTokens: number;
+  callCount: number;
+  costUsd: number;
+}
+
+/**
+ * The same roll-up `UsageController.rollUpAcrossAgents` does for
+ * `GET llms/:id/usage`: daily rows at `${date}|${model}` grain, totals, the
+ * model with the most tokens, and per-agent totals sorted by cost. Kept in
+ * step with the controller by hand — it is private there, and this slice
+ * cannot import the usage controller.
+ */
+function rollUpAcrossAgents(rows: IUsageData[]): {
+  last30days: IUsageDailyEntry[];
+  totals: ITotals;
+  topModel: string | null;
+  agentTotals: IAgentTotals[];
+} {
+  const daily = new Map<string, IUsageDailyEntry>();
+  const perAgent = new Map<string, IAgentTotals>();
+  const perModelTokens = new Map<string, number>();
+
+  for (const r of rows) {
+    const date = r.date.toISOString().slice(0, 10);
+    const cost = costUsd(r.model, r.inputTokens, r.outputTokens);
+
+    const key = `${date}|${r.model}`;
+    const day = daily.get(key) ?? {
+      date,
+      model: r.model,
+      inputTokens: 0,
+      outputTokens: 0,
+      callCount: 0,
+      costUsd: 0,
+    };
+    day.inputTokens += r.inputTokens;
+    day.outputTokens += r.outputTokens;
+    day.callCount += r.callCount;
+    day.costUsd += cost;
+    daily.set(key, day);
+
+    const agent = perAgent.get(r.agentId) ?? {
+      agentId: r.agentId,
+      inputTokens: 0,
+      outputTokens: 0,
+      callCount: 0,
+      costUsd: 0,
+    };
+    agent.inputTokens += r.inputTokens;
+    agent.outputTokens += r.outputTokens;
+    agent.callCount += r.callCount;
+    agent.costUsd += cost;
+    perAgent.set(r.agentId, agent);
+
+    perModelTokens.set(
+      r.model,
+      (perModelTokens.get(r.model) ?? 0) + r.inputTokens + r.outputTokens,
+    );
+  }
+
+  const last30days = [...daily.values()].sort((a, b) =>
+    b.date.localeCompare(a.date),
+  );
+  const totals = last30days.reduce<ITotals>(
+    (acc, e) => ({
+      inputTokens: acc.inputTokens + e.inputTokens,
+      outputTokens: acc.outputTokens + e.outputTokens,
+      callCount: acc.callCount + e.callCount,
+      costUsd: acc.costUsd + e.costUsd,
+    }),
+    { inputTokens: 0, outputTokens: 0, callCount: 0, costUsd: 0 },
+  );
+
+  let topModel: string | null = null;
+  let topTokens = -1;
+  for (const [model, tokens] of perModelTokens) {
+    if (tokens > topTokens) {
+      topTokens = tokens;
+      topModel = model;
+    }
+  }
+
+  const agentTotals = [...perAgent.values()].sort(
+    (a, b) => b.costUsd - a.costUsd,
+  );
+  return { last30days, totals, topModel, agentTotals };
+}
diff --git a/api/src/slices/log/domain/index.ts b/api/src/slices/log/domain/index.ts
index 02fb43b9..789d077d 100644
--- a/api/src/slices/log/domain/index.ts
+++ b/api/src/slices/log/domain/index.ts
@@ -1 +1,2 @@
 export * from './log.types';
+export * from './log.service';
diff --git a/api/src/slices/log/domain/log.service.ts b/api/src/slices/log/domain/log.service.ts
new file mode 100644
index 00000000..ac478292
--- /dev/null
+++ b/api/src/slices/log/domain/log.service.ts
@@ -0,0 +1,154 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { CoreV1Api, KubeConfig } from '@kubernetes/client-node';
+import {
+  formatKubeError,
+  kubeErrorCode,
+  kubeErrorMessage,
+} from '#/agent/pod/domain/kubeError';
+import { IInfraConfigGateway } from '#/setting/domain';
+import type { IPodLogRead } from './log.types';
+
+/** Tail the console gets when it asks for nothing sensible, and the ceiling. */
+export const DEFAULT_TAIL_LINES = 500;
+export const MAX_TAIL_LINES = 5000;
+
+/**
+ * Agent-pod logs, read once for the console (`LogController`) and the chat
+ * (`LogTool`, CLEAN-109) so the two never drift on what "no pod" looks like.
+ *
+ * Reads via the Kubernetes API (not `kubectl` shell-out) so the same code
+ * works on two setups:
+ *   - Local dev: API runs on host → `KubeConfig.loadFromDefault()` picks up
+ *     `~/.kube/config`.
+ *   - In-cluster: API runs in a Pod → `loadFromDefault()` auto-detects the
+ *     projected ServiceAccount token at
+ *     `/var/run/secrets/kubernetes.io/serviceaccount`.
+ *
+ * Required RBAC: the API's ServiceAccount needs `get` on `pods` and
+ * `pods/log` in the agents namespace (see k8s/templates/rbac.yaml).
+ */
+@Injectable()
+export class LogService {
+  private readonly logger = new Logger(LogService.name);
+  private kubeContext: { coreApi: CoreV1Api; namespace: string } | null = null;
+
+  constructor(private infraConfig: IInfraConfigGateway) {}
+
+  private async getKubeContext(): Promise<{
+    coreApi: CoreV1Api;
+    namespace: string;
+  }> {
+    if (this.kubeContext) return this.kubeContext;
+
+    const [namespace, skipTls] = await Promise.all([
+      this.infraConfig.getAgentsNamespace(),
+      this.infraConfig.getKubeSkipTlsVerify(),
+    ]);
+
+    const kc = new KubeConfig();
+    kc.loadFromDefault();
+
+    // In-cluster the apiserver uses k3s's self-signed CA. It's mounted at
+    // /var/run/secrets/kubernetes.io/serviceaccount/ca.crt; the deployment
+    // exposes it via NODE_EXTRA_CA_CERTS so Node's global TLS stack trusts
+    // it. For local dev / kubeconfigs without embedded CA, enable
+    // `infrastructure.kube_skip_tls_verify` to bypass verification.
+    if (skipTls) {
+      const current = kc.getCurrentCluster();
+      if (current) {
+        kc.clusters = kc.clusters.map((c) =>
+          c.name === current.name ? { ...c, skipTLSVerify: true } : c,
+        );
+      }
+    }
+
+    this.kubeContext = {
+      coreApi: kc.makeApiClient(CoreV1Api),
+      namespace,
+    };
+    return this.kubeContext;
+  }
+
+  /** A `?tail=` query (or a tool argument) into a line count within bounds. */
+  parseTail(raw?: string | number): number {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) return DEFAULT_TAIL_LINES;
+    return Math.min(Math.floor(n), MAX_TAIL_LINES);
+  }
+
+  /**
+   * The last `tailLines` of the agent's pod. `agentStatus` only names the
+   * agent's state in the "no pod" marker, as the console shows it.
+   */
+  async readPodLogs(
+    agentId: string,
+    agentStatus: string,
+    tailLines: number,
+  ): Promise<IPodLogRead> {
+    const podName = `agent-${agentId}`;
+    const { coreApi, namespace } = await this.getKubeContext();
+
+    try {
+      // timestamps: K8s prefixes every line with `<RFC3339Nano-ts> ` (0–9
+      // fraction digits, `Z` zone) — the admin parses it out client-side for
+      // day grouping and a per-line time column. The `[...]` marker responses
+      // below intentionally stay timestamp-less so the frontend can tell them
+      // apart from real log lines.
+      const logs = await coreApi.readNamespacedPodLog({
+        name: podName,
+        namespace,
+        tailLines,
+        timestamps: true,
+      });
+      // SDK returns the raw log string.
+      return {
+        state: 'logs',
+        logs: typeof logs === 'string' ? logs : String(logs ?? ''),
+      };
+    } catch (err) {
+      // 404 is the normal "no pod" state (agent pending/deploying/stopped/failed)
+      // and the admin polls this every 5s — keep it silent. Real failures
+      // (RBAC, network, etc.) still surface as warnings.
+      if (this.isNotFound(err)) {
+        return {
+          state: 'no_pod',
+          logs: `[no pod yet for ${agentStatus} agent]`,
+        };
+      }
+      // 400 BadRequest with "is waiting to start: ContainerCreating /
+      // PodInitializing / …" — pod exists but the container hasn't booted
+      // yet. Transient (2–15s during restart while kubelet pulls image and
+      // mounts volumes). The raw K8s 400 looks scary in the UI, so report a
+      // friendly "container starting" line that the frontend can detect.
+      const waitingReason = this.extractWaitingReason(err);
+      if (waitingReason) {
+        return {
+          state: 'waiting',
+          logs: `[container ${waitingReason.toLowerCase()}]`,
+        };
+      }
+      const message = formatKubeError(err);
+      this.logger.warn(`log fetch failed for ${podName}: ${message}`);
+      return { state: 'failed', logs: `[log fetch failed: ${message}]` };
+    }
+  }
+
+  private isNotFound(err: unknown): boolean {
+    return kubeErrorCode(err) === 404;
+  }
+
+  // K8s returns 400 BadRequest with a body like:
+  //   container "agent" in pod "…" is waiting to start: ContainerCreating
+  // The reason after "is waiting to start: " is what we want for the UI.
+  // Same shape covers PodInitializing, CreateContainerConfigError, etc.
+  // kubeErrorMessage handles both body shapes the k8s SDK produces (parsed
+  // object vs raw JSON string); the ApiException `message` dump is the last
+  // resort so this branch can never silently fall through to the raw error.
+  private extractWaitingReason(err: unknown): string | null {
+    if (kubeErrorCode(err) !== 400) return null;
+    const msg =
+      kubeErrorMessage(err) ?? ((err as { message?: string })?.message || '');
+    const match = msg.match(/is waiting to start:\s*([A-Za-z0-9_]+)/);
+    return match?.[1] ?? null;
+  }
+}
diff --git a/api/src/slices/log/domain/log.types.ts b/api/src/slices/log/domain/log.types.ts
index 85cd37bd..e07b951c 100644
--- a/api/src/slices/log/domain/log.types.ts
+++ b/api/src/slices/log/domain/log.types.ts
@@ -3,3 +3,13 @@ export interface ILogEntry {
   message: string;
   level: 'info' | 'warn' | 'error';
 }
+
+/** What a pod-log read hands back: the text, and why it may be a marker. */
+export type PodLogState = 'logs' | 'no_pod' | 'waiting' | 'failed';
+
+export interface IPodLogRead {
+  /** Real lines came back (`logs`), or the reason they did not. */
+  state: PodLogState;
+  /** Raw log text, or a timestamp-less `[...]` marker line when there is none. */
+  logs: string;
+}
diff --git a/api/src/slices/log/log.controller.ts b/api/src/slices/log/log.controller.ts
index f3e90f9f..511950aa 100644
--- a/api/src/slices/log/log.controller.ts
+++ b/api/src/slices/log/log.controller.ts
@@ -4,78 +4,24 @@ import {
   Param,
   NotFoundException,
   Query,
-  Logger,
 } from '@nestjs/common';
 import { ApiTags, ApiOperation } from '@nestjs/swagger';
-import { CoreV1Api, KubeConfig } from '@kubernetes/client-node';
 import { IAgentGateway } from '#/agent/agent/domain';
-import {
-  formatKubeError,
-  kubeErrorCode,
-  kubeErrorMessage,
-} from '#/agent/pod/domain/kubeError';
-import { IInfraConfigGateway } from '#/setting/domain';
+import { LogService } from './domain';
 
 /**
- * Agent-pod logs.
- *
- * Reads via the Kubernetes API (not `kubectl` shell-out) so the same code
- * works on two setups:
- *   - Local dev: API runs on host → `KubeConfig.loadFromDefault()` picks up
- *     `~/.kube/config`.
- *   - In-cluster: API runs in a Pod → `loadFromDefault()` auto-detects the
- *     projected ServiceAccount token at
- *     `/var/run/secrets/kubernetes.io/serviceaccount`.
- *
- * Required RBAC: the API's ServiceAccount needs `get` on `pods` and
- * `pods/log` in the agents namespace (see k8s/templates/rbac.yaml).
+ * Agent-pod logs for the console. The Kubernetes read lives in `LogService`
+ * so `LogTool` (the chat's `get_agent_logs`) serves the very same lines and
+ * the very same "no pod" / "container starting" markers.
  */
 @ApiTags('logs')
 @Controller('agents/:agentId/logs')
 export class LogController {
-  private readonly logger = new Logger(LogController.name);
-  private kubeContext: { coreApi: CoreV1Api; namespace: string } | null = null;
-
   constructor(
     private agentGateway: IAgentGateway,
-    private infraConfig: IInfraConfigGateway,
+    private logService: LogService,
   ) {}
 
-  private async getKubeContext(): Promise<{
-    coreApi: CoreV1Api;
-    namespace: string;
-  }> {
-    if (this.kubeContext) return this.kubeContext;
-
-    const [namespace, skipTls] = await Promise.all([
-      this.infraConfig.getAgentsNamespace(),
-      this.infraConfig.getKubeSkipTlsVerify(),
-    ]);
-
-    const kc = new KubeConfig();
-    kc.loadFromDefault();
-
-    // In-cluster the apiserver uses k3s's self-signed CA. It's mounted at
-    // /var/run/secrets/kubernetes.io/serviceaccount/ca.crt; the deployment
-    // exposes it via NODE_EXTRA_CA_CERTS so Node's global TLS stack trusts
-    // it. For local dev / kubeconfigs without embedded CA, enable
-    // `infrastructure.kube_skip_tls_verify` to bypass verification.
-    if (skipTls) {
-      const current = kc.getCurrentCluster();
-      if (current) {
-        kc.clusters = kc.clusters.map((c) =>
-          c.name === current.name ? { ...c, skipTLSVerify: true } : c,
-        );
-      }
-    }
-
-    this.kubeContext = {
-      coreApi: kc.makeApiClient(CoreV1Api),
-      namespace,
-    };
-    return this.kubeContext;
-  }
-
   @Get()
   @ApiOperation({ summary: 'Get agent pod logs' })
   async getLogs(
@@ -85,73 +31,11 @@ export class LogController {
     const agent = await this.agentGateway.findById(agentId);
     if (!agent) throw new NotFoundException('Agent not found');
 
-    const podName = `agent-${agentId}`;
-    const tailLines = this.parseTail(tail);
-    const { coreApi, namespace } = await this.getKubeContext();
-
-    try {
-      // timestamps: K8s prefixes every line with `<RFC3339Nano-ts> ` (0–9
-      // fraction digits, `Z` zone) — the admin parses it out client-side for
-      // day grouping and a per-line time column. The `[...]` marker responses
-      // below intentionally stay timestamp-less so the frontend can tell them
-      // apart from real log lines.
-      const logs = await coreApi.readNamespacedPodLog({
-        name: podName,
-        namespace,
-        tailLines,
-        timestamps: true,
-      });
-      // SDK returns the raw log string.
-      return { logs: typeof logs === 'string' ? logs : String(logs ?? '') };
-    } catch (err) {
-      // 404 is the normal "no pod" state (agent pending/deploying/stopped/failed)
-      // and the admin polls this every 5s — keep it silent. Real failures
-      // (RBAC, network, etc.) still surface as warnings.
-      if (this.isNotFound(err)) {
-        return { logs: `[no pod yet for ${agent.status} agent]` };
-      }
-      // 400 BadRequest with "is waiting to start: ContainerCreating /
-      // PodInitializing / …" — pod exists but the container hasn't booted
-      // yet. Transient (2–15s during restart while kubelet pulls image and
-      // mounts volumes). The raw K8s 400 looks scary in the UI, so report a
-      // friendly "container starting" line that the frontend can detect.
-      const waitingReason = this.extractWaitingReason(err);
-      if (waitingReason) {
-        return { logs: `[container ${waitingReason.toLowerCase()}]` };
-      }
-      const message = this.extractKubeError(err);
-      this.logger.warn(`log fetch failed for ${podName}: ${message}`);
-      return { logs: `[log fetch failed: ${message}]` };
-    }
-  }
-
-  private isNotFound(err: unknown): boolean {
-    return kubeErrorCode(err) === 404;
-  }
-
-  // K8s returns 400 BadRequest with a body like:
-  //   container "agent" in pod "…" is waiting to start: ContainerCreating
-  // The reason after "is waiting to start: " is what we want for the UI.
-  // Same shape covers PodInitializing, CreateContainerConfigError, etc.
-  // kubeErrorMessage handles both body shapes the k8s SDK produces (parsed
-  // object vs raw JSON string); the ApiException `message` dump is the last
-  // resort so this branch can never silently fall through to the raw error.
-  private extractWaitingReason(err: unknown): string | null {
-    if (kubeErrorCode(err) !== 400) return null;
-    const msg =
-      kubeErrorMessage(err) ??
-      ((err as { message?: string })?.message || '');
-    const match = msg.match(/is waiting to start:\s*([A-Za-z0-9_]+)/);
-    return match?.[1] ?? null;
-  }
-
-  private parseTail(raw?: string): number {
-    const n = Number(raw);
-    if (!Number.isFinite(n) || n <= 0) return 500;
-    return Math.min(n, 5000);
-  }
-
-  private extractKubeError(err: unknown): string {
-    return formatKubeError(err);
+    const read = await this.logService.readPodLogs(
+      agentId,
+      agent.status,
+      this.logService.parseTail(tail),
+    );
+    return { logs: read.logs };
   }
 }
diff --git a/api/src/slices/log/log.module.ts b/api/src/slices/log/log.module.ts
index a54ed1bd..f9e37a07 100644
--- a/api/src/slices/log/log.module.ts
+++ b/api/src/slices/log/log.module.ts
@@ -1,10 +1,13 @@
 import { Module } from '@nestjs/common';
 import { LogController } from './log.controller';
+import { LogService } from './domain';
+import { LogTool } from './log.tool';
 import { AgentModule } from '#/agent/agent/agent.module';
 import { SettingModule } from '#/setting/setting.module';
 
 @Module({
   imports: [AgentModule, SettingModule],
   controllers: [LogController],
+  providers: [LogService, LogTool],
 })
 export class LogModule {}
diff --git a/api/src/slices/log/log.tool.spec.ts b/api/src/slices/log/log.tool.spec.ts
new file mode 100644
index 00000000..4d60faf4
--- /dev/null
+++ b/api/src/slices/log/log.tool.spec.ts
@@ -0,0 +1,173 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { LogTool } from './log.tool';
+import type { LogService } from './domain';
+import type { IAgentGateway } from '#/agent/agent/domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+// The k8s client ships as ESM, which this jest cannot load; the tool never
+// touches it directly (LogService does), so an empty stand-in is enough.
+jest.mock('@kubernetes/client-node', () => ({
+  CoreV1Api: class {},
+  KubeConfig: class {},
+}));
+
+/**
+ * Pod output is the one place an agent's secrets can leak in plain text, so
+ * the gate matters as much as the read: a plain agent must neither see nor
+ * call this tool. The read itself is `LogService`'s; here we check the tool
+ * asks it for the right pod and tail and turns its markers into sentences a
+ * model can act on.
+ */
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+const THREE_LINES =
+  '2026-09-22T10:00:00Z booting\n' +
+  '2026-09-22T10:00:01Z listening on :8080\n' +
+  '2026-09-22T10:00:02Z ready\n';
+
+interface Harness {
+  tool: LogTool;
+  agents: { findById: jest.Mock };
+  logs: { parseTail: jest.Mock; readPodLogs: jest.Mock };
+}
+
+function harness(): Harness {
+  const agents = {
+    findById: jest.fn().mockResolvedValue({
+      id: 'agent-a',
+      name: 'Support Bot',
+      status: 'running',
+    }),
+  };
+  const logs = {
+    // The real parser clamps to [1, 5000]; the tool only needs its shape.
+    parseTail: jest.fn((raw?: number) => raw ?? 500),
+    readPodLogs: jest
+      .fn()
+      .mockResolvedValue({ state: 'logs', logs: THREE_LINES }),
+  };
+  const tool = new LogTool(
+    agents as unknown as IAgentGateway,
+    logs as unknown as LogService,
+  );
+  return { tool, agents, logs };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('LogTool — who may use it', () => {
+  it('hides the tool from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists it for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, logs, agents } = harness();
+    await expect(
+      tool.getAgentLogs({ agentId: 'agent-a' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(agents.findById).not.toHaveBeenCalled();
+    expect(logs.readPodLogs).not.toHaveBeenCalled();
+  });
+});
+
+describe('LogTool — reading', () => {
+  it('reads the requested tail of the agent pod', async () => {
+    const { tool, logs } = harness();
+    const result = await tool.getAgentLogs(
+      { agentId: 'agent-a', lines: 3 },
+      null,
+      operator(),
+    );
+    expect(logs.readPodLogs).toHaveBeenCalledWith('agent-a', 'running', 3);
+    const parsed = JSON.parse(textOf(result)) as {
+      agentId: string;
+      lines: number;
+      logs: string;
+    };
+    expect(parsed).toEqual({ agentId: 'agent-a', lines: 3, logs: THREE_LINES });
+    expect(result.isError).toBeUndefined();
+  });
+
+  it('asks for 100 lines when not told how many', async () => {
+    const { tool, logs } = harness();
+    await tool.getAgentLogs({ agentId: 'agent-a' }, null, operator());
+    expect(logs.parseTail).toHaveBeenCalledWith(100);
+    expect(logs.readPodLogs).toHaveBeenCalledWith('agent-a', 'running', 100);
+  });
+
+  it('trims to the tail when the read returns more lines than asked', async () => {
+    const { tool } = harness();
+    const parsed = JSON.parse(
+      textOf(
+        await tool.getAgentLogs(
+          { agentId: 'agent-a', lines: 2 },
+          null,
+          operator(),
+        ),
+      ),
+    ) as { lines: number; logs: string };
+    expect(parsed.lines).toBe(2);
+    expect(parsed.logs).toBe(
+      '2026-09-22T10:00:01Z listening on :8080\n2026-09-22T10:00:02Z ready\n',
+    );
+  });
+
+  it('passes a "container starting" marker through as the log text', async () => {
+    const { tool, logs } = harness();
+    logs.readPodLogs.mockResolvedValue({
+      state: 'waiting',
+      logs: '[container containercreating]',
+    });
+    const text = textOf(
+      await tool.getAgentLogs({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(text).toContain('[container containercreating]');
+    expect(text).not.toContain('error');
+  });
+});
+
+describe('LogTool — refusals name the next move', () => {
+  it('points at list_agents for an unknown agent and does not read', async () => {
+    const { tool, agents, logs } = harness();
+    agents.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getAgentLogs({ agentId: 'agent-zzz' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_agents');
+    expect(logs.readPodLogs).not.toHaveBeenCalled();
+  });
+
+  it('points at start_agent when the agent has no pod', async () => {
+    const { tool, agents, logs } = harness();
+    agents.findById.mockResolvedValue({
+      id: 'agent-a',
+      name: 'Support Bot',
+      status: 'stopped',
+    });
+    logs.readPodLogs.mockResolvedValue({
+      state: 'no_pod',
+      logs: '[no pod yet for stopped agent]',
+    });
+    const text = textOf(
+      await tool.getAgentLogs({ agentId: 'agent-a' }, null, operator()),
+    );
+    expect(logs.readPodLogs).toHaveBeenCalledWith('agent-a', 'stopped', 100);
+    expect(text).toContain('Agent «Support Bot» has no running pod');
+    expect(text).toContain('start_agent');
+  });
+});
diff --git a/api/src/slices/log/log.tool.ts b/api/src/slices/log/log.tool.ts
new file mode 100644
index 00000000..de6bb394
--- /dev/null
+++ b/api/src/slices/log/log.tool.ts
@@ -0,0 +1,110 @@
+import { Injectable } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { LogService, MAX_TAIL_LINES } from './domain';
+
+/** What the chat gets when it does not say how many lines it wants. */
+const DEFAULT_TOOL_TAIL = 100;
+
+/**
+ * Pod logs from the chat (CLEAN-109), mirroring `GET agents/:id/logs`. The
+ * read is `LogService`, the same one the console's log pane polls, so the
+ * markers for "no pod" and "container starting" are the console's — with one
+ * difference: a missing pod becomes a sentence naming the next move, because
+ * a model that reads `[no pod yet for stopped agent]` and stops has failed
+ * the person.
+ *
+ * Operator-only: logs can carry anything the agent printed, including
+ * secrets a template author echoed by mistake, so a plain agent must not
+ * be able to read another agent's (or its own) pod output through here.
+ */
+@Injectable()
+export class LogTool implements IConditionallyListedTool {
+  constructor(
+    private readonly agentGateway: IAgentGateway,
+    private readonly logService: LogService,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'get_agent_logs',
+    topic: ToolTopics.Agents,
+    title: 'Read pod logs',
+    template: 'Show the last «100» log lines of the agent «name»',
+    description:
+      "The tail of an agent's pod log, every line prefixed with its RFC3339 " +
+      'timestamp, newest last. Returns { agentId, lines, logs }. Takes the ' +
+      'agent id — resolve a name with list_agents first. When the agent has ' +
+      'no running pod the result says so and points at start_agent; a ' +
+      '[container …] line means the pod is still booting, read again in a ' +
+      'few seconds.',
+    parameters: z.object({
+      agentId: z
+        .string()
+        .describe('Agent id, e.g. agent-abc123 (list_agents has them)'),
+      lines: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_TAIL_LINES)
+        .optional()
+        .describe(
+          `How many lines from the end to return, default ${DEFAULT_TOOL_TAIL}, ` +
+            `at most ${MAX_TAIL_LINES}`,
+        ),
+    }),
+  })
+  async getAgentLogs(
+    args: { agentId: string; lines?: number },
+    _context: unknown,
+    httpRequest: Request & { user?: IAuthTokenPayload },
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+
+    const agent = await this.agentGateway.findById(args.agentId);
+    if (!agent) {
+      return ok({
+        error: `Agent «${args.agentId}» not found — call list_agents to find the id`,
+      });
+    }
+
+    const lines = this.logService.parseTail(args.lines ?? DEFAULT_TOOL_TAIL);
+    const read = await this.logService.readPodLogs(
+      args.agentId,
+      agent.status,
+      lines,
+    );
+    if (read.state === 'no_pod') {
+      return ok({
+        error: `Agent «${agent.name}» has no running pod — start it first (start_agent).`,
+      });
+    }
+
+    return ok({
+      agentId: args.agentId,
+      lines,
+      logs: read.state === 'logs' ? tailOf(read.logs, lines) : read.logs,
+    });
+  }
+}
+
+/** Kubernetes honours `tailLines`, but a cheap trim keeps the promise ours. */
+function tailOf(logs: string, lines: number): string {
+  const trimmed = logs.endsWith('\n') ? logs.slice(0, -1) : logs;
+  const all = trimmed.split('\n');
+  if (all.length <= lines) return logs;
+  return all.slice(-lines).join('\n') + (logs.endsWith('\n') ? '\n' : '');
+}
diff --git a/api/src/slices/mcp/decorators/index.ts b/api/src/slices/mcp/decorators/index.ts
index 45832240..3a6179ca 100644
--- a/api/src/slices/mcp/decorators/index.ts
+++ b/api/src/slices/mcp/decorators/index.ts
@@ -1,4 +1,5 @@
 export * from './tool.decorator';
+export * from './topics';
 export * from './constants';
 export * from './resource.decorator';
 export * from './prompt.decorator';
diff --git a/api/src/slices/mcp/decorators/tool.decorator.ts b/api/src/slices/mcp/decorators/tool.decorator.ts
index d3241af6..d534155c 100644
--- a/api/src/slices/mcp/decorators/tool.decorator.ts
+++ b/api/src/slices/mcp/decorators/tool.decorator.ts
@@ -1,21 +1,47 @@
 import { SetMetadata } from '@nestjs/common';
 import { MCP_TOOL_METADATA_KEY } from './constants';
 import { z } from 'zod';
+import type { ToolTopic } from './topics';
 
 export interface ToolMetadata {
   name: string;
   description: string;
   parameters?: z.ZodTypeAny;
+  /** Accordion of the chat's Tools panel this tool sits in (CLEAN-109). */
+  topic: ToolTopic;
+  /** Human title for the panel row, sentence case, ≤ 60 chars. */
+  title: string;
+  /**
+   * Starter prompt the panel drops into the composer: an imperative English
+   * sentence with «…» placeholders. A starter, not a form — the person edits
+   * it freely.
+   */
+  template: string;
+  /**
+   * The tool removes, revokes, replaces wholesale or interrupts something.
+   * Such a tool must take a boolean `confirm` parameter and refuse without
+   * it (see `confirmed()` in `../tooling`).
+   */
+  destructive?: boolean;
 }
 
 export interface ToolOptions {
   name: string;
   description: string;
   parameters?: z.ZodTypeAny;
+  topic: ToolTopic;
+  title: string;
+  template: string;
+  destructive?: boolean;
 }
 
 /**
- * Decorator that marks a controller method as an MCP tool.
+ * Decorator that marks a provider method as an MCP tool.
+ *
+ * `topic`, `title` and `template` are required: the registry refuses to boot
+ * a tool without them (CLEAN-109), so a new console capability cannot ship a
+ * tool the Tools panel cannot show.
+ *
  * @param {Object} options - The options for the decorator
  * @param {string} options.name - The name of the tool
  * @param {string} options.description - The description of the tool
diff --git a/api/src/slices/mcp/decorators/topics.ts b/api/src/slices/mcp/decorators/topics.ts
new file mode 100644
index 00000000..f4f35d88
--- /dev/null
+++ b/api/src/slices/mcp/decorators/topics.ts
@@ -0,0 +1,65 @@
+/**
+ * The accordions of the chat's Tools panel (CLEAN-109). Every `@Tool` names
+ * exactly one topic; the panel groups by it and orders groups by `order`.
+ * Topics mirror admin-console sections, merged where a section would hold
+ * fewer than three tools. Add a topic here before adding a tool to it — the
+ * registry refuses an unknown topic at boot.
+ */
+export const ToolTopics = {
+  Agents: 'agents',
+  AgentWorkspace: 'agent_workspace',
+  Templates: 'templates',
+  Skills: 'skills',
+  Llm: 'llm',
+  McpServers: 'mcp_servers',
+  Knowledge: 'knowledge',
+  Settings: 'settings',
+  Peers: 'peers',
+  Paddock: 'paddock',
+  UsersKeys: 'users_keys',
+  ChatsUsage: 'chats_usage',
+  Browser: 'browser',
+  Attachments: 'attachments',
+  Platform: 'platform',
+} as const;
+
+export type ToolTopic = (typeof ToolTopics)[keyof typeof ToolTopics];
+
+export interface IToolTopicInfo {
+  key: ToolTopic;
+  title: string;
+  order: number;
+}
+
+export const TOOL_TOPIC_INFO: Record<ToolTopic, IToolTopicInfo> = {
+  agents: { key: 'agents', title: 'Agents', order: 10 },
+  agent_workspace: { key: 'agent_workspace', title: 'Agent workspace', order: 20 },
+  templates: { key: 'templates', title: 'Templates', order: 30 },
+  skills: { key: 'skills', title: 'Skills', order: 40 },
+  llm: { key: 'llm', title: 'LLM credentials', order: 50 },
+  mcp_servers: { key: 'mcp_servers', title: 'MCP servers', order: 60 },
+  knowledge: { key: 'knowledge', title: 'Knowledge', order: 70 },
+  settings: { key: 'settings', title: 'Settings', order: 80 },
+  peers: { key: 'peers', title: 'Peers (A2A)', order: 90 },
+  paddock: { key: 'paddock', title: 'Paddock', order: 100 },
+  users_keys: { key: 'users_keys', title: 'Users & API keys', order: 110 },
+  chats_usage: { key: 'chats_usage', title: 'Chats & usage', order: 120 },
+  browser: { key: 'browser', title: 'Browser & integrations', order: 130 },
+  attachments: { key: 'attachments', title: 'Attachments', order: 140 },
+  platform: { key: 'platform', title: 'Platform', order: 150 },
+};
+
+export const TOOL_TOPIC_KEYS: readonly ToolTopic[] = Object.values(ToolTopics);
+
+export function isToolTopic(value: unknown): value is ToolTopic {
+  return (
+    typeof value === 'string' && (TOOL_TOPIC_KEYS as string[]).includes(value)
+  );
+}
+
+/** Topics in panel order. */
+export function orderedTopics(): IToolTopicInfo[] {
+  return [...TOOL_TOPIC_KEYS]
+    .map((key) => TOOL_TOPIC_INFO[key])
+    .sort((a, b) => a.order - b.order);
+}
diff --git a/api/src/slices/mcp/index.ts b/api/src/slices/mcp/index.ts
index 55fdbb69..a7b38a79 100644
--- a/api/src/slices/mcp/index.ts
+++ b/api/src/slices/mcp/index.ts
@@ -3,3 +3,4 @@ export * from './interfaces';
 export * from './mcp.module';
 export * from './services/mcp-registry.service';
 export * from './services/mcp-executor.service';
+export * from './services/tool-catalog.service';
diff --git a/api/src/slices/mcp/interfaces/index.ts b/api/src/slices/mcp/interfaces/index.ts
index 4050a880..c2e4c73a 100644
--- a/api/src/slices/mcp/interfaces/index.ts
+++ b/api/src/slices/mcp/interfaces/index.ts
@@ -3,3 +3,4 @@ export * from './mcp-tool.interface';
 export * from './http-adapter.interface';
 export * from './dynamic-description.interface';
 export * from './conditional-listing.interface';
+export * from './tool-listing-recorder.interface';
diff --git a/api/src/slices/mcp/interfaces/tool-listing-recorder.interface.ts b/api/src/slices/mcp/interfaces/tool-listing-recorder.interface.ts
new file mode 100644
index 00000000..7cf302f9
--- /dev/null
+++ b/api/src/slices/mcp/interfaces/tool-listing-recorder.interface.ts
@@ -0,0 +1,15 @@
+/**
+ * Optional hook the MCP tools handler calls after serving tools/list to an
+ * agent runtime (CLEAN-109). A pod lists once at boot, so the names it was
+ * given are what it believes it has; whoever provides this token can keep
+ * that snapshot and later tell a tool the pod has from one it lacks.
+ *
+ * Resolved with `strict: false` and a try/catch: the mcp slice does not
+ * depend on the provider, and a missing or failing recorder never breaks a
+ * listing.
+ */
+export const TOOL_LISTING_RECORDER = Symbol('TOOL_LISTING_RECORDER');
+
+export interface IToolListingRecorder {
+  record(agentId: string, toolNames: string[]): Promise<void>;
+}
diff --git a/api/src/slices/mcp/mcp.module.ts b/api/src/slices/mcp/mcp.module.ts
index 0b4a1305..f204ee5f 100644
--- a/api/src/slices/mcp/mcp.module.ts
+++ b/api/src/slices/mcp/mcp.module.ts
@@ -3,6 +3,7 @@ import { DiscoveryModule } from '@nestjs/core';
 import { McpOptions, McpTransportType } from './interfaces';
 import { McpExecutorService } from './services/mcp-executor.service';
 import { McpRegistryService } from './services/mcp-registry.service';
+import { ToolCatalogService } from './services/tool-catalog.service';
 import { SsePingService } from './services/sse-ping.service';
 import { StdioService } from './transport/stdio.service';
 import { createStreamableHttpController } from './transport/streamable-http.controller.factory';
@@ -10,7 +11,7 @@ import { createSseController } from './transport/sse.controller.factory';
 let instanceIdCounter = 0;
 @Module({
   imports: [DiscoveryModule],
-  providers: [McpRegistryService, McpExecutorService],
+  providers: [McpRegistryService, McpExecutorService, ToolCatalogService],
 })
 export class McpModule {
   static forRoot(options: McpOptions): DynamicModule {
@@ -42,11 +43,14 @@ export class McpModule {
     const controllers = this.createControllersFromOptions(mergedOptions);
 
     return {
+      // Global so a slice can read the per-caller tool list (ToolCatalogService)
+      // without re-instantiating this module — there is one registry.
+      global: true,
       imports: [],
       module: McpModule,
       controllers,
       providers,
-      exports: [McpRegistryService],
+      exports: [McpRegistryService, ToolCatalogService],
     };
   }
 
@@ -107,6 +111,7 @@ export class McpModule {
       },
       McpRegistryService,
       McpExecutorService,
+      ToolCatalogService,
     ];
 
     const transports = Array.isArray(options.transport)
diff --git a/api/src/slices/mcp/services/handlers/mcp-tools.handler.spec.ts b/api/src/slices/mcp/services/handlers/mcp-tools.handler.spec.ts
index 83e2b15b..4c4290ac 100644
--- a/api/src/slices/mcp/services/handlers/mcp-tools.handler.spec.ts
+++ b/api/src/slices/mcp/services/handlers/mcp-tools.handler.spec.ts
@@ -27,7 +27,12 @@ interface FakeTool {
   resolveThrows?: boolean;
 }
 
-function makeHarness(tools: FakeTool[]) {
+interface HarnessOptions {
+  recorder?: { record: jest.Mock };
+  request?: object;
+}
+
+function makeHarness(tools: FakeTool[], options: HarnessOptions = {}) {
   const discovered = tools.map((t) => ({
     type: 'tool' as const,
     metadata: {
@@ -53,7 +58,11 @@ function makeHarness(tools: FakeTool[]) {
       if (tool.resolveThrows) throw new Error('resolve blew up');
       return tool.instance;
     }),
+    // The listing recorder (CLEAN-109) is optional; tests that want one
+    // install it on `recorder`.
+    get: jest.fn(() => recorder),
   } as unknown as ModuleRef;
+  let recorder: { record: jest.Mock } | undefined = options.recorder;
 
   const handlers = new Map<unknown, Handler>();
   const mcpServer = {
@@ -65,7 +74,9 @@ function makeHarness(tools: FakeTool[]) {
     },
   } as unknown as McpServer;
 
-  const httpRequest = { user: { sub: 'agent:a1' } } as unknown as Request;
+  const httpRequest = (options.request ?? {
+    user: { sub: 'agent:a1' },
+  }) as unknown as Request;
 
   const handler = new McpToolsHandler(moduleRef, registry);
   handler.registerHandlers(mcpServer, httpRequest);
@@ -197,6 +208,63 @@ describe('McpToolsHandler — per-caller listing', () => {
   });
 });
 
+describe('McpToolsHandler — listing snapshot (CLEAN-109)', () => {
+  const flush = () => new Promise((r) => setImmediate(r));
+
+  it('hands the listed names to the recorder for an agent token', async () => {
+    const recorder = { record: jest.fn(async () => undefined) };
+    const { list } = makeHarness(
+      [
+        { name: 'a', instance: { run: jest.fn() } },
+        {
+          name: 'hidden',
+          instance: { run: jest.fn(), isListedForRequest: jest.fn(async () => false) },
+        },
+        { name: 'b', instance: { run: jest.fn() } },
+      ],
+      { recorder },
+    );
+
+    await list();
+    await flush();
+
+    expect(recorder.record).toHaveBeenCalledWith('a1', ['a', 'b']);
+  });
+
+  it('records nothing for a person listing through the console', async () => {
+    const recorder = { record: jest.fn(async () => undefined) };
+    const { list } = makeHarness([{ name: 'a', instance: { run: jest.fn() } }], {
+      recorder,
+      request: { user: { sub: 'user-7', roles: ['owner'] } },
+    });
+
+    await list();
+    await flush();
+
+    expect(recorder.record).not.toHaveBeenCalled();
+  });
+
+  it('lists as before when no recorder is wired or the recorder fails', async () => {
+    const { list: listWithout } = makeHarness([
+      { name: 'a', instance: { run: jest.fn() } },
+    ]);
+    expect((await listWithout()).tools).toHaveLength(1);
+
+    const failing = {
+      record: jest.fn(async () => {
+        throw new Error('db down');
+      }),
+    };
+    const { list } = makeHarness([{ name: 'a', instance: { run: jest.fn() } }], {
+      recorder: failing,
+    });
+    const result = await list();
+    await flush();
+    expect(result.tools).toHaveLength(1);
+    expect(failing.record).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe('McpToolsHandler — per-caller calling', () => {
   it('refuses a call to a tool that is not listed for this caller', async () => {
     const run = jest.fn(async () => ok('delegated'));
diff --git a/api/src/slices/mcp/services/handlers/mcp-tools.handler.ts b/api/src/slices/mcp/services/handlers/mcp-tools.handler.ts
index a7f039ed..b1323cec 100644
--- a/api/src/slices/mcp/services/handlers/mcp-tools.handler.ts
+++ b/api/src/slices/mcp/services/handlers/mcp-tools.handler.ts
@@ -8,76 +8,74 @@ import {
 import { Injectable, Scope } from '@nestjs/common';
 import { ContextIdFactory, ModuleRef } from '@nestjs/core';
 import { Request } from 'express';
-import { zodToJsonSchema } from 'zod-to-json-schema';
 import { McpRegistryService } from '../mcp-registry.service';
 import { McpHandlerBase } from './mcp-handler.base';
-import { isDynamicallyDescribed } from '../../interfaces/dynamic-description.interface';
 import { isConditionallyListed } from '../../interfaces/conditional-listing.interface';
+import {
+  TOOL_LISTING_RECORDER,
+  type IToolListingRecorder,
+} from '../../interfaces/tool-listing-recorder.interface';
+import { ToolCatalogService } from '../tool-catalog.service';
+import { callerAgentId } from '../../tooling';
 
 @Injectable({ scope: Scope.REQUEST })
 export class McpToolsHandler extends McpHandlerBase {
+  private readonly catalog: ToolCatalogService;
+
   constructor(moduleRef: ModuleRef, registry: McpRegistryService) {
     super(moduleRef, registry, McpToolsHandler.name);
+    // Constructed rather than injected: the executor builds this handler by
+    // hand, and the service is stateless over the same two dependencies.
+    this.catalog = new ToolCatalogService(moduleRef, registry);
   }
 
-  private convertZodToJsonSchema(parameters: any): any {
+  /**
+   * Fire-and-forget. Only agent runtimes are recorded (a person listing
+   * through the console has no pod), and neither a missing recorder nor a
+   * failed write may touch the listing itself.
+   */
+  private recordListing(httpRequest: Request, toolNames: string[]): void {
+    const agentId = callerAgentId(httpRequest);
+    if (!agentId) return;
+    let recorder: IToolListingRecorder | undefined;
     try {
-      return zodToJsonSchema(parameters);
+      recorder = this.moduleRef.get<IToolListingRecorder>(
+        TOOL_LISTING_RECORDER,
+        { strict: false },
+      );
     } catch {
-      return undefined;
+      return;
     }
+    if (!recorder || typeof recorder.record !== 'function') return;
+    void Promise.resolve()
+      .then(() => recorder.record(agentId, toolNames))
+      .catch((e: unknown) => {
+        this.logger.warn(
+          `tool listing snapshot failed for agent ${agentId}: ${
+            e instanceof Error ? e.message : String(e)
+          }`,
+        );
+      });
   }
 
   registerHandlers(mcpServer: McpServer, httpRequest: Request) {
     mcpServer.server.setRequestHandler(ListToolsRequestSchema, async () => {
-      const contextId = ContextIdFactory.getByRequest(httpRequest);
-      this.moduleRef.registerRequestByContextId(httpRequest, contextId);
+      // The per-caller list (conditional listing, dynamic descriptions) is
+      // computed by ToolCatalogService so the console's catalogue endpoint
+      // and this handler can never disagree (CLEAN-109).
+      const listed = await this.catalog.listFor(httpRequest);
 
-      const listed = await Promise.all(
-        this.registry.getTools().map(async (tool) => {
-          let description = tool.metadata.description;
-          // Tools may opt into per-caller descriptions by implementing
-          // IDynamicallyDescribedTool, and out of the list entirely by
-          // implementing IConditionallyListedTool. Failure to resolve,
-          // describe or decide falls back to listing the tool with its
-          // static decorator description, so a broken tool can't hide
-          // itself or the rest of the list.
-          try {
-            const instance = await this.moduleRef.resolve(
-              tool.providerClass,
-              contextId,
-              { strict: false },
-            );
-            if (isConditionallyListed(instance)) {
-              const listedForCaller =
-                await instance.isListedForRequest(httpRequest);
-              if (!listedForCaller) return null;
-            }
-            if (isDynamicallyDescribed(instance)) {
-              const dyn = await instance.describeForRequest(httpRequest);
-              if (typeof dyn === 'string' && dyn.length > 0) {
-                description = dyn;
-              }
-            }
-          } catch (e) {
-            this.logger.debug(
-              `tools/list hooks failed for ${tool.metadata.name}: ${
-                e instanceof Error ? e.message : String(e)
-              }`,
-            );
-          }
-          return {
-            name: tool.metadata.name,
-            description,
-            inputSchema: tool.metadata.parameters
-              ? this.convertZodToJsonSchema(tool.metadata.parameters)
-              : undefined,
-          };
-        }),
-      );
+      // A pod lists once at boot: what it was told here is what it believes
+      // it has. Hand the names to the recorder, if one is wired, so the
+      // console can later tell a tool the pod has from one it lacks.
+      this.recordListing(httpRequest, listed.map((t) => t.name));
 
       return {
-        tools: listed.filter((tool) => tool !== null),
+        tools: listed.map((tool) => ({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+        })),
       };
     });
 
diff --git a/api/src/slices/mcp/services/mcp-registry.service.spec.ts b/api/src/slices/mcp/services/mcp-registry.service.spec.ts
index 75fb27e3..7482f0f5 100644
--- a/api/src/slices/mcp/services/mcp-registry.service.spec.ts
+++ b/api/src/slices/mcp/services/mcp-registry.service.spec.ts
@@ -1,6 +1,7 @@
 import { Test, TestingModule } from '@nestjs/testing';
 import { McpRegistryService } from './mcp-registry.service';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { z } from 'zod';
 
 describe('McpRegistryService', () => {
   let service: McpRegistryService;
@@ -64,4 +65,99 @@ describe('McpRegistryService', () => {
     expect(result?.resource.metadata.name).toBe('res3');
     expect(result?.params).toEqual({});
   });
+
+  /**
+   * CLEAN-109: a tool the Tools panel cannot show must not boot. Each case
+   * removes one required field from an otherwise complete tool and expects
+   * the bootstrap to name the tool and the field.
+   */
+  describe('tool metadata validation', () => {
+    const complete = () => ({
+      name: 'register_thing',
+      description: 'Register a thing.',
+      topic: 'mcp_servers',
+      title: 'Register a thing',
+      template: 'Register the thing «name»',
+      parameters: z.object({ name: z.string() }),
+    });
+
+    const withTools = (...metas: object[]) => {
+      (service as any).discoveredTools = metas.map((metadata, i) => ({
+        type: 'tool',
+        metadata,
+        providerClass: Symbol(`tool${i}`),
+        methodName: 'run',
+      }));
+    };
+
+    it('accepts a complete tool', () => {
+      withTools(complete());
+      expect(() => service.validateToolMetadata()).not.toThrow();
+    });
+
+    it.each([
+      ['topic', { topic: 'nope' }, 'unknown topic'],
+      ['title', { title: '' }, 'missing title'],
+      ['template', { template: '  ' }, 'missing template'],
+      ['long title', { title: 'x'.repeat(61) }, 'title longer'],
+      ['long template', { template: '«' + 'x'.repeat(200) }, 'template longer'],
+      [
+        'placeholder',
+        { template: 'Register the thing' },
+        'template has parameters but no «…» placeholder',
+      ],
+    ])('refuses a tool with a bad %s', (_label, patch, expected) => {
+      withTools({ ...complete(), ...patch });
+      expect(() => service.validateToolMetadata()).toThrow(
+        expect.objectContaining({
+          message: expect.stringContaining(`register_thing: ${expected}`),
+        }),
+      );
+    });
+
+    it('allows a template without placeholders when the tool takes no parameters', () => {
+      withTools({
+        ...complete(),
+        template: 'List every thing',
+        parameters: z.object({}),
+      });
+      expect(() => service.validateToolMetadata()).not.toThrow();
+    });
+
+    it('refuses a destructive tool without a boolean confirm parameter', () => {
+      withTools({ ...complete(), destructive: true });
+      expect(() => service.validateToolMetadata()).toThrow(
+        /register_thing: destructive tool without a boolean `confirm`/,
+      );
+      withTools({
+        ...complete(),
+        destructive: true,
+        parameters: z.object({ name: z.string(), confirm: z.string() }),
+      });
+      expect(() => service.validateToolMetadata()).toThrow(/confirm/);
+      withTools({
+        ...complete(),
+        destructive: true,
+        parameters: z.object({ name: z.string(), confirm: z.boolean() }),
+      });
+      expect(() => service.validateToolMetadata()).not.toThrow();
+    });
+
+    it('refuses duplicate tool names', () => {
+      withTools(complete(), complete());
+      expect(() => service.validateToolMetadata()).toThrow(/duplicate tool name/);
+    });
+
+    it('lists every problem in one error', () => {
+      withTools({ ...complete(), title: '', template: '' });
+      let message = '';
+      try {
+        service.validateToolMetadata();
+      } catch (e) {
+        message = (e as Error).message;
+      }
+      expect(message).toContain('register_thing: missing title');
+      expect(message).toContain('register_thing: missing template');
+    });
+  });
 });
diff --git a/api/src/slices/mcp/services/mcp-registry.service.ts b/api/src/slices/mcp/services/mcp-registry.service.ts
index e69d1b9c..0b9f67aa 100644
--- a/api/src/slices/mcp/services/mcp-registry.service.ts
+++ b/api/src/slices/mcp/services/mcp-registry.service.ts
@@ -9,11 +9,69 @@ import {
   MCP_RESOURCE_METADATA_KEY,
   MCP_TOOL_METADATA_KEY,
   ToolMetadata,
+  isToolTopic,
 } from '../decorators';
 import { ResourceMetadata } from '../decorators/resource.decorator';
 import { match } from 'path-to-regexp';
 import { PromptMetadata } from '../decorators/prompt.decorator';
 import { Logger } from '@nestjs/common';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+export const TOOL_TITLE_MAX = 60;
+export const TOOL_TEMPLATE_MAX = 200;
+
+/**
+ * The panel contract every tool must satisfy (CLEAN-109). Returns the
+ * problems found, empty when the metadata is complete. Exported so a spec
+ * can exercise it without booting a module.
+ */
+export function toolMetadataProblems(metadata: Partial<ToolMetadata>): string[] {
+  const problems: string[] = [];
+  const name = metadata.name ?? '<unnamed>';
+  if (!metadata.name) problems.push('missing name');
+  if (!isToolTopic(metadata.topic)) {
+    problems.push(`unknown topic "${String(metadata.topic)}"`);
+  }
+  const title = (metadata.title ?? '').trim();
+  if (!title) problems.push('missing title');
+  else if (title.length > TOOL_TITLE_MAX) {
+    problems.push(`title longer than ${TOOL_TITLE_MAX} chars`);
+  }
+  const template = (metadata.template ?? '').trim();
+  if (!template) problems.push('missing template');
+  else if (template.length > TOOL_TEMPLATE_MAX) {
+    problems.push(`template longer than ${TOOL_TEMPLATE_MAX} chars`);
+  }
+
+  let properties: Record<string, unknown> = {};
+  let required: string[] = [];
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const params = metadata.parameters as any;
+    const schema = (params ? zodToJsonSchema(params) : {}) as unknown as {
+      properties?: Record<string, unknown>;
+      required?: string[];
+    };
+    properties = schema.properties ?? {};
+    required = schema.required ?? [];
+  } catch {
+    problems.push('parameters cannot be converted to JSON schema');
+  }
+  // A template needs a «…» only when the person must supply something: a
+  // required parameter other than `confirm` (which the model sets, not the
+  // person). Optional filters ("List the knowledge bases") need none.
+  const needsPlaceholder = required.some((k) => k !== 'confirm');
+  if (template && needsPlaceholder && !template.includes('«')) {
+    problems.push('template has parameters but no «…» placeholder');
+  }
+  if (metadata.destructive) {
+    const confirm = properties.confirm as { type?: unknown } | undefined;
+    if (!confirm || confirm.type !== 'boolean') {
+      problems.push('destructive tool without a boolean `confirm` parameter');
+    }
+  }
+  return problems.map((p) => `${name}: ${p}`);
+}
 
 /**
  * Interface representing a discovered tool
@@ -40,6 +98,30 @@ export class McpRegistryService implements OnApplicationBootstrap {
 
   onApplicationBootstrap() {
     this.discoverTools();
+    this.validateToolMetadata();
+  }
+
+  /**
+   * A tool the Tools panel cannot show is a tool the person never finds, so
+   * the API refuses to start with one (CLEAN-109, FR-005). Names must also be
+   * unique: `findTool` would silently serve the first of two.
+   */
+  validateToolMetadata(): void {
+    const tools = this.getTools();
+    const problems = tools.flatMap((t) => toolMetadataProblems(t.metadata));
+    const seen = new Set<string>();
+    for (const t of tools) {
+      const name = t.metadata?.name;
+      if (!name) continue;
+      if (seen.has(name)) problems.push(`${name}: duplicate tool name`);
+      seen.add(name);
+    }
+    if (problems.length) {
+      throw new Error(
+        `MCP tool metadata is incomplete — every @Tool needs topic, title and template, and a destructive tool needs a boolean confirm parameter:\n  - ${problems.join('\n  - ')}`,
+      );
+    }
+    this.logger.log(`Validated ${tools.length} MCP tools`);
   }
 
   /**
diff --git a/api/src/slices/mcp/services/tool-catalog.service.spec.ts b/api/src/slices/mcp/services/tool-catalog.service.spec.ts
new file mode 100644
index 00000000..866d9398
--- /dev/null
+++ b/api/src/slices/mcp/services/tool-catalog.service.spec.ts
@@ -0,0 +1,97 @@
+import { ModuleRef } from '@nestjs/core';
+import { Request } from 'express';
+import { z } from 'zod';
+import { ToolCatalogService } from './tool-catalog.service';
+import { McpRegistryService } from '../services/mcp-registry.service';
+
+interface FakeTool {
+  name: string;
+  instance: Record<string, unknown>;
+  resolveThrows?: boolean;
+}
+
+function makeHarness(tools: FakeTool[]) {
+  const discovered = tools.map((t) => ({
+    type: 'tool' as const,
+    metadata: {
+      name: t.name,
+      description: `static description of ${t.name}`,
+      parameters: z.object({ id: z.string() }),
+      topic: 'agents',
+      title: t.name,
+      template: `Do «${t.name}»`,
+    },
+    providerClass: t.name as unknown as symbol,
+    methodName: 'run',
+  }));
+  const registry = { getTools: () => discovered } as unknown as McpRegistryService;
+  const moduleRef = {
+    registerRequestByContextId: jest.fn(),
+    resolve: jest.fn(async (token: unknown) => {
+      const tool = tools.find((t) => t.name === token);
+      if (!tool) throw new Error(`no provider for ${String(token)}`);
+      if (tool.resolveThrows) throw new Error('resolve blew up');
+      return tool.instance;
+    }),
+  } as unknown as ModuleRef;
+  return { service: new ToolCatalogService(moduleRef, registry), moduleRef };
+}
+
+const operator = () =>
+  ({ user: { sub: 'agent:admin', roles: ['owner'] } }) as unknown as Request;
+const plain = () =>
+  ({ user: { sub: 'agent:a1', roles: ['agent'] } }) as unknown as Request;
+
+describe('ToolCatalogService.listFor', () => {
+  it('lists a tool with no opinion, with its static description, schema and metadata', async () => {
+    const { service } = makeHarness([{ name: 'plain', instance: { run: jest.fn() } }]);
+    const result = await service.listFor(plain());
+    expect(result).toHaveLength(1);
+    expect(result[0].name).toBe('plain');
+    expect(result[0].description).toBe('static description of plain');
+    expect(result[0].inputSchema).toMatchObject({ type: 'object' });
+    expect(result[0].metadata.template).toBe('Do «plain»');
+  });
+
+  it('omits a tool whose listing hook says no and asks it with the request', async () => {
+    const isListedForRequest = jest.fn(async (req: Request) =>
+      (req as unknown as { user: { roles: string[] } }).user.roles.includes('owner'),
+    );
+    const { service } = makeHarness([
+      { name: 'delete_user', instance: { run: jest.fn(), isListedForRequest } },
+    ]);
+    expect(await service.listFor(plain())).toHaveLength(0);
+    expect(await service.listFor(operator())).toHaveLength(1);
+    expect(isListedForRequest).toHaveBeenCalledTimes(2);
+  });
+
+  it('applies a dynamic description when one is given', async () => {
+    const { service } = makeHarness([
+      {
+        name: 'query_knowledge',
+        instance: {
+          run: jest.fn(),
+          describeForRequest: jest.fn(async () => 'bases: «Docs»'),
+        },
+      },
+    ]);
+    const [tool] = await service.listFor(plain());
+    expect(tool.description).toBe('bases: «Docs»');
+  });
+
+  it('keeps a tool listed when its hooks or resolution throw', async () => {
+    const { service } = makeHarness([
+      { name: 'broken', instance: {}, resolveThrows: true },
+      {
+        name: 'throwing',
+        instance: {
+          isListedForRequest: jest.fn(async () => {
+            throw new Error('nope');
+          }),
+        },
+      },
+    ]);
+    const result = await service.listFor(plain());
+    expect(result.map((t) => t.name)).toEqual(['broken', 'throwing']);
+  });
+});
diff --git a/api/src/slices/mcp/services/tool-catalog.service.ts b/api/src/slices/mcp/services/tool-catalog.service.ts
new file mode 100644
index 00000000..439b82fd
--- /dev/null
+++ b/api/src/slices/mcp/services/tool-catalog.service.ts
@@ -0,0 +1,93 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ContextIdFactory, ModuleRef } from '@nestjs/core';
+import type { Request } from 'express';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { McpRegistryService } from './mcp-registry.service';
+import { isDynamicallyDescribed } from '../interfaces/dynamic-description.interface';
+import { isConditionallyListed } from '../interfaces/conditional-listing.interface';
+import type { ToolMetadata } from '../decorators';
+
+/** One tool as a given caller sees it: the per-caller description applied. */
+export interface IListedTool {
+  name: string;
+  description: string;
+  inputSchema: unknown;
+  metadata: ToolMetadata;
+}
+
+/**
+ * "Which tools does this caller see, described how?" — the single answer for
+ * MCP tools/list (a real request from a pod) and for the console's catalogue
+ * (a synthetic request carrying the principal a pod would have). One
+ * implementation, so the panel can never disagree with the runtime
+ * (CLEAN-109, research R3).
+ */
+@Injectable()
+export class ToolCatalogService {
+  private readonly logger = new Logger(ToolCatalogService.name);
+
+  constructor(
+    private readonly moduleRef: ModuleRef,
+    private readonly registry: McpRegistryService,
+  ) {}
+
+  async listFor(httpRequest: Request): Promise<IListedTool[]> {
+    const contextId = ContextIdFactory.getByRequest(httpRequest);
+    this.moduleRef.registerRequestByContextId(httpRequest, contextId);
+
+    const listed = await Promise.all(
+      this.registry.getTools().map(async (tool): Promise<IListedTool | null> => {
+        let description = tool.metadata.description;
+        // Tools may opt into per-caller descriptions by implementing
+        // IDynamicallyDescribedTool, and out of the list entirely by
+        // implementing IConditionallyListedTool. Failure to resolve,
+        // describe or decide falls back to listing the tool with its
+        // static decorator description, so a broken tool can't hide
+        // itself or the rest of the list.
+        try {
+          const instance = await this.moduleRef.resolve(
+            tool.providerClass,
+            contextId,
+            { strict: false },
+          );
+          if (isConditionallyListed(instance)) {
+            const listedForCaller =
+              await instance.isListedForRequest(httpRequest);
+            if (!listedForCaller) return null;
+          }
+          if (isDynamicallyDescribed(instance)) {
+            const dyn = await instance.describeForRequest(httpRequest);
+            if (typeof dyn === 'string' && dyn.length > 0) {
+              description = dyn;
+            }
+          }
+        } catch (e) {
+          this.logger.debug(
+            `tools/list hooks failed for ${tool.metadata.name}: ${
+              e instanceof Error ? e.message : String(e)
+            }`,
+          );
+        }
+        return {
+          name: tool.metadata.name,
+          description,
+          inputSchema: tool.metadata.parameters
+            ? this.convertZodToJsonSchema(tool.metadata.parameters)
+            : undefined,
+          metadata: tool.metadata,
+        };
+      }),
+    );
+
+    return listed.filter((tool): tool is IListedTool => tool !== null);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private convertZodToJsonSchema(parameters: any): unknown {
+    try {
+      return zodToJsonSchema(parameters);
+    } catch {
+      return undefined;
+    }
+  }
+}
diff --git a/api/src/slices/mcp/tool-metadata.spec.ts b/api/src/slices/mcp/tool-metadata.spec.ts
new file mode 100644
index 00000000..68566dd7
--- /dev/null
+++ b/api/src/slices/mcp/tool-metadata.spec.ts
@@ -0,0 +1,133 @@
+/**
+ * The boot check, without a database (CLEAN-109, FR-005): load every
+ * `*.tool.ts` under src/slices, read the @Tool metadata off each method the
+ * way McpRegistryService does, and run the same validation the API runs at
+ * bootstrap. A tool that would refuse to boot fails here first.
+ */
+import 'reflect-metadata';
+import { readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { MCP_TOOL_METADATA_KEY, type ToolMetadata } from './decorators';
+import { toolMetadataProblems } from './services/mcp-registry.service';
+import { TOOL_TOPIC_KEYS } from './decorators/topics';
+
+jest.mock('@kubernetes/client-node', () => ({
+  KubeConfig: class {
+    loadFromDefault() {}
+    loadFromCluster() {}
+    makeApiClient() {
+      return {};
+    }
+  },
+  CoreV1Api: class {},
+  CustomObjectsApi: class {},
+  Log: class {},
+  Watch: class {},
+}));
+
+const SLICES = join(__dirname, '..');
+
+function toolFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      if (entry === 'node_modules') continue;
+      out.push(...toolFiles(full));
+    } else if (entry.endsWith('.tool.ts')) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+interface Discovered {
+  file: string;
+  className: string;
+  method: string;
+  metadata: ToolMetadata;
+}
+
+const loadErrors: string[] = [];
+
+function discover(): Discovered[] {
+  const found: Discovered[] = [];
+  for (const file of toolFiles(SLICES)) {
+    let mod: Record<string, unknown>;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires
+      mod = require(file) as Record<string, unknown>;
+    } catch (e) {
+      loadErrors.push(
+        `${relative(SLICES, file)}: ${(e as Error).stack ?? String(e)}`,
+      );
+      continue;
+    }
+    for (const [className, exported] of Object.entries(mod)) {
+      if (typeof exported !== 'function' || !exported.prototype) continue;
+      const proto = exported.prototype as Record<string, unknown>;
+      for (const method of Object.getOwnPropertyNames(proto)) {
+        if (method === 'constructor') continue;
+        // Descriptors, not property reads: a getter on the prototype (LlmTool
+        // resolves a gateway lazily that way) must not run without `this`.
+        const descriptor = Object.getOwnPropertyDescriptor(proto, method);
+        const ref = descriptor?.value as unknown;
+        if (typeof ref !== 'function') continue;
+        const metadata = Reflect.getMetadata(MCP_TOOL_METADATA_KEY, ref) as
+          | ToolMetadata
+          | undefined;
+        if (metadata) {
+          found.push({
+            file: relative(SLICES, file),
+            className,
+            method,
+            metadata,
+          });
+        }
+      }
+    }
+  }
+  return found;
+}
+
+describe('every @Tool in the API satisfies the boot-time contract', () => {
+  const tools = discover();
+
+  it('loads every tool file', () => {
+    expect(loadErrors).toEqual([]);
+  });
+
+  it('finds the tool set (sanity: the audit expects well over a hundred)', () => {
+    expect(tools.length).toBeGreaterThan(100);
+  });
+
+  it('has no duplicate tool names', () => {
+    const names = tools.map((t) => t.metadata.name);
+    const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+    expect(dupes).toEqual([]);
+  });
+
+  it('every tool has a valid topic, title, template and confirm on destructive tools', () => {
+    const problems = tools.flatMap((t) =>
+      toolMetadataProblems(t.metadata).map(
+        (p) => `${t.file} ${t.className}.${t.method}: ${p}`,
+      ),
+    );
+    expect(problems).toEqual([]);
+  });
+
+  it('every topic in use is a known topic', () => {
+    const unknown = tools
+      .filter((t) => !(TOOL_TOPIC_KEYS as string[]).includes(t.metadata.topic))
+      .map((t) => `${t.metadata.name}: ${String(t.metadata.topic)}`);
+    expect(unknown).toEqual([]);
+  });
+
+  it('destructive tools end their description with the confirmation sentence', () => {
+    const missing = tools
+      .filter((t) => t.metadata.destructive)
+      .filter((t) => !/confirm: true/.test(t.metadata.description))
+      .map((t) => t.metadata.name);
+    expect(missing).toEqual([]);
+  });
+});
diff --git a/api/src/slices/mcp/tool-secrets.spec.ts b/api/src/slices/mcp/tool-secrets.spec.ts
new file mode 100644
index 00000000..f66c8cac
--- /dev/null
+++ b/api/src/slices/mcp/tool-secrets.spec.ts
@@ -0,0 +1,286 @@
+/**
+ * FR-004 (CLEAN-109): no tool result carries a secret. Every tool that takes
+ * or lists a credential is called with a sentinel in every secret-shaped
+ * position — as an argument AND as a field of every row the mocked gateways
+ * hand back — and the sentinel must not come out in the result text. The
+ * single exception is create_api_key, which returns the plaintext key once
+ * (research R6) and says so.
+ *
+ * The gateways are proxies that answer any method with a row (or a list of
+ * rows) full of secrets, so a tool that forgets to strip cannot pass by
+ * happening to call a method the harness did not anticipate.
+ */
+import type { Request } from 'express';
+import { UserRoleTypes } from '#/user/user/domain';
+import { LlmTool } from '#/llm/llm.tool';
+import { McpServerTool } from '#/mcpServer/mcpServer.tool';
+import { SecretTool } from '#/agent/secret/secret.tool';
+import { UserTool } from '#/user/user/user.tool';
+import { IntegrationTool } from '#/integration/integration.tool';
+import { ApiKeyTool, KEY_SHOWN_ONCE } from '#/user/apiKey/apiKey.tool';
+import { RancherTool } from '#/rancher/rancher.tool';
+
+const SENTINEL = 'SENTINEL-SECRET-7f3a';
+
+const row = () => ({
+  id: 'row-1',
+  agentId: 'agent-1',
+  name: 'Row',
+  title: 'Row',
+  email: 'row@example.com',
+  provider: 'anthropic',
+  model: 'claude',
+  url: 'https://example.com/mcp',
+  transport: 'streamableHttp',
+  authType: 'bearer',
+  status: 'active',
+  role: 'user',
+  enabled: true,
+  builtIn: false,
+  templateIds: [],
+  scopes: [],
+  group: 'integrations',
+  valueType: 'string',
+  // every secret-shaped field the product has
+  apiKey: SENTINEL,
+  authValue: SENTINEL,
+  oauthClientId: SENTINEL,
+  password: SENTINEL,
+  passwordHash: SENTINEL,
+  secret: SENTINEL,
+  token: SENTINEL,
+  cookies: SENTINEL,
+  keyHash: SENTINEL,
+  createdAt: new Date('2026-09-22T00:00:00Z'),
+  updatedAt: new Date('2026-09-22T00:00:00Z'),
+});
+
+const LIST_LIKE =
+  /^(findAll|findMany|list|findRecent|findByGroup|findDependent|findByTemplate|findExisting|findForAgent|getAll)/;
+
+/** A gateway that answers anything with secret-laden rows. */
+function leakyGateway(overrides: Record<string, unknown> = {}) {
+  const calls: Record<string, jest.Mock> = {};
+  return new Proxy(overrides, {
+    get(target, prop: string) {
+      if (prop in target) return target[prop];
+      if (prop === 'then') return undefined;
+      if (!calls[prop]) {
+        calls[prop] = jest.fn(async () =>
+          LIST_LIKE.test(prop) ? [row(), row()] : row(),
+        );
+      }
+      return calls[prop];
+    },
+  });
+}
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({ user: { sub: 'agent:admin', email: '', roles } }) as unknown as Request;
+const operator = () => request([UserRoleTypes.Owner]);
+
+/** Every plausible argument name, secrets everywhere they could go. */
+const args = {
+  id: 'row-1',
+  agentId: 'agent-1',
+  userId: 'agent:admin',
+  serverId: 'row-1',
+  name: 'Row',
+  key: 'API_KEY',
+  value: SENTINEL,
+  apiKey: SENTINEL,
+  authValue: SENTINEL,
+  password: SENTINEL,
+  secret: SENTINEL,
+  token: SENTINEL,
+  store: { API_KEY: SENTINEL },
+  provider: 'anthropic',
+  model: 'claude',
+  url: 'https://example.com/mcp',
+  transport: 'streamableHttp' as const,
+  authType: 'bearer' as const,
+  email: 'row@example.com',
+  role: 'user',
+  service: 'github',
+  accountKey: 'main',
+  label: 'Main',
+  confirm: true,
+};
+
+type Result = { content: { text: string }[]; isError?: boolean };
+const textOf = (r: Result) => r.content.map((c) => c.text).join('\n');
+
+/** The JSON paths at which the sentinel sits — the failure message names them. */
+function leakPaths(text: string): string[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return text.includes(SENTINEL) ? ['<text>'] : [];
+  }
+  const out: string[] = [];
+  const walk = (v: unknown, path: string) => {
+    if (v === SENTINEL) out.push(path || '<root>');
+    else if (Array.isArray(v)) v.forEach((x, i) => walk(x, `${path}[${i}]`));
+    else if (v && typeof v === 'object') {
+      for (const [k, x] of Object.entries(v))
+        walk(x, path ? `${path}.${k}` : k);
+    } else if (typeof v === 'string' && v.includes(SENTINEL))
+      out.push(`${path}(substring)`);
+  };
+  walk(parsed, '');
+  return out;
+}
+
+interface Case {
+  name: string;
+  run: () => Promise<Result>;
+}
+
+function cases(): Case[] {
+  const llm = new LlmTool(
+    leakyGateway() as never,
+    leakyGateway({
+      check: jest.fn(async () => ({ ok: false, error: `bad key ${SENTINEL}` })),
+    }) as never,
+    { get: () => leakyGateway() } as never,
+  );
+  const mcp = new McpServerTool(leakyGateway() as never);
+  const secret = new SecretTool(
+    leakyGateway() as never,
+    leakyGateway({
+      list: jest.fn(async () => [{ name: 'API_KEY', value: SENTINEL }]),
+      set: jest.fn(async () => undefined),
+      replaceAll: jest.fn(async () => undefined),
+      delete: jest.fn(async () => undefined),
+    }) as never,
+  );
+  const user = new UserTool(leakyGateway() as never);
+  const integration = new IntegrationTool(leakyGateway() as never);
+  const apiKey = new ApiKeyTool(
+    leakyGateway() as never,
+    leakyGateway() as never,
+  );
+  const rancher = new RancherTool(
+    leakyGateway() as never,
+    leakyGateway() as never,
+    leakyGateway() as never,
+    leakyGateway() as never,
+    leakyGateway() as never,
+    leakyGateway() as never,
+    leakyGateway({
+      findAll: jest.fn(async () => [
+        {
+          group: 'integrations',
+          name: 'bridle_api_key',
+          value: SENTINEL,
+          valueType: 'string',
+        },
+        {
+          group: 'integrations',
+          name: 'ranch_api_url',
+          value: 'https://api',
+          valueType: 'string',
+        },
+      ]),
+      findByGroup: jest.fn(async () => [
+        {
+          group: 'integrations',
+          name: 'bridle_api_key',
+          value: SENTINEL,
+          valueType: 'string',
+        },
+      ]),
+    }) as never,
+    leakyGateway() as never,
+    leakyGateway() as never,
+    leakyGateway() as never,
+  );
+
+  const call = (fn: (...a: never[]) => Promise<unknown>) => () =>
+    fn(args as never, null as never, operator() as never) as Promise<Result>;
+
+  return [
+    { name: 'get_llm', run: call(llm.getLlm.bind(llm)) },
+    { name: 'create_llm', run: call(llm.createLlm.bind(llm)) },
+    { name: 'update_llm', run: call(llm.updateLlm.bind(llm)) },
+    { name: 'health_check_llm', run: call(llm.healthCheckLlm.bind(llm)) },
+    { name: 'llm_usage', run: call(llm.llmUsage.bind(llm)) },
+    { name: 'list_llms', run: call(rancher.listLlms.bind(rancher)) },
+    { name: 'list_mcp_servers', run: call(mcp.listMcpServers.bind(mcp)) },
+    { name: 'get_mcp_server', run: call(mcp.getMcpServer.bind(mcp)) },
+    { name: 'register_mcp_server', run: call(mcp.registerMcpServer.bind(mcp)) },
+    { name: 'update_mcp_server', run: call(mcp.updateMcpServer.bind(mcp)) },
+    {
+      name: 'list_agent_secrets',
+      run: call(secret.listAgentSecrets.bind(secret)),
+    },
+    { name: 'set_agent_secret', run: call(secret.setAgentSecret.bind(secret)) },
+    {
+      name: 'replace_agent_secrets',
+      run: call(secret.replaceAgentSecrets.bind(secret)),
+    },
+    { name: 'list_users', run: call(user.listUsers.bind(user)) },
+    { name: 'get_user', run: call(user.getUser.bind(user)) },
+    { name: 'create_user', run: call(user.createUser.bind(user)) },
+    { name: 'update_user', run: call(user.updateUser.bind(user)) },
+    {
+      name: 'list_integration_accounts',
+      run: call(integration.listIntegrationAccounts.bind(integration)),
+    },
+    {
+      name: 'create_integration_account',
+      run: call(integration.createIntegrationAccount.bind(integration)),
+    },
+    { name: 'list_api_keys', run: call(apiKey.listApiKeys.bind(apiKey)) },
+    { name: 'list_settings', run: call(rancher.listSettings.bind(rancher)) },
+  ];
+}
+
+describe('tool results never carry a secret (FR-004)', () => {
+  for (const c of cases()) {
+    it(`${c.name} keeps the sentinel out of its result`, async () => {
+      let result: Result;
+      try {
+        result = await c.run();
+      } catch (e) {
+        // A refusal thrown as an exception carries no row, so it cannot leak;
+        // but a thrown error message must not carry the sentinel either.
+        expect(String((e as Error).message)).not.toContain(SENTINEL);
+        return;
+      }
+      expect(leakPaths(textOf(result))).toEqual([]);
+    });
+  }
+
+  it('create_api_key is the one tool that returns a key, once, and says so', async () => {
+    const apiKey = new ApiKeyTool(
+      leakyGateway() as never,
+      leakyGateway({
+        create: jest.fn(async () => ({
+          apiKey: {
+            id: 'k-1',
+            name: 'ci',
+            prefix: 'rk_ab',
+            scopes: [],
+            keyHash: SENTINEL,
+            createdBy: 'agent:admin',
+            createdAt: new Date('2026-09-22T00:00:00Z'),
+            lastUsedAt: null,
+            expiresAt: null,
+          },
+          key: 'rk_ab_PLAINTEXT_ONCE',
+        })),
+      }) as never,
+    );
+    const text = textOf(
+      (await apiKey.createApiKey(
+        { name: 'ci', scopes: [] } as never,
+        null as never,
+        operator() as never,
+      )) as Result,
+    );
+    expect(text).toContain('rk_ab_PLAINTEXT_ONCE');
+    expect(text).toContain(KEY_SHOWN_ONCE);
+  });
+});
diff --git a/api/src/slices/mcp/tooling.spec.ts b/api/src/slices/mcp/tooling.spec.ts
new file mode 100644
index 00000000..7d4c60fa
--- /dev/null
+++ b/api/src/slices/mcp/tooling.spec.ts
@@ -0,0 +1,90 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import {
+  callerAgentId,
+  callerIsOperator,
+  confirmed,
+  err,
+  ok,
+  requireAgent,
+  requireOperator,
+  stripSecrets,
+} from './tooling';
+import { UserRoleTypes } from '#/user/user/domain';
+
+const request = (sub: string, roles: UserRoleTypes[]): Request =>
+  ({ user: { sub, email: '', roles } }) as unknown as Request;
+
+describe('tooling', () => {
+  it('ok wraps strings as-is and objects as pretty JSON', () => {
+    expect(ok('hi').content[0].text).toBe('hi');
+    expect(ok({ a: 1 }).content[0].text).toBe('{\n  "a": 1\n}');
+    expect(ok({}).isError).toBeUndefined();
+  });
+
+  it('err marks the result', () => {
+    expect(err('no')).toEqual({ content: [{ type: 'text', text: 'no' }], isError: true });
+  });
+
+  it('reads the caller agent id from agent tokens only', () => {
+    expect(callerAgentId(request('agent:a-1', [UserRoleTypes.Agent]))).toBe('a-1');
+    expect(callerAgentId(request('user-1', [UserRoleTypes.Owner]))).toBeNull();
+    expect(callerAgentId({} as Request)).toBeNull();
+  });
+
+  it('operator means the Owner role', () => {
+    expect(callerIsOperator(request('agent:admin', [UserRoleTypes.Owner]))).toBe(true);
+    expect(callerIsOperator(request('agent:a', [UserRoleTypes.Agent]))).toBe(false);
+  });
+
+  it('requireOperator accepts Owner and refuses Agent with the console hint', () => {
+    expect(() => requireOperator(request('agent:admin', [UserRoleTypes.Owner]))).not.toThrow();
+    expect(() => requireOperator(request('agent:a', [UserRoleTypes.Agent]))).toThrow(
+      ForbiddenException,
+    );
+    try {
+      requireOperator(request('agent:a', [UserRoleTypes.Agent]));
+    } catch (e) {
+      expect((e as Error).message).toContain('operator role');
+      expect((e as Error).message).toContain('console');
+    }
+  });
+
+  it('requireAgent returns the id for agents and refuses people', () => {
+    expect(requireAgent(request('agent:a-2', [UserRoleTypes.Agent]))).toBe('a-2');
+    expect(() => requireAgent(request('user-1', [UserRoleTypes.Owner]))).toThrow(
+      ForbiddenException,
+    );
+  });
+
+  it('confirmed refuses without confirm and names what would happen', () => {
+    const refusal = confirmed({}, 'delete agent «bot»');
+    expect(refusal?.isError).toBe(true);
+    expect(refusal?.content[0].text).toBe(
+      'This will delete agent «bot». Ask the person to confirm, then call again with confirm: true.',
+    );
+    expect(confirmed({ confirm: false }, 'x')).not.toBeNull();
+    expect(confirmed({ confirm: 'yes' }, 'x')).not.toBeNull();
+    expect(confirmed({ confirm: true }, 'x')).toBeNull();
+  });
+
+  it('stripSecrets removes credential fields recursively and keeps the rest', () => {
+    const input = {
+      id: '1',
+      apiKey: 'sk-secret',
+      nested: { authValue: 'bearer x', name: 'n', list: [{ token: 't', keep: 1 }] },
+      value: 'plain',
+      when: new Date('2026-09-22T00:00:00Z'),
+    };
+    const out = stripSecrets(input);
+    expect(out).toEqual({
+      id: '1',
+      nested: { name: 'n', list: [{ keep: 1 }] },
+      value: 'plain',
+      when: input.when,
+    });
+    expect(stripSecrets({ value: 'v', id: 1 }, ['value'])).toEqual({ id: 1 });
+    expect(stripSecrets('str')).toBe('str');
+    expect(stripSecrets(null)).toBeNull();
+  });
+});
diff --git a/api/src/slices/mcp/tooling.ts b/api/src/slices/mcp/tooling.ts
new file mode 100644
index 00000000..d04896fc
--- /dev/null
+++ b/api/src/slices/mcp/tooling.ts
@@ -0,0 +1,135 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import type { IAuthTokenPayload } from '#/user/auth/domain/auth.types';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Shared helpers for every `*.tool.ts` (CLEAN-109). One vocabulary for what a
+ * tool hands back, who is calling, and how a destructive tool asks for a
+ * confirmation it cannot see for itself. `agent/peer/toolSupport.ts` re-exports
+ * the shared part so the peer tools read exactly as before.
+ */
+
+/** What an MCP tool hands back. The shape the SDK expects, nothing more. */
+export interface ToolResult {
+  content: { type: 'text'; text: string }[];
+  isError?: boolean;
+}
+
+export const ok = (value: unknown): ToolResult => ({
+  content: [
+    {
+      type: 'text',
+      text: typeof value === 'string' ? value : JSON.stringify(value, null, 2),
+    },
+  ],
+});
+
+export const err = (text: string): ToolResult => ({
+  content: [{ type: 'text', text }],
+  isError: true,
+});
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** Agent service tokens carry `sub = agent:<id>`; anything else is not an agent. */
+export function callerAgentId(httpRequest: Request): string | null {
+  const user = (httpRequest as AuthedRequest).user;
+  const sub = user?.sub ?? '';
+  if (!sub.startsWith('agent:')) return null;
+  return sub.slice('agent:'.length);
+}
+
+/** Admin agents hold the Owner role; plain agents hold `Agent` (auth.service). */
+export function callerIsOperator(httpRequest: Request): boolean {
+  const user = (httpRequest as AuthedRequest).user;
+  return (user?.roles ?? []).includes(UserRoleTypes.Owner);
+}
+
+export const OPERATOR_REFUSAL =
+  'This tool requires the Ranch operator role. Ask the operator to do it ' +
+  'in the console, or through the Ranch admin agent.';
+
+/**
+ * Third lock for operator-only tools: the listing hook hides them and
+ * tools/call refuses a name that stopped applying, this refuses the body.
+ */
+export function requireOperator(httpRequest: Request): void {
+  if (!callerIsOperator(httpRequest)) {
+    throw new ForbiddenException(OPERATOR_REFUSAL);
+  }
+}
+
+export const AGENT_ONLY_REFUSAL =
+  'This tool can only be called by an agent runtime.';
+
+/** Self-service tools act for the calling agent; a person has no "self" here. */
+export function requireAgent(httpRequest: Request): string {
+  const agentId = callerAgentId(httpRequest);
+  if (!agentId) throw new ForbiddenException(AGENT_ONLY_REFUSAL);
+  return agentId;
+}
+
+export const CONFIRM_SENTENCE =
+  'Ask the person to confirm first; call only after they said yes, with confirm: true.';
+
+/**
+ * The API cannot see the chat, so a destructive tool proves the person agreed
+ * with a required `confirm: true`. Returns the refusal to hand back, or null
+ * when the call may proceed. `what` is what the tool is about to do, in the
+ * words the person would read: "delete agent «support-bot» and its workspace".
+ */
+export function confirmed(
+  args: { confirm?: unknown },
+  what: string,
+): ToolResult | null {
+  if (args.confirm === true) return null;
+  return err(
+    `This will ${what}. Ask the person to confirm, then call again with confirm: true.`,
+  );
+}
+
+const SECRET_KEYS = [
+  'apiKey',
+  'authValue',
+  'oauthClientId',
+  'clientSecret',
+  'password',
+  'passwordHash',
+  'secret',
+  'token',
+  'accessToken',
+  'refreshToken',
+  'keyHash',
+  'cookies',
+  'privateKey',
+  'value',
+] as const;
+
+const DEFAULT_SECRET_KEYS: readonly string[] = SECRET_KEYS.filter(
+  (k) => k !== 'value',
+);
+
+/**
+ * Strip secret-bearing fields from a value before it becomes tool output
+ * (FR-004). Recurses into arrays and plain objects. The default set (every
+ * name Ranch uses for a credential) is ALWAYS stripped; `extraKeys` adds
+ * more for a slice's own field names. `value` is only stripped when asked
+ * for, since most rows have an innocent `value`.
+ */
+export function stripSecrets<T>(input: T, extraKeys: readonly string[] = []): T {
+  const keys = new Set<string>([...DEFAULT_SECRET_KEYS, ...extraKeys]);
+  const walk = (v: unknown): unknown => {
+    if (Array.isArray(v)) return v.map(walk);
+    if (v && typeof v === 'object' && !(v instanceof Date)) {
+      const out: Record<string, unknown> = {};
+      for (const [key, val] of Object.entries(v as Record<string, unknown>)) {
+        if (keys.has(key)) continue;
+        out[key] = walk(val);
+      }
+      return out;
+    }
+    return v;
+  };
+  return walk(input) as T;
+}
diff --git a/api/src/slices/mcpServer/mcpServer.module.ts b/api/src/slices/mcpServer/mcpServer.module.ts
index f543f1be..eb9fe1d8 100644
--- a/api/src/slices/mcpServer/mcpServer.module.ts
+++ b/api/src/slices/mcpServer/mcpServer.module.ts
@@ -1,5 +1,6 @@
 import { Module } from '@nestjs/common';
 import { McpServerController } from './mcpServer.controller';
+import { McpServerTool } from './mcpServer.tool';
 import { IMcpServerGateway } from './domain/mcpServer.gateway';
 import { McpServerSeeder } from './domain/mcpServer.seeder';
 import { AgentMcpResolver } from './domain/agentMcpResolver.service';
@@ -20,6 +21,9 @@ import { ConfigModule as KnowledgeConfigModule } from '#/reins/config/config.mod
     McpServerMapper,
     McpServerSeeder,
     AgentMcpResolver,
+    // The chat-side mirror of McpServerController (CLEAN-109). start_mcp_oauth
+    // lives in oauth/mcpOauth.tool.ts, because McpOauthModule imports this one.
+    McpServerTool,
     {
       provide: IMcpServerGateway,
       useClass: McpServerGateway,
diff --git a/api/src/slices/mcpServer/mcpServer.tool.spec.ts b/api/src/slices/mcpServer/mcpServer.tool.spec.ts
new file mode 100644
index 00000000..34f22eeb
--- /dev/null
+++ b/api/src/slices/mcpServer/mcpServer.tool.spec.ts
@@ -0,0 +1,295 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { McpServerTool } from './mcpServer.tool';
+import type { IMcpServerGateway } from './domain';
+import type { IMcpServerData } from './domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Two things matter more than the happy paths here: a plain agent cannot see
+ * or call these tools, and the bearer a person hands over to register a
+ * server never comes back out through any result (FR-004).
+ */
+const SENTINEL = 'SENTINEL-BEARER';
+
+const row = (overrides: Partial<IMcpServerData> = {}): IMcpServerData => ({
+  id: 'mcp-1',
+  name: 'Jira',
+  description: 'Tickets',
+  url: 'https://mcp.jira.test/mcp',
+  transport: 'streamableHttp',
+  authType: 'bearer',
+  authValue: SENTINEL,
+  oauthClientId: 'client-secret-id',
+  enabled: true,
+  builtIn: false,
+  templateIds: ['tpl-1'],
+  createdAt: new Date('2026-09-17T10:00:00.000Z'),
+  updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  ...overrides,
+});
+
+const builtIn = () =>
+  row({
+    id: 'mcp-ranch',
+    name: 'Ranch',
+    url: 'http://ranch-api/mcp',
+    authType: 'none',
+    authValue: null,
+    oauthClientId: null,
+    builtIn: true,
+    templateIds: [],
+  });
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: McpServerTool;
+  servers: jest.Mocked<
+    Pick<
+      IMcpServerGateway,
+      'findAll' | 'findById' | 'create' | 'update' | 'delete'
+    >
+  >;
+}
+
+function harness(): Harness {
+  const servers = {
+    findAll: jest.fn().mockResolvedValue([row(), builtIn()]),
+    findById: jest.fn().mockResolvedValue(row()),
+    create: jest.fn().mockResolvedValue(row()),
+    update: jest.fn().mockResolvedValue(row()),
+    delete: jest.fn().mockResolvedValue(undefined),
+  } as unknown as Harness['servers'];
+  const tool = new McpServerTool(servers as never);
+  return { tool, servers };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('McpServerTool — who may use it', () => {
+  it('hides the tools from a plain agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, servers } = harness();
+    await expect(
+      tool.listMcpServers({}, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(servers.findAll).not.toHaveBeenCalled();
+  });
+});
+
+describe('McpServerTool — reading', () => {
+  it('lists every server without its credential or OAuth client id', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.listMcpServers({}, null, operator()));
+    expect(text).toContain('"Jira"');
+    expect(text).toContain('"Ranch"');
+    expect(text).toContain('"authType": "bearer"');
+    expect(text).toContain('"builtIn": true');
+    expect(text).toContain('"tpl-1"');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('authValue');
+    expect(text).not.toContain('oauthClientId');
+  });
+
+  it('shows one server by id, stripped the same way', async () => {
+    const { tool, servers } = harness();
+    const text = textOf(
+      await tool.getMcpServer({ id: 'mcp-1' }, null, operator()),
+    );
+    expect(servers.findById).toHaveBeenCalledWith('mcp-1');
+    expect(text).toContain('https://mcp.jira.test/mcp');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('client-secret-id');
+  });
+
+  it('points a miss at list_mcp_servers', async () => {
+    const { tool, servers } = harness();
+    servers.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getMcpServer({ id: 'nope' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_mcp_servers');
+  });
+});
+
+describe('McpServerTool — registering', () => {
+  it('passes the fields to the gateway and acknowledges the credential without echoing it', async () => {
+    const { tool, servers } = harness();
+    const text = textOf(
+      await tool.registerMcpServer(
+        {
+          name: 'Jira',
+          url: 'https://mcp.jira.test/mcp',
+          authType: 'bearer',
+          authValue: SENTINEL,
+          transport: 'streamableHttp',
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(servers.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'Jira',
+        url: 'https://mcp.jira.test/mcp',
+        authType: 'bearer',
+        authValue: SENTINEL,
+        transport: 'streamableHttp',
+      }),
+    );
+    expect(text).toContain('"id": "mcp-1"');
+    expect(text).toContain('Credential stored');
+    expect(text).toContain('set_template_mcps');
+    expect(text).toContain('restart');
+    expect(text).not.toContain(SENTINEL);
+  });
+
+  it('tells the model each agent still has to connect when the server is oauth', async () => {
+    const { tool, servers } = harness();
+    servers.create.mockResolvedValue(
+      row({ authType: 'oauth', authValue: null }),
+    );
+    const text = textOf(
+      await tool.registerMcpServer(
+        { name: 'Jira', url: 'https://mcp.jira.test/mcp', authType: 'oauth' },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('start_mcp_oauth');
+    expect(text).toContain('No credential stored');
+  });
+});
+
+describe('McpServerTool — updating', () => {
+  it('sends only the fields given and never echoes a new credential', async () => {
+    const { tool, servers } = harness();
+    const text = textOf(
+      await tool.updateMcpServer(
+        { id: 'mcp-1', enabled: false, authValue: SENTINEL },
+        null,
+        operator(),
+      ),
+    );
+    expect(servers.update).toHaveBeenCalledWith('mcp-1', {
+      enabled: false,
+      authValue: SENTINEL,
+    });
+    expect(text).toContain('Credential replaced');
+    expect(text).toContain('restart_agent');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('ignored');
+  });
+
+  it('lets a built-in row change only enabled and description, and says what it dropped', async () => {
+    const { tool, servers } = harness();
+    servers.findById.mockResolvedValue(builtIn());
+    servers.update.mockResolvedValue(builtIn());
+    const text = textOf(
+      await tool.updateMcpServer(
+        {
+          id: 'mcp-ranch',
+          enabled: false,
+          description: 'Off for now',
+          url: 'https://evil.test',
+          authValue: SENTINEL,
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(servers.update).toHaveBeenCalledWith('mcp-ranch', {
+      enabled: false,
+      description: 'Off for now',
+    });
+    expect(text).toContain('built in');
+    expect(text).toContain('"url"');
+    expect(text).toContain('"authValue"');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('Credential replaced');
+  });
+
+  it('reports a missing server before touching the gateway', async () => {
+    const { tool, servers } = harness();
+    servers.findById.mockResolvedValue(null);
+    const text = textOf(
+      await tool.updateMcpServer(
+        { id: 'nope', enabled: false },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(servers.update).not.toHaveBeenCalled();
+  });
+});
+
+describe('McpServerTool — deleting', () => {
+  it('refuses without the confirmation argument and deletes nothing (CLEAN-109)', async () => {
+    const { tool, servers } = harness();
+    const result = await tool.deleteMcpServer(
+      { id: 'mcp-1' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('«Jira»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(servers.delete).not.toHaveBeenCalled();
+  });
+
+  it('deletes once confirmed and names the restart that makes it real', async () => {
+    const { tool, servers } = harness();
+    const text = textOf(
+      await tool.deleteMcpServer(
+        { id: 'mcp-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(servers.delete).toHaveBeenCalledWith('mcp-1');
+    expect(text).toContain('«Jira»');
+    expect(text).toContain('restart_agent');
+  });
+
+  it('refuses a built-in with the controller wording and the disabling move, even when confirmed', async () => {
+    const { tool, servers } = harness();
+    servers.findById.mockResolvedValue(builtIn());
+    const result = await tool.deleteMcpServer(
+      { id: 'mcp-ranch', confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Built-in MCP servers cannot be deleted');
+    expect(textOf(result)).toContain('update_mcp_server');
+    expect(servers.delete).not.toHaveBeenCalled();
+  });
+
+  it('reports a missing server before asking for confirmation', async () => {
+    const { tool, servers } = harness();
+    servers.findById.mockResolvedValue(null);
+    const result = await tool.deleteMcpServer({ id: 'nope' }, null, operator());
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(servers.delete).not.toHaveBeenCalled();
+  });
+});
diff --git a/api/src/slices/mcpServer/mcpServer.tool.ts b/api/src/slices/mcpServer/mcpServer.tool.ts
new file mode 100644
index 00000000..f757289f
--- /dev/null
+++ b/api/src/slices/mcpServer/mcpServer.tool.ts
@@ -0,0 +1,341 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  stripSecrets,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { IMcpServerGateway } from './domain';
+import type {
+  ICreateMcpServerData,
+  IMcpServerData,
+  IUpdateMcpServerData,
+} from './domain';
+import type { UpdateMcpServerDto } from './dtos';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+const TRANSPORTS = ['streamableHttp', 'sse'] as const;
+const AUTH_TYPES = ['none', 'bearer', 'header', 'oauth'] as const;
+
+/**
+ * What a row must never carry into a tool result: the bearer/header value and
+ * the OAuth client id the api registered for itself. `stripSecrets` knows
+ * `authValue`; `oauthClientId` is this slice's own, so it is named here.
+ */
+const HIDDEN_FIELDS = [
+  'authValue',
+  'oauthClientId',
+  'apiKey',
+  'password',
+  'passwordHash',
+  'secret',
+  'token',
+] as const;
+
+const NOT_FOUND = (id: string) =>
+  `MCP server ${id} not found — call list_mcp_servers to find the id`;
+
+/** The console's "attach it to a template" reminder, in one place. */
+const ATTACH_LINE =
+  'An MCP server only reaches agents through a template: attach it with ' +
+  'set_template_mcps, then restart_agent for every agent of that template.';
+
+/**
+ * The MCP server registry from the chat (CLEAN-109): what the console does
+ * under "MCP servers", mirrored one tool per endpoint of
+ * `McpServerController`. Every call goes through `IMcpServerGateway`, the
+ * same gateway the controller uses, and the two rules the controller holds
+ * are held here too: a built-in row (Ranch's own MCP) accepts only `enabled`
+ * and `description`, and is never deleted — only disabled.
+ *
+ * Credentials go one way. `register_mcp_server` and `update_mcp_server` take
+ * an `authValue`, store it, and acknowledge without echoing it; no result of
+ * these tools ever carries `authValue` or `oauthClientId` (FR-004).
+ *
+ * Operator-only: the Ranch admin agent holds the Owner role, a plain agent
+ * does not — for it these tools are not listed, and a call by name is
+ * refused.
+ */
+@Injectable()
+export class McpServerTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(McpServerTool.name);
+
+  constructor(private readonly servers: IMcpServerGateway) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  private present(server: IMcpServerData) {
+    return stripSecrets(server, HIDDEN_FIELDS);
+  }
+
+  // ─── Reading ─────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'list_mcp_servers',
+    topic: ToolTopics.McpServers,
+    title: 'List MCP servers',
+    template: 'List the MCP servers registered in this Ranch',
+    description:
+      'Every MCP server registered in this Ranch: id, name, url, transport, ' +
+      'auth type, whether it is enabled, whether it is built in (Ranch’s ' +
+      'own MCP), and the ids of the templates it is attached to. Credentials ' +
+      'are never returned. Use it to turn a name the person said into the id ' +
+      'the other mcp server tools need.',
+    parameters: z.object({}),
+  })
+  async listMcpServers(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const rows = await this.servers.findAll();
+    return ok(rows.map((row) => this.present(row)));
+  }
+
+  @Tool({
+    name: 'get_mcp_server',
+    topic: ToolTopics.McpServers,
+    title: 'Show an MCP server',
+    template: 'Show the MCP server «name»',
+    description:
+      'One MCP server by id, with its url, transport, auth type, enabled ' +
+      'flag, built-in flag and the templates it is attached to. The stored ' +
+      'credential is never returned — only its type. Find the id with ' +
+      'list_mcp_servers.',
+    parameters: z.object({
+      id: z.string().describe('MCP server id (list_mcp_servers has them)'),
+    }),
+  })
+  async getMcpServer(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const server = await this.servers.findById(id);
+    if (!server) return ok({ error: NOT_FOUND(id) });
+    return ok(this.present(server));
+  }
+
+  // ─── Changing ────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'register_mcp_server',
+    topic: ToolTopics.McpServers,
+    title: 'Register an MCP server',
+    template:
+      'Register the MCP server at «url» named «name» with «bearer|none» auth',
+    description:
+      'Register a new MCP server so templates can attach it. `authType` says ' +
+      'how the runtime authenticates: none, bearer (authValue is the token), ' +
+      'header (authValue is the full header value), or oauth (no authValue — ' +
+      'each agent connects through start_mcp_oauth). The credential is stored ' +
+      'and never read back. Registering alone changes nothing for agents: ' +
+      'attach the server to a template with set_template_mcps and restart ' +
+      'its agents.',
+    parameters: z.object({
+      name: z.string().max(80).describe('Display name, up to 80 characters'),
+      url: z.string().describe('The MCP endpoint URL'),
+      description: z.string().optional(),
+      transport: z
+        .enum(TRANSPORTS)
+        .optional()
+        .describe('streamableHttp (default) or sse'),
+      authType: z
+        .enum(AUTH_TYPES)
+        .optional()
+        .describe('none (default), bearer, header or oauth'),
+      authValue: z
+        .string()
+        .optional()
+        .describe(
+          'The bearer token or header value. Stored write-only, never returned.',
+        ),
+      enabled: z.boolean().optional().describe('Default true'),
+    }),
+  })
+  async registerMcpServer(
+    args: {
+      name: string;
+      url: string;
+      description?: string;
+      transport?: (typeof TRANSPORTS)[number];
+      authType?: (typeof AUTH_TYPES)[number];
+      authValue?: string;
+      enabled?: boolean;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const data: ICreateMcpServerData = {
+      name: args.name,
+      url: args.url,
+      description: args.description,
+      transport: args.transport,
+      authType: args.authType,
+      authValue: args.authValue,
+      enabled: args.enabled,
+    };
+    const server = await this.servers.create(data);
+    this.logger.log(
+      `MCP server registered through MCP: id=${server.id} authType=${server.authType}`,
+    );
+    return ok({
+      server: this.present(server),
+      credential: args.authValue
+        ? 'Credential stored; it is never returned by these tools.'
+        : 'No credential stored.',
+      next:
+        server.authType === 'oauth'
+          ? `${ATTACH_LINE} Each agent then connects with start_mcp_oauth.`
+          : ATTACH_LINE,
+    });
+  }
+
+  @Tool({
+    name: 'update_mcp_server',
+    topic: ToolTopics.McpServers,
+    title: 'Update or enable/disable a server',
+    template: 'Disable the MCP server «name»',
+    description:
+      'Change an MCP server: name, description, url, transport, auth type, ' +
+      'credential or the enabled flag. Pass only the fields to change. A ' +
+      'built-in server (Ranch’s own MCP) accepts only `enabled` and ' +
+      '`description`; the rest is ignored and the result says so. A new ' +
+      'authValue replaces the stored one and is never read back. Agents of ' +
+      'the templates it is attached to pick the change up on their next ' +
+      'restart.',
+    parameters: z.object({
+      id: z.string().describe('MCP server id (list_mcp_servers has them)'),
+      name: z.string().optional(),
+      description: z.string().optional(),
+      url: z.string().optional(),
+      transport: z.enum(TRANSPORTS).optional(),
+      authType: z.enum(AUTH_TYPES).optional(),
+      authValue: z
+        .string()
+        .optional()
+        .describe('Replaces the stored credential. Never returned.'),
+      enabled: z.boolean().optional(),
+    }),
+  })
+  async updateMcpServer(
+    args: { id: string } & UpdateMcpServerDto,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { id, ...dto } = args;
+    const existing = await this.servers.findById(id);
+    if (!existing) return ok({ error: NOT_FOUND(id) });
+
+    // Only the fields the caller actually sent, so an omitted `enabled`
+    // never becomes `enabled: undefined` in the gateway's update.
+    const requested = Object.fromEntries(
+      Object.entries(dto).filter(([, value]) => value !== undefined),
+    ) as IUpdateMcpServerData;
+
+    let data: IUpdateMcpServerData = requested;
+    let ignored: string[] = [];
+    if (existing.builtIn) {
+      // Same rule as McpServerController: built-ins (Ranch's own MCP) can be
+      // enabled/disabled but not edited — their url and auth model is owned
+      // by the api itself.
+      const allowed: IUpdateMcpServerData = {};
+      if (requested.enabled !== undefined) allowed.enabled = requested.enabled;
+      if (requested.description !== undefined) {
+        allowed.description = requested.description;
+      }
+      data = allowed;
+      ignored = Object.keys(requested).filter((key) => !(key in allowed));
+    }
+
+    const server = await this.servers.update(id, data);
+    this.logger.log(
+      `MCP server updated through MCP: id=${id} fields=${Object.keys(data).join(',')}`,
+    );
+    return ok({
+      server: this.present(server),
+      changed: Object.keys(data),
+      ...(ignored.length
+        ? {
+            ignored,
+            note:
+              `«${existing.name}» is built in: only enabled and description ` +
+              'can change; the other fields were ignored.',
+          }
+        : {}),
+      ...(requested.authValue !== undefined && data.authValue !== undefined
+        ? { credential: 'Credential replaced; it is never returned.' }
+        : {}),
+      next:
+        'Agents of the templates this server is attached to use the new ' +
+        'settings after restart_agent.',
+    });
+  }
+
+  @Tool({
+    name: 'delete_mcp_server',
+    topic: ToolTopics.McpServers,
+    title: 'Delete an MCP server',
+    template: 'Delete the MCP server «name»',
+    destructive: true,
+    description:
+      'Remove an MCP server from the registry, detaching it from every ' +
+      'template. Its stored credential is gone with it. A built-in server ' +
+      '(Ranch’s own MCP) cannot be deleted — disable it with ' +
+      'update_mcp_server instead. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string().describe('MCP server id (list_mcp_servers has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteMcpServer(
+    args: { id: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const existing = await this.servers.findById(args.id);
+    if (!existing) return ok({ error: NOT_FOUND(args.id) });
+    if (existing.builtIn) {
+      // The controller's exact wording, with the tool that does it here.
+      return err(
+        'Built-in MCP servers cannot be deleted — disable them via PATCH ' +
+          '/mcp-servers/:id { enabled: false } instead. From here: ' +
+          `update_mcp_server with id=${args.id}, enabled=false.`,
+      );
+    }
+    const refusal = confirmed(
+      args,
+      `delete the MCP server «${existing.name}» and detach it from ` +
+        `${existing.templateIds.length} template(s)`,
+    );
+    if (refusal) return refusal;
+
+    await this.servers.delete(args.id);
+    this.logger.log(`MCP server deleted through MCP: id=${args.id}`);
+    return ok(
+      `«${existing.name}» (${args.id}) deleted. Agents of the templates it ` +
+        'was attached to still hold it until they restart — restart_agent ' +
+        'when the person is ready.',
+    );
+  }
+}
diff --git a/api/src/slices/mcpServer/oauth/mcpOauth.module.ts b/api/src/slices/mcpServer/oauth/mcpOauth.module.ts
index 0a2fb76a..f930a466 100644
--- a/api/src/slices/mcpServer/oauth/mcpOauth.module.ts
+++ b/api/src/slices/mcpServer/oauth/mcpOauth.module.ts
@@ -4,12 +4,15 @@ import { McpServerModule } from '../mcpServer.module';
 import { SecretModule } from '#/agent/secret/secret.module';
 import { BridleModule } from '#/bridle/bridle.module';
 import { McpOauthController } from './mcpOauth.controller';
+import { McpOauthTool } from './mcpOauth.tool';
 import { McpOauthService } from './domain/mcpOauth.service';
 import { McpOauthClient } from './data/mcpOauth.client';
 
 @Module({
   imports: [AuthModule, McpServerModule, SecretModule, BridleModule],
   controllers: [McpOauthController],
-  providers: [McpOauthService, McpOauthClient],
+  // McpOauthTool sits here, not in McpServerModule, so the service stays
+  // module-private and no import runs back the other way (CLEAN-109).
+  providers: [McpOauthService, McpOauthClient, McpOauthTool],
 })
 export class McpOauthModule {}
diff --git a/api/src/slices/mcpServer/oauth/mcpOauth.tool.spec.ts b/api/src/slices/mcpServer/oauth/mcpOauth.tool.spec.ts
new file mode 100644
index 00000000..1529732c
--- /dev/null
+++ b/api/src/slices/mcpServer/oauth/mcpOauth.tool.spec.ts
@@ -0,0 +1,125 @@
+import {
+  BadRequestException,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import type { Request } from 'express';
+import { McpOauthTool } from './mcpOauth.tool';
+import type { McpOauthService } from './domain/mcpOauth.service';
+import { UserRoleTypes } from '#/user/user/domain';
+
+const AUTHORIZE_URL =
+  'https://auth.provider.test/authorize?client_id=abc&state=xyz';
+
+const request = (roles: UserRoleTypes[], sub = 'agent:agent-ops'): Request =>
+  ({
+    user: { sub, email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+/** An operator that is a person, not an agent — there is no "self" to connect. */
+const humanOperator = () => request([UserRoleTypes.Owner], 'user-1');
+
+function harness() {
+  const oauth = {
+    start: jest.fn().mockResolvedValue({ authorizeUrl: AUTHORIZE_URL }),
+  };
+  const tool = new McpOauthTool(oauth as unknown as McpOauthService);
+  return { tool, oauth };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('McpOauthTool — who may use it', () => {
+  it('hides the tool from a plain agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists it for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, oauth } = harness();
+    await expect(
+      tool.startMcpOauth({ serverId: 'mcp-1' }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(oauth.start).not.toHaveBeenCalled();
+  });
+});
+
+describe('McpOauthTool — starting a connect', () => {
+  it('connects for the calling agent by default and hands back the URL to open', async () => {
+    const { tool, oauth } = harness();
+    const text = textOf(
+      await tool.startMcpOauth({ serverId: 'mcp-1' }, null, operator()),
+    );
+    expect(oauth.start).toHaveBeenCalledWith('mcp-1', 'agent-ops');
+    expect(text).toContain(AUTHORIZE_URL);
+    expect(text).toContain('"agentId": "agent-ops"');
+    expect(text).toContain('browser');
+  });
+
+  it('connects for another agent when told which', async () => {
+    const { tool, oauth } = harness();
+    await tool.startMcpOauth(
+      { serverId: 'mcp-1', agentId: 'agent-support' },
+      null,
+      operator(),
+    );
+    expect(oauth.start).toHaveBeenCalledWith('mcp-1', 'agent-support');
+  });
+
+  it('asks for an agentId when the operator is a person', async () => {
+    const { tool, oauth } = harness();
+    const result = await tool.startMcpOauth(
+      { serverId: 'mcp-1' },
+      null,
+      humanOperator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('agentId');
+    expect(oauth.start).not.toHaveBeenCalled();
+  });
+
+  it('points a missing server at list_mcp_servers', async () => {
+    const { tool, oauth } = harness();
+    oauth.start.mockRejectedValue(
+      new NotFoundException('MCP server not found'),
+    );
+    const result = await tool.startMcpOauth(
+      { serverId: 'nope' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('not found');
+    expect(textOf(result)).toContain('list_mcp_servers');
+  });
+
+  it('tells the model to switch the server to oauth first when it is not', async () => {
+    const { tool, oauth } = harness();
+    oauth.start.mockRejectedValue(
+      new BadRequestException('MCP server is not OAuth-based'),
+    );
+    const result = await tool.startMcpOauth(
+      { serverId: 'mcp-1' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('update_mcp_server');
+  });
+
+  it('lets a non-HTTP failure escape, so the MCP layer reports it as an error', async () => {
+    const { tool, oauth } = harness();
+    oauth.start.mockRejectedValue(new Error('discovery timed out'));
+    await expect(
+      tool.startMcpOauth({ serverId: 'mcp-1' }, null, operator()),
+    ).rejects.toThrow('discovery timed out');
+  });
+});
diff --git a/api/src/slices/mcpServer/oauth/mcpOauth.tool.ts b/api/src/slices/mcpServer/oauth/mcpOauth.tool.ts
new file mode 100644
index 00000000..913434c2
--- /dev/null
+++ b/api/src/slices/mcpServer/oauth/mcpOauth.tool.ts
@@ -0,0 +1,110 @@
+import { HttpException, Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerAgentId,
+  callerIsOperator,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { McpOauthService } from './domain/mcpOauth.service';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/**
+ * The in-chat OAuth "Connect" for an MCP server, as a tool (CLEAN-109). It
+ * mirrors `POST mcp-servers/:id/oauth/start` and lives in this folder, not in
+ * `mcpServer.tool.ts`, because `McpOauthModule` imports `McpServerModule` for
+ * the gateway: registering it there would need the import the other way too,
+ * and a cycle for one tool is a poor trade.
+ *
+ * `McpOauthService` does the work — server lookup, discovery, one-time client
+ * registration, PKCE state — exactly as for the console. The tool adds only
+ * the two things a model needs: which agent the connection belongs to (the
+ * caller, unless told otherwise) and what to do with the URL that comes back.
+ */
+@Injectable()
+export class McpOauthTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(McpOauthTool.name);
+
+  constructor(private readonly oauth: McpOauthService) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'start_mcp_oauth',
+    topic: ToolTopics.McpServers,
+    title: 'Start OAuth for a server',
+    template: 'Connect the MCP server «name» with OAuth',
+    description:
+      'Begin the OAuth connect for an MCP server registered with authType ' +
+      'oauth. Returns an authorization URL: give it to the person to open in ' +
+      'their browser; they log in at the provider, and the callback stores ' +
+      'the token for the agent named by `agentId` (the calling agent when ' +
+      'omitted) and wakes it. The link is single-use and expires in ten ' +
+      'minutes. Find the server id with list_mcp_servers.',
+    parameters: z.object({
+      serverId: z
+        .string()
+        .describe('MCP server id (list_mcp_servers has them)'),
+      agentId: z
+        .string()
+        .optional()
+        .describe(
+          'Agent that will own the connection. Defaults to the calling agent.',
+        ),
+    }),
+  })
+  async startMcpOauth(
+    { serverId, agentId }: { serverId: string; agentId?: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const owner = agentId ?? callerAgentId(httpRequest);
+    if (!owner) {
+      return err(
+        'Pass agentId: the token is stored for one agent, and this caller is ' +
+          'not an agent. list_agents has the ids.',
+      );
+    }
+    try {
+      const { authorizeUrl } = await this.oauth.start(serverId, owner);
+      this.logger.log(
+        `OAuth connect started through MCP: server=${serverId} agent=${owner}`,
+      );
+      return ok({
+        authorizeUrl,
+        agentId: owner,
+        instruction:
+          'Send this URL to the person and ask them to open it in their ' +
+          'browser and log in at the provider. Once they see "Connected", ' +
+          `the token is stored for ${owner} — nothing more to call here.`,
+      });
+    } catch (error) {
+      // The service's own refusals — no such server, not oauth, no public
+      // URL, no dynamic registration — each name a cause the model can act
+      // on; anything else is not ours to interpret and escapes as an error.
+      if (!(error instanceof HttpException)) throw error;
+      return err(`${error.message} ${nextMove(error.message)}`);
+    }
+  }
+}
+
+/** Turn the service's refusal into the tool call that fixes it. */
+function nextMove(message: string): string {
+  if (message.includes('not found')) {
+    return 'Call list_mcp_servers to find the id.';
+  }
+  if (message.includes('not OAuth-based')) {
+    return 'Set its authType to oauth with update_mcp_server first.';
+  }
+  return 'Tell the person; this is not something a tool call fixes.';
+}
diff --git a/api/src/slices/paddock/evaluation/evaluation.tool.spec.ts b/api/src/slices/paddock/evaluation/evaluation.tool.spec.ts
new file mode 100644
index 00000000..2f0a8d3e
--- /dev/null
+++ b/api/src/slices/paddock/evaluation/evaluation.tool.spec.ts
@@ -0,0 +1,172 @@
+import { NotFoundException } from '@nestjs/common';
+import { PaddockEvaluationTool } from './evaluation.tool';
+
+const snapshot = {
+  id: 'sc-1',
+  name: 'Refund flow',
+  messages: [{ text: 'I want a refund', from: 'user' }],
+  expectedBehavior: 'Quotes the policy',
+  successCriteria: [],
+};
+
+const evaluation = {
+  id: 'ev-1',
+  status: 'completed',
+  scenariosSnapshot: [snapshot],
+  results: [
+    {
+      id: 'res-1',
+      evaluationId: 'ev-1',
+      scenarioId: 'sc-1',
+      verdict: 'pass',
+      finalScore: 0.9,
+      agreement: 1,
+      dimensionScores: { correctness: 0.9 },
+      judges: [],
+      failureReasons: [],
+    },
+  ],
+};
+
+const notFound = () => {
+  throw new NotFoundException('Evaluation not found');
+};
+
+const harness = () => {
+  const service = {
+    abort: jest.fn(async (id: string) => ({ id, status: 'aborted' })),
+    rerun: jest.fn(async (id: string) => ({
+      id: `${id}-2`,
+      status: 'running',
+    })),
+    getLogs: jest.fn(async (id: string) =>
+      id === 'ev-1' ? { lines: ['one', 'two', 'three'] } : notFound(),
+    ),
+    getScenario: jest.fn(async (id: string, scenarioId: string) => {
+      if (id !== 'ev-1') return notFound();
+      if (scenarioId !== 'sc-1') {
+        throw new NotFoundException(
+          `Scenario ${scenarioId} is not part of evaluation ${id}`,
+        );
+      }
+      return snapshot;
+    }),
+    getById: jest.fn(async (id: string) =>
+      id === 'ev-1' ? evaluation : notFound(),
+    ),
+    getTrace: jest.fn(async (id: string, scenarioId: string) => {
+      if (id !== 'ev-1') return notFound();
+      return scenarioId === 'sc-1' ? { turns: [{ response: 'Sure' }] } : null;
+    }),
+  };
+  const tool = new PaddockEvaluationTool(service as never);
+  return { tool, service };
+};
+
+const textOf = (r: { content: { text: string }[] }) => r.content[0].text;
+
+describe('PaddockEvaluationTool — abort_paddock_evaluation (CLEAN-109)', () => {
+  it('aborts once confirmed', async () => {
+    const { tool, service } = harness();
+    const result = await tool.abort({ id: 'ev-1', confirm: true });
+    expect(service.abort).toHaveBeenCalledWith('ev-1');
+    expect(textOf(result)).toContain('"status": "aborted"');
+  });
+
+  it('refuses without confirm and aborts nothing', async () => {
+    const { tool, service } = harness();
+    const result = await tool.abort({ id: 'ev-1' });
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('abort the paddock evaluation ev-1');
+    expect(service.abort).not.toHaveBeenCalled();
+  });
+
+  it('rerun needs no confirmation', async () => {
+    const { tool, service } = harness();
+    const result = await tool.rerun({ id: 'ev-1' });
+    expect(service.rerun).toHaveBeenCalledWith('ev-1');
+    expect(result.isError).toBeUndefined();
+  });
+});
+
+describe('PaddockEvaluationTool — get_paddock_evaluation_logs (CLEAN-109)', () => {
+  it('returns the buffered lines', async () => {
+    const { tool, service } = harness();
+    const result = await tool.logs({ id: 'ev-1' });
+    expect(service.getLogs).toHaveBeenCalledWith('ev-1');
+    const text = textOf(result);
+    expect(text).toContain('"total": 3');
+    expect(text).toContain('"one"');
+    expect(text).toContain('"three"');
+  });
+
+  it('keeps only the last N lines when asked for a tail', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.logs({ id: 'ev-1', tail: 1 }));
+    expect(text).toContain('"total": 3');
+    expect(text).toContain('"three"');
+    expect(text).not.toContain('"one"');
+  });
+
+  it('turns a missing evaluation into a sentence naming the next move', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.logs({ id: 'nope' }));
+    expect(text).toContain('Evaluation not found');
+    expect(text).toContain('list_paddock_evaluations');
+  });
+});
+
+describe('PaddockEvaluationTool — get_paddock_evaluation_scenario_result (CLEAN-109)', () => {
+  it('returns the snapshot scenario with its verdict', async () => {
+    const { tool, service } = harness();
+    const result = await tool.scenarioResult({
+      id: 'ev-1',
+      scenarioId: 'sc-1',
+    });
+    expect(service.getScenario).toHaveBeenCalledWith('ev-1', 'sc-1');
+    expect(service.getById).toHaveBeenCalledWith('ev-1');
+    const text = textOf(result);
+    expect(text).toContain('"name": "Refund flow"');
+    expect(text).toContain('"verdict": "pass"');
+    expect(text).toContain('"status": "completed"');
+  });
+
+  it('reports a scenario that is not part of the evaluation', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.scenarioResult({ id: 'ev-1', scenarioId: 'sc-9' }),
+    );
+    expect(text).toContain('not part of evaluation ev-1');
+  });
+
+  it('reports a missing evaluation', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.scenarioResult({ id: 'nope', scenarioId: 'sc-1' }),
+    );
+    expect(text).toContain('Evaluation not found');
+    expect(text).toContain('list_paddock_evaluations');
+  });
+});
+
+describe('PaddockEvaluationTool — get_paddock_evaluation_trace (CLEAN-109)', () => {
+  it('returns the trace of a scenario', async () => {
+    const { tool, service } = harness();
+    const result = await tool.trace({ id: 'ev-1', scenarioId: 'sc-1' });
+    expect(service.getTrace).toHaveBeenCalledWith('ev-1', 'sc-1');
+    expect(textOf(result)).toContain('"response": "Sure"');
+  });
+
+  it('explains a null trace instead of returning nothing', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.trace({ id: 'ev-1', scenarioId: 'sc-9' }));
+    expect(text).toContain('No trace for scenario sc-9');
+    expect(text).toContain('get_paddock_evaluation');
+  });
+
+  it('reports a missing evaluation', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.trace({ id: 'nope', scenarioId: 'sc-1' }));
+    expect(text).toContain('Evaluation not found');
+  });
+});
diff --git a/api/src/slices/paddock/evaluation/evaluation.tool.ts b/api/src/slices/paddock/evaluation/evaluation.tool.ts
index b81a2691..07dc5b06 100644
--- a/api/src/slices/paddock/evaluation/evaluation.tool.ts
+++ b/api/src/slices/paddock/evaluation/evaluation.tool.ts
@@ -1,15 +1,9 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable, Logger, NotFoundException } from '@nestjs/common';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
+import { CONFIRM_SENTENCE, confirmed, ok } from '#/mcp/tooling';
 import { PaddockEvaluationService } from './domain/evaluation.service';
 
-const asText = (value: unknown): string =>
-  typeof value === 'string' ? value : JSON.stringify(value, null, 2);
-
-const ok = (value: unknown) => ({
-  content: [{ type: 'text' as const, text: asText(value) }],
-});
-
 const judgeOverrideSchema = z
   .object({
     credentialIds: z.array(z.string()).optional(),
@@ -27,6 +21,9 @@ export class PaddockEvaluationTool {
 
   @Tool({
     name: 'run_paddock_evaluation',
+    topic: ToolTopics.Paddock,
+    title: 'Run an evaluation',
+    template: 'Run a paddock evaluation for the agent «name»',
     description:
       'Start a paddock evaluation for an agent. Returns immediately with the evaluation record; the actual run is async — poll get_paddock_evaluation for status. Errors with 409 if another eval is already running for the agent.',
     parameters: z.object({
@@ -57,6 +54,9 @@ export class PaddockEvaluationTool {
 
   @Tool({
     name: 'list_paddock_evaluations',
+    topic: ToolTopics.Paddock,
+    title: 'List evaluations',
+    template: 'List the paddock evaluations of «agent»',
     description:
       'List paddock evaluations. Filter by agentId / templateId. Most recent first.',
     parameters: z.object({
@@ -71,6 +71,9 @@ export class PaddockEvaluationTool {
 
   @Tool({
     name: 'get_paddock_evaluation',
+    topic: ToolTopics.Paddock,
+    title: 'Show an evaluation',
+    template: 'How did the evaluation «id» go?',
     description:
       'Get an evaluation by id. Includes status, summary counts, and per-scenario results once the run completes.',
     parameters: z.object({ id: z.string() }),
@@ -81,6 +84,9 @@ export class PaddockEvaluationTool {
 
   @Tool({
     name: 'get_paddock_evaluation_report',
+    topic: ToolTopics.Paddock,
+    title: 'Evaluation report',
+    template: 'Show the report of the evaluation «id»',
     description:
       'Fetch the full evaluation report blob (json + markdown). Only available after the evaluation finishes successfully.',
     parameters: z.object({ id: z.string() }),
@@ -91,16 +97,32 @@ export class PaddockEvaluationTool {
 
   @Tool({
     name: 'abort_paddock_evaluation',
+    topic: ToolTopics.Paddock,
+    title: 'Abort an evaluation',
+    template: 'Abort the evaluation «id»',
+    destructive: true,
     description:
-      'Mark a running paddock evaluation as aborted. The current scenario will finish before the run halts.',
-    parameters: z.object({ id: z.string() }),
+      'Mark a running paddock evaluation as aborted. The current scenario will finish before the run halts. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
   })
-  async abort({ id }: { id: string }) {
+  async abort(args: { id: string; confirm?: boolean }) {
+    const { id } = args;
+    const refusal = confirmed(args, `abort the paddock evaluation ${id}`);
+    if (refusal) return refusal;
     return ok(await this.service.abort(id));
   }
 
   @Tool({
     name: 'rerun_paddock_evaluation',
+    topic: ToolTopics.Paddock,
+    title: 'Rerun an evaluation',
+    template: 'Rerun the evaluation «id»',
     description:
       'Start a new evaluation re-using the exact scenario set + judge config from this one. Useful for comparing results across agent or prompt changes.',
     parameters: z.object({ id: z.string() }),
@@ -108,4 +130,99 @@ export class PaddockEvaluationTool {
   async rerun({ id }: { id: string }) {
     return ok(await this.service.rerun(id));
   }
+
+  @Tool({
+    name: 'get_paddock_evaluation_logs',
+    topic: ToolTopics.Paddock,
+    title: 'Evaluation logs',
+    template: 'Show the logs of evaluation «id»',
+    description:
+      'Tail the paddock CLI output (stdout + stderr) of an evaluation. The buffer is in memory (~2000 lines) and is cleared when the API restarts or a new run starts for the same agent, so an older evaluation may come back empty. Pass tail to keep only the last N lines. Find ids with list_paddock_evaluations.',
+    parameters: z.object({
+      id: z.string(),
+      tail: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe('Return only the last N lines (default: all buffered).'),
+    }),
+  })
+  async logs({ id, tail }: { id: string; tail?: number }) {
+    const found = await this.lookup(() => this.service.getLogs(id));
+    if ('error' in found) return ok(found);
+    const lines = tail ? found.value.lines.slice(-tail) : found.value.lines;
+    return ok({ id, total: found.value.lines.length, lines });
+  }
+
+  @Tool({
+    name: 'get_paddock_evaluation_scenario_result',
+    topic: ToolTopics.Paddock,
+    title: "One scenario's result",
+    template: 'How did scenario «scenario» go in evaluation «id»?',
+    description:
+      'Show how one scenario went in an evaluation: the scenario as captured in the run (messages, expected behaviour, success criteria — reliable even after template re-seeds changed live scenario ids) together with its verdict, scores and failure reasons once judged. Scenario ids come from get_paddock_evaluation; for the raw agent responses call get_paddock_evaluation_trace.',
+    parameters: z.object({ id: z.string(), scenarioId: z.string() }),
+  })
+  async scenarioResult({ id, scenarioId }: { id: string; scenarioId: string }) {
+    const found = await this.lookup(async () => {
+      const scenario = await this.service.getScenario(id, scenarioId);
+      const evaluation = await this.service.getById(id);
+      return { scenario, evaluation };
+    });
+    if ('error' in found) return ok(found);
+    const { scenario, evaluation } = found.value;
+    const result =
+      evaluation.results.find((r) => r.scenarioId === scenarioId) ?? null;
+    return ok({
+      evaluationId: id,
+      status: evaluation.status,
+      scenario,
+      // Null while the run has not reached this scenario yet.
+      result,
+    });
+  }
+
+  @Tool({
+    name: 'get_paddock_evaluation_trace',
+    topic: ToolTopics.Paddock,
+    title: 'Evaluation trace',
+    template: 'Show the trace of evaluation «id»',
+    description:
+      'Fetch the execution trace of one scenario in an evaluation: agent responses, tool calls and errors, turn by turn. Available only after the run completes. Scenario ids come from get_paddock_evaluation.',
+    parameters: z.object({ id: z.string(), scenarioId: z.string() }),
+  })
+  async trace({ id, scenarioId }: { id: string; scenarioId: string }) {
+    const found = await this.lookup(() =>
+      this.service.getTrace(id, scenarioId),
+    );
+    if ('error' in found) return ok(found);
+    if (!found.value) {
+      return ok({
+        error: `No trace for scenario ${scenarioId} in evaluation ${id} — the run may still be going, or the scenario is not part of it. Check with get_paddock_evaluation.`,
+      });
+    }
+    return ok(found.value);
+  }
+
+  /**
+   * The service answers a missing evaluation with a NotFoundException, which
+   * suits HTTP. A model reads better from a sentence that names the next
+   * move, so the read tools turn that one case into a result and let
+   * anything else throw.
+   */
+  private async lookup<T>(
+    read: () => Promise<T>,
+  ): Promise<{ value: T } | { error: string }> {
+    try {
+      return { value: await read() };
+    } catch (e) {
+      if (e instanceof NotFoundException) {
+        return {
+          error: `${e.message} — call list_paddock_evaluations to find the id`,
+        };
+      }
+      throw e;
+    }
+  }
 }
diff --git a/api/src/slices/paddock/scenario/scenario.tool.spec.ts b/api/src/slices/paddock/scenario/scenario.tool.spec.ts
new file mode 100644
index 00000000..d8ffbe23
--- /dev/null
+++ b/api/src/slices/paddock/scenario/scenario.tool.spec.ts
@@ -0,0 +1,116 @@
+import { PaddockScenarioTool } from './scenario.tool';
+
+const draft = (name: string) => ({
+  templateId: null,
+  agentId: 'agent-1',
+  category: 'conversation',
+  difficulty: 'medium',
+  name,
+  description: `${name} desc`,
+  expectedBehavior: 'Refunds within policy',
+  messages: [{ text: 'I want a refund', from: 'user' }],
+  successCriteria: [
+    { dimension: 'correctness', description: 'Quotes policy', weight: 1 },
+  ],
+  setup: null,
+});
+
+const harness = () => {
+  const scenarios = {
+    findAll: jest.fn(async () => []),
+    findById: jest.fn(async (id: string) =>
+      id === 'sc-1' ? { id: 'sc-1', name: 'Refund flow' } : null,
+    ),
+    delete: jest.fn(async () => undefined),
+    create: jest.fn(),
+    update: jest.fn(),
+  };
+  let n = 0;
+  const generator = {
+    generate: jest.fn(async () => draft(`Draft ${++n}`)),
+  };
+  const tool = new PaddockScenarioTool(scenarios as never, generator as never);
+  return { tool, scenarios, generator };
+};
+
+const textOf = (r: { content: { text: string }[] }) => r.content[0].text;
+
+describe('PaddockScenarioTool — delete_paddock_scenario (CLEAN-109)', () => {
+  it('deletes once confirmed', async () => {
+    const { tool, scenarios } = harness();
+    const result = await tool.remove({ id: 'sc-1', confirm: true });
+    expect(scenarios.delete).toHaveBeenCalledWith('sc-1');
+    expect(textOf(result)).toContain('"ok": true');
+  });
+
+  it('refuses without confirm, naming the scenario, and deletes nothing', async () => {
+    const { tool, scenarios } = harness();
+    const result = await tool.remove({ id: 'sc-1' });
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('«Refund flow»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(scenarios.delete).not.toHaveBeenCalled();
+  });
+
+  it('reports a missing scenario before asking for confirmation', async () => {
+    const { tool, scenarios } = harness();
+    const result = await tool.remove({ id: 'nope' });
+    expect(textOf(result)).toContain('not found');
+    expect(scenarios.delete).not.toHaveBeenCalled();
+  });
+});
+
+describe('PaddockScenarioTool — generate_paddock_scenarios (CLEAN-109)', () => {
+  it('drafts one scenario by default, passing the scope through as the controller does', async () => {
+    const { tool, generator, scenarios } = harness();
+    const result = await tool.generate({
+      description: 'refund requests',
+      agentId: 'agent-1',
+      category: 'conversation',
+    });
+    expect(generator.generate).toHaveBeenCalledTimes(1);
+    expect(generator.generate).toHaveBeenCalledWith({
+      description: 'refund requests',
+      templateId: undefined,
+      agentId: 'agent-1',
+      category: 'conversation',
+      difficulty: undefined,
+      credentialId: undefined,
+    });
+    const text = textOf(result);
+    expect(text).toContain('"name": "Draft 1"');
+    expect(text).toContain('Not saved');
+    // Drafts are for review; the tool never persists them.
+    expect(scenarios.create).not.toHaveBeenCalled();
+  });
+
+  it('drafts «count» scenarios one after another', async () => {
+    const { tool, generator } = harness();
+    const result = await tool.generate({
+      description: 'refund requests',
+      templateId: 'tpl-1',
+      count: 3,
+      credentialId: 'cred-1',
+    });
+    expect(generator.generate).toHaveBeenCalledTimes(3);
+    expect(generator.generate).toHaveBeenLastCalledWith(
+      expect.objectContaining({ templateId: 'tpl-1', credentialId: 'cred-1' }),
+    );
+    const text = textOf(result);
+    expect(text).toContain('"name": "Draft 1"');
+    expect(text).toContain('"name": "Draft 3"');
+  });
+
+  it('refuses an ambiguous scope without calling the LLM', async () => {
+    const { tool, generator } = harness();
+    const both = await tool.generate({
+      description: 'x',
+      agentId: 'agent-1',
+      templateId: 'tpl-1',
+    });
+    const neither = await tool.generate({ description: 'x' });
+    expect(textOf(both)).toContain('exactly one of');
+    expect(textOf(neither)).toContain('exactly one of');
+    expect(generator.generate).not.toHaveBeenCalled();
+  });
+});
diff --git a/api/src/slices/paddock/scenario/scenario.tool.ts b/api/src/slices/paddock/scenario/scenario.tool.ts
index a0cabc71..6ee1de3b 100644
--- a/api/src/slices/paddock/scenario/scenario.tool.ts
+++ b/api/src/slices/paddock/scenario/scenario.tool.ts
@@ -1,7 +1,11 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { z } from 'zod';
-import { Tool } from '#mcp';
-import { IPaddockScenarioGateway } from './domain';
+import { Tool, ToolTopics } from '#mcp';
+import { CONFIRM_SENTENCE, confirmed, ok } from '#/mcp/tooling';
+import {
+  IPaddockScenarioGateway,
+  IPaddockScenarioGeneratorGateway,
+} from './domain';
 import {
   ICreatePaddockScenarioData,
   IUpdatePaddockScenarioData,
@@ -9,13 +13,6 @@ import {
   PaddockScenarioDifficulty,
 } from './domain/scenario.types';
 
-const asText = (value: unknown): string =>
-  typeof value === 'string' ? value : JSON.stringify(value, null, 2);
-
-const ok = (value: unknown) => ({
-  content: [{ type: 'text' as const, text: asText(value) }],
-});
-
 const categoryEnum = z.enum([
   'tool_use',
   'memory',
@@ -60,10 +57,16 @@ const setupSchema = z
 export class PaddockScenarioTool {
   private readonly logger = new Logger(PaddockScenarioTool.name);
 
-  constructor(private readonly scenarios: IPaddockScenarioGateway) {}
+  constructor(
+    private readonly scenarios: IPaddockScenarioGateway,
+    private readonly generator: IPaddockScenarioGeneratorGateway,
+  ) {}
 
   @Tool({
     name: 'list_paddock_scenarios',
+    topic: ToolTopics.Paddock,
+    title: 'List paddock scenarios',
+    template: 'List the paddock scenarios of «template or agent»',
     description:
       'List paddock scenarios. Filter by templateId or agentId; without filters returns all.',
     parameters: z.object({
@@ -83,6 +86,9 @@ export class PaddockScenarioTool {
 
   @Tool({
     name: 'get_paddock_scenario',
+    topic: ToolTopics.Paddock,
+    title: 'Show a scenario',
+    template: 'Show the paddock scenario «id»',
     description: 'Get a single paddock scenario by id.',
     parameters: z.object({ id: z.string() }),
   })
@@ -93,6 +99,9 @@ export class PaddockScenarioTool {
 
   @Tool({
     name: 'list_agent_paddock_scenarios',
+    topic: ToolTopics.Paddock,
+    title: 'Scenarios of an agent',
+    template: 'Which paddock scenarios does the agent «name» have?',
     description:
       'List the merged set of paddock scenarios that would run for a given agent (template defaults + agent overrides; overrides win on name collision).',
     parameters: z.object({ agentId: z.string() }),
@@ -103,6 +112,10 @@ export class PaddockScenarioTool {
 
   @Tool({
     name: 'create_paddock_scenario',
+    topic: ToolTopics.Paddock,
+    title: 'Create a scenario',
+    template:
+      'Create a paddock scenario for «agent or template» that checks «what it checks»',
     description:
       'Create a paddock scenario. Pass exactly one of templateId or agentId — that defines the scope.',
     parameters: z.object({
@@ -163,6 +176,9 @@ export class PaddockScenarioTool {
 
   @Tool({
     name: 'update_paddock_scenario',
+    topic: ToolTopics.Paddock,
+    title: 'Update a scenario',
+    template: 'Change the paddock scenario «id»: «what to change»',
     description:
       'Update a paddock scenario. Scope (templateId / agentId) is immutable — recreate the scenario to change scope.',
     parameters: z.object({
@@ -185,13 +201,97 @@ export class PaddockScenarioTool {
 
   @Tool({
     name: 'delete_paddock_scenario',
-    description: 'Delete a paddock scenario by id.',
-    parameters: z.object({ id: z.string() }),
+    topic: ToolTopics.Paddock,
+    title: 'Delete a scenario',
+    template: 'Delete the paddock scenario «id»',
+    destructive: true,
+    description: 'Delete a paddock scenario by id. ' + CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
   })
-  async remove({ id }: { id: string }) {
+  async remove(args: { id: string; confirm?: boolean }) {
+    const { id } = args;
     const existing = await this.scenarios.findById(id);
     if (!existing) return ok({ error: `Scenario ${id} not found` });
+    const refusal = confirmed(
+      args,
+      `delete the paddock scenario «${existing.name ?? id}»`,
+    );
+    if (refusal) return refusal;
     await this.scenarios.delete(id);
     return ok({ ok: true, id });
   }
+
+  @Tool({
+    name: 'generate_paddock_scenarios',
+    topic: ToolTopics.Paddock,
+    title: 'Generate scenarios from a description',
+    template:
+      'Generate «3» paddock scenarios for the agent «name» about «topic»',
+    description:
+      'Draft paddock scenarios from a plain-language description of what to test, using an LLM. Pass exactly one of agentId or templateId as the scope (resolve names with list_agents / list_templates first). Returns the drafts only — nothing is saved. Review them, then call create_paddock_scenario for each one worth keeping.',
+    parameters: z.object({
+      description: z
+        .string()
+        .describe('What behaviour or problem the scenarios should test.'),
+      agentId: z.string().optional(),
+      templateId: z.string().optional(),
+      count: z
+        .number()
+        .int()
+        .min(1)
+        .max(5)
+        .optional()
+        .describe('How many drafts to produce (1–5, default 1).'),
+      category: categoryEnum.optional(),
+      difficulty: difficultyEnum.optional(),
+      credentialId: z
+        .string()
+        .optional()
+        .describe('LlmCredential id to draft with; default: first active.'),
+    }),
+  })
+  async generate(input: {
+    description: string;
+    agentId?: string;
+    templateId?: string;
+    count?: number;
+    category?: PaddockScenarioCategory;
+    difficulty?: PaddockScenarioDifficulty;
+    credentialId?: string;
+  }) {
+    // Same XOR rule the controller enforces on POST /paddock-scenarios/generate.
+    const hasTemplate = Boolean(input.templateId);
+    const hasAgent = Boolean(input.agentId);
+    if (hasTemplate === hasAgent) {
+      return ok({
+        error: 'Scenario must be scoped to exactly one of: templateId, agentId',
+      });
+    }
+    // The generator drafts one scenario per call; the console asks for one at
+    // a time, a chat asks for "three about refunds". Sequential on purpose —
+    // each is an LLM call and parallel drafts tend to come back near-identical.
+    const count = input.count ?? 1;
+    const drafts: ICreatePaddockScenarioData[] = [];
+    for (let i = 0; i < count; i++) {
+      drafts.push(
+        await this.generator.generate({
+          description: input.description,
+          templateId: input.templateId ?? undefined,
+          agentId: input.agentId ?? undefined,
+          category: input.category,
+          difficulty: input.difficulty,
+          credentialId: input.credentialId,
+        }),
+      );
+    }
+    return ok({
+      drafts,
+      note: 'Not saved. Call create_paddock_scenario with a draft to keep it.',
+    });
+  }
 }
diff --git a/api/src/slices/rancher/rancher.tool.ts b/api/src/slices/rancher/rancher.tool.ts
index df800680..8825240f 100644
--- a/api/src/slices/rancher/rancher.tool.ts
+++ b/api/src/slices/rancher/rancher.tool.ts
@@ -1,28 +1,37 @@
-import { ForbiddenException, Injectable, Logger } from '@nestjs/common';
+import { Injectable, Logger } from '@nestjs/common';
 import { Request } from 'express';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  CONFIRM_SENTENCE,
+  confirmed,
+  ok,
+  requireOperator,
+  stripSecrets,
+} from '#/mcp/tooling';
 import { IAgentGateway } from '#/agent/agent/domain';
 import { AgentDeployService } from '#/agent/agent/domain/agentDeploy.service';
 import { ITemplateGateway } from '#/agent/template/domain';
 import { ITemplateFileGateway } from '#/agent/templateFile/domain';
 import { ILlmGateway } from '#/llm/domain';
 import { ISkillGateway } from '#/skill/domain';
-import { ISettingGateway } from '#/setting/domain';
+import {
+  ISettingGateway,
+  describeSettingCatalog,
+  findSettingDefinition,
+  nearestSettingDefinition,
+} from '#/setting/domain';
 import { IUsageGateway } from '#/usage/domain';
 import { IFileGateway } from '#/agent/file/domain';
 import { IAuthTokenPayload } from '#/user/auth/domain';
-import { UserRoleTypes } from '#/user/user/domain';
-
-const asText = (value: unknown): string => {
-  if (typeof value === 'string') return value;
-  return JSON.stringify(value, null, 2);
-};
-
-const ok = (value: unknown) => ({
-  content: [{ type: 'text' as const, text: asText(value) }],
-});
-
+import { RancherService } from './domain/rancher.service';
+
+/**
+ * The original Ranch management tools — agents, templates, skills, LLM
+ * credentials, files, usage, settings. Operator-only: the Ranch admin agent
+ * holds the Owner role, plain agents do not (CLEAN-109 moved the check to
+ * the shared `requireOperator`; the tools themselves are unchanged).
+ */
 @Injectable()
 export class RancherTool {
   private readonly logger = new Logger(RancherTool.name);
@@ -37,21 +46,42 @@ export class RancherTool {
     private readonly settings: ISettingGateway,
     private readonly usage: IUsageGateway,
     private readonly files: IFileGateway,
+    private readonly rancher: RancherService,
   ) {}
 
+  // ─── Platform ────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'get_rancher_status',
+    topic: ToolTopics.Platform,
+    title: 'Rancher setup status',
+    template: 'Is the Rancher setup complete?',
+    description:
+      'The Rancher setup wizard state: is there an LLM credential, the special Rancher template, an admin agent, and S3 configured. Read-only; the console shows the same stepper.',
+    parameters: z.object({}),
+  })
+  async getRancherStatus(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: Request & { user?: IAuthTokenPayload },
+  ) {
+    this.requireOwner(httpRequest);
+    return ok(await this.rancher.getStatus());
+  }
+
   private requireOwner(
     httpRequest: Request & { user?: IAuthTokenPayload },
   ): void {
-    const roles = httpRequest.user?.roles ?? [];
-    if (!roles.includes(UserRoleTypes.Owner)) {
-      throw new ForbiddenException('This tool requires platform admin role.');
-    }
+    requireOperator(httpRequest);
   }
 
   // ─── Agents ──────────────────────────────────────────────────────────
 
   @Tool({
     name: 'list_agents',
+    topic: ToolTopics.Agents,
+    title: 'List agents',
+    template: 'List all agents and their status',
     description:
       'List every agent on this Ranch with their status, template, and resources.',
     parameters: z.object({}),
@@ -68,6 +98,9 @@ export class RancherTool {
 
   @Tool({
     name: 'get_agent',
+    topic: ToolTopics.Agents,
+    title: 'Show an agent',
+    template: 'Show the agent «name»',
     description:
       'Get a single agent by id, including current status, workflowId and config.',
     parameters: z.object({
@@ -87,6 +120,9 @@ export class RancherTool {
 
   @Tool({
     name: 'restart_agent',
+    topic: ToolTopics.Agents,
+    title: 'Restart an agent',
+    template: 'Restart the agent «name»',
     description:
       'Restart an agent pod. Use after editing its files or LLM credential to apply changes.',
     parameters: z.object({
@@ -118,6 +154,10 @@ export class RancherTool {
 
   @Tool({
     name: 'create_agent',
+    topic: ToolTopics.Agents,
+    title: 'Create an agent',
+    template:
+      'Create an agent «name» from the template «template» using the LLM credential «credential»',
     description:
       'Create and deploy a new agent from a template. Seeds template files, ' +
       'syncs skills and starts the first deploy — the agent will appear as ' +
@@ -133,7 +173,7 @@ export class RancherTool {
       knowledgeIds: z
         .array(z.string())
         .optional()
-        .describe('Knowledge base ids to bind (GET /knowledges for the list)'),
+        .describe('Knowledge base ids to bind (list_knowledges for the list)'),
       isAdmin: z
         .boolean()
         .optional()
@@ -183,6 +223,9 @@ export class RancherTool {
 
   @Tool({
     name: 'update_agent',
+    topic: ToolTopics.Agents,
+    title: 'Update an agent',
+    template: 'Change the agent «name»: «what to change»',
     description:
       'Update an agent: rename, switch LLM credential, or bind knowledge ' +
       'bases. knowledgeIds REPLACES the full list (fetch current via ' +
@@ -242,6 +285,9 @@ export class RancherTool {
 
   @Tool({
     name: 'set_agent_admin',
+    topic: ToolTopics.Agents,
+    title: 'Make an agent the Ranch admin',
+    template: 'Make «name» the Ranch admin agent',
     description:
       'Promote or demote an agent to/from Ranch admin. Single-admin invariant: enabling clears the flag from any other agent.',
     parameters: z.object({
@@ -263,6 +309,9 @@ export class RancherTool {
 
   @Tool({
     name: 'list_templates',
+    topic: ToolTopics.Templates,
+    title: 'List templates',
+    template: 'List all agent templates',
     description:
       'List all agent templates (image + defaults that pods are spawned from).',
     parameters: z.object({}),
@@ -278,6 +327,9 @@ export class RancherTool {
 
   @Tool({
     name: 'get_template',
+    topic: ToolTopics.Templates,
+    title: 'Show a template',
+    template: 'Show the template «name»',
     description:
       'Get a template by id, including image, defaultResources, and attached skill ids.',
     parameters: z.object({ id: z.string() }),
@@ -294,6 +346,9 @@ export class RancherTool {
 
   @Tool({
     name: 'set_template_skills',
+    topic: ToolTopics.Templates,
+    title: 'Set template skills',
+    template: 'Give the template «name» the skills «skill list»',
     description:
       'Replace the full set of skills attached to a template. The list is exhaustive — omitted ids are detached.',
     parameters: z.object({
@@ -318,6 +373,9 @@ export class RancherTool {
 
   @Tool({
     name: 'update_template',
+    topic: ToolTopics.Templates,
+    title: 'Update a template',
+    template: 'Change the template «name»: «what to change»',
     description:
       'Update template fields in place. Pass only the fields you want to change. ' +
       'Useful for editing defaultConfig, paddockConfig (passThreshold, scenarios, ' +
@@ -359,6 +417,9 @@ export class RancherTool {
 
   @Tool({
     name: 'list_template_files',
+    topic: ToolTopics.Templates,
+    title: 'List template files',
+    template: 'List the files of the template «name»',
     description:
       "List files stored in a template's S3 prefix (templates/{id}/). These are " +
       'seeded into every new agent that uses this template.',
@@ -377,6 +438,9 @@ export class RancherTool {
 
   @Tool({
     name: 'read_template_file',
+    topic: ToolTopics.Templates,
+    title: 'Read a template file',
+    template: 'Show «path» of the template «name»',
     description:
       'Read a single template file by relative path (e.g. ".agent/SOUL.md", ' +
       '".paddock/config.json"). Files larger than 256 KiB are rejected.',
@@ -400,6 +464,9 @@ export class RancherTool {
 
   @Tool({
     name: 'write_template_file',
+    topic: ToolTopics.Templates,
+    title: 'Write a template file',
+    template: 'Write «path» in the template «name» with: «content»',
     description:
       'Write or replace a template file. Only `.md` and `.json` are accepted. ' +
       'Use this to add files like ".agent/SOUL.md" or ".paddock/config.json" ' +
@@ -435,7 +502,11 @@ export class RancherTool {
 
   @Tool({
     name: 'list_llms',
-    description: 'List configured LLM credentials (provider, model, status).',
+    topic: ToolTopics.Llm,
+    title: 'List LLM credentials',
+    template: 'List the LLM credentials',
+    description:
+      'List configured LLM credentials (provider, model, status). Keys are never returned.',
     parameters: z.object({}),
   })
   async listLlms(
@@ -444,13 +515,16 @@ export class RancherTool {
     httpRequest: Request & { user?: IAuthTokenPayload },
   ) {
     this.requireOwner(httpRequest);
-    return ok(await this.llms.findAll());
+    return ok(stripSecrets(await this.llms.findAll()));
   }
 
   // ─── Skills ──────────────────────────────────────────────────────────
 
   @Tool({
     name: 'list_skills',
+    topic: ToolTopics.Skills,
+    title: 'List skills',
+    template: 'List all skills',
     description:
       'List skills available in the Ranch. Skills are bundles of instructions + helper files attached to templates.',
     parameters: z.object({}),
@@ -466,6 +540,9 @@ export class RancherTool {
 
   @Tool({
     name: 'update_skill',
+    topic: ToolTopics.Skills,
+    title: 'Update a skill',
+    template: 'Change the skill «name»: «what to change»',
     description:
       'Edit a skill in place. Pass only the fields you want to change. ' +
       'Skills are baked into agent pods at deploy time — after editing, ' +
@@ -480,15 +557,20 @@ export class RancherTool {
         .describe('Full SKILL.md markdown body — replaces existing content.'),
     }),
   })
-  async updateSkill({
-    id,
-    ...patch
-  }: {
-    id: string;
-    title?: string;
-    description?: string;
-    body?: string;
-  }) {
+  async updateSkill(
+    {
+      id,
+      ...patch
+    }: {
+      id: string;
+      title?: string;
+      description?: string;
+      body?: string;
+    },
+    _context: unknown,
+    httpRequest: Request & { user?: IAuthTokenPayload },
+  ) {
+    this.requireOwner(httpRequest);
     const skill = await this.skills.findById(id);
     if (!skill) return ok({ error: `Skill ${id} not found` });
     const updated = await this.skills.update(id, patch);
@@ -497,6 +579,9 @@ export class RancherTool {
 
   @Tool({
     name: 'list_skill_agents',
+    topic: ToolTopics.Skills,
+    title: 'Which agents use a skill',
+    template: 'Which agents use the skill «name»?',
     description:
       'List agents currently using this skill (via their template). Use this ' +
       'before `redeploy_skill_agents` to preview what will be restarted.',
@@ -504,22 +589,41 @@ export class RancherTool {
       skillId: z.string(),
     }),
   })
-  async listSkillAgents({ skillId }: { skillId: string }) {
+  async listSkillAgents(
+    { skillId }: { skillId: string },
+    _context: unknown,
+    httpRequest: Request & { user?: IAuthTokenPayload },
+  ) {
+    this.requireOwner(httpRequest);
     return ok(await this.skills.findDependentAgents(skillId));
   }
 
   @Tool({
     name: 'redeploy_skill_agents',
+    topic: ToolTopics.Skills,
+    title: 'Redeploy agents of a skill',
+    template: 'Redeploy every agent that uses the skill «name»',
+    destructive: true,
     description:
       'Restart every agent whose template includes this skill so it picks up ' +
       "the edited SKILL.md. Each agent's workflow is cancelled and resubmitted " +
       '(template files + skills resynced from DB). Sequential with concurrency 3 ' +
-      'to avoid slamming the cluster. Returns aggregate counts and per-agent errors.',
+      'to avoid slamming the cluster. Returns aggregate counts and per-agent errors. ' +
+      CONFIRM_SENTENCE,
     parameters: z.object({
       skillId: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
     }),
   })
-  async redeploySkillAgents({ skillId }: { skillId: string }) {
+  async redeploySkillAgents(
+    args: { skillId: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: Request & { user?: IAuthTokenPayload },
+  ) {
+    this.requireOwner(httpRequest);
+    const { skillId } = args;
     const skill = await this.skills.findById(skillId);
     if (!skill) return ok({ error: `Skill ${skillId} not found` });
 
@@ -527,6 +631,11 @@ export class RancherTool {
     if (dependents.length === 0) {
       return ok({ skillId, total: 0, restarted: 0, failed: 0, errors: [] });
     }
+    const refusal = confirmed(
+      args,
+      `restart ${dependents.length} agent(s) that use the skill «${skill.title ?? skillId}»`,
+    );
+    if (refusal) return refusal;
 
     const CONCURRENCY = 3;
     const errors: { agentId: string; error: string }[] = [];
@@ -566,6 +675,9 @@ export class RancherTool {
 
   @Tool({
     name: 'list_agent_files',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'List workspace files',
+    template: 'List the files of the agent «name»',
     description:
       "List files in an agent's S3 prefix (the files mounted into its pod's `.agent/` dir).",
     parameters: z.object({ agentId: z.string() }),
@@ -581,6 +693,9 @@ export class RancherTool {
 
   @Tool({
     name: 'read_agent_file',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Read a workspace file',
+    template: 'Show «path» from the agent «name»',
     description:
       'Read a single agent file by relative path (e.g. SOUL.md, MEMORY.md, agent.config.json).',
     parameters: z.object({
@@ -599,6 +714,9 @@ export class RancherTool {
 
   @Tool({
     name: 'write_agent_file',
+    topic: ToolTopics.AgentWorkspace,
+    title: 'Write a workspace file',
+    template: 'Write «path» in the agent «name» with: «content»',
     description:
       'Write or replace an agent file. Only `.md` and `.json` are supported. Restart the agent for changes to take effect.',
     parameters: z.object({
@@ -640,6 +758,9 @@ export class RancherTool {
 
   @Tool({
     name: 'agent_usage',
+    topic: ToolTopics.ChatsUsage,
+    title: 'Usage of an agent',
+    template: 'How much did the agent «name» cost in the last «30» days?',
     description: 'Recent token usage records for an agent (default 30 days).',
     parameters: z.object({
       agentId: z.string(),
@@ -664,8 +785,16 @@ export class RancherTool {
 
   @Tool({
     name: 'list_settings',
+    topic: ToolTopics.Settings,
+    title: 'List settings',
+    template: 'Show the settings in «group»',
+    // The catalogue rides in the description so tools/list already tells the
+    // model which keys exist — a setting is a free-form row, and a guessed
+    // key would be saved as a row nothing reads (CLEAN-109).
     description:
-      'List all platform settings, optionally filtered by group (e.g. integrations, agent_defaults, auth).',
+      'List all platform settings, optionally filtered by group (e.g. integrations, agent_defaults, auth).' +
+      '\n\n' +
+      describeSettingCatalog(),
     parameters: z.object({
       group: z.string().optional(),
     }),
@@ -676,14 +805,37 @@ export class RancherTool {
     httpRequest: Request & { user?: IAuthTokenPayload },
   ) {
     this.requireOwner(httpRequest);
-    if (group) return ok(await this.settings.findByGroup(group));
-    return ok(await this.settings.findAll());
+    const rows = group
+      ? await this.settings.findByGroup(group)
+      : await this.settings.findAll();
+    // Password-type settings (bot tokens, S3 secrets, the knowledge api key)
+    // are catalogued as secret; the list says whether they are set, never
+    // what they hold (FR-004).
+    return ok(
+      rows.map((row) =>
+        findSettingDefinition(row.group, row.name)?.secret
+          ? {
+              ...row,
+              value:
+                row.value === null || row.value === undefined || row.value === ''
+                  ? '(secret — empty)'
+                  : '(secret — set)',
+            }
+          : row,
+      ),
+    );
   }
 
   @Tool({
     name: 'upsert_setting',
+    topic: ToolTopics.Settings,
+    title: 'Set a setting',
+    template: 'Set «group».«name» to «value»',
     description:
-      'Create or replace a setting by group/name. Use valueType="string" for plain strings, "json" for everything else.',
+      'Create or replace a setting by group/name. Use valueType="string" for plain strings, "json" for everything else. ' +
+      'Unknown keys are accepted, as in the console, but nothing reads them — prefer a key from the list below.' +
+      '\n\n' +
+      describeSettingCatalog(),
     parameters: z.object({
       group: z.string(),
       name: z.string(),
@@ -711,11 +863,20 @@ export class RancherTool {
     httpRequest: Request & { user?: IAuthTokenPayload },
   ) {
     this.requireOwner(httpRequest);
-    return ok(
-      await this.settings.upsert(group, name, {
-        value,
-        valueType: valueType ?? 'string',
-      }),
-    );
+    const saved = await this.settings.upsert(group, name, {
+      value,
+      valueType: valueType ?? 'string',
+    });
+    if (findSettingDefinition(group, name)) return ok(saved);
+    // Saved anyway (the console allows any key), but say what it probably
+    // should have been, so a typo does not silently become a dead row.
+    const near = nearestSettingDefinition(group, name);
+    return ok({
+      ...saved,
+      ...(near && { nearestKey: `${near.group}.${near.name}` }),
+      hint: near
+        ? `«${group}.${name}» is not a key the platform reads — did you mean «${near.group}.${near.name}» (${near.description})?`
+        : `«${group}.${name}» is not a key the platform reads; it is saved but nothing uses it.`,
+    });
   }
 }
diff --git a/api/src/slices/reins/knowledge/knowledge.module.ts b/api/src/slices/reins/knowledge/knowledge.module.ts
index b012311f..c65a0f2b 100644
--- a/api/src/slices/reins/knowledge/knowledge.module.ts
+++ b/api/src/slices/reins/knowledge/knowledge.module.ts
@@ -14,6 +14,7 @@ import { IndexReconcileService } from './domain/indexReconcile.service';
 import { KnowledgeGateway } from './data/knowledge.gateway';
 import { KnowledgeMapper } from './data/knowledge.mapper';
 import { KnowledgeTool } from './knowledge.tool';
+import { KnowledgeAdminTool } from './knowledgeAdmin.tool';
 
 @Module({
   imports: [
@@ -33,6 +34,7 @@ import { KnowledgeTool } from './knowledge.tool';
     IndexReconcileService,
     { provide: IKnowledgeGateway, useClass: KnowledgeGateway },
     KnowledgeTool,
+    KnowledgeAdminTool,
   ],
   exports: [IKnowledgeGateway, KnowledgeService],
 })
diff --git a/api/src/slices/reins/knowledge/knowledge.tool.ts b/api/src/slices/reins/knowledge/knowledge.tool.ts
index 6a4d5cba..783c7bb6 100644
--- a/api/src/slices/reins/knowledge/knowledge.tool.ts
+++ b/api/src/slices/reins/knowledge/knowledge.tool.ts
@@ -1,6 +1,6 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { z } from 'zod';
-import { Tool } from '#mcp';
+import { Tool, ToolTopics } from '#mcp';
 import { Request } from 'express';
 import { IAuthTokenPayload } from '#/user/auth/domain';
 import { IAgentGateway } from '#/agent/agent/domain';
@@ -84,6 +84,9 @@ export class KnowledgeTool implements IDynamicallyDescribedTool {
 
   @Tool({
     name: 'query_knowledge',
+    topic: ToolTopics.Knowledge,
+    title: 'Ask the knowledge bases',
+    template: 'What does our knowledge say about «question»?',
     description: BASE_DESCRIPTION,
     parameters: z.object({
       knowledge_id: z
diff --git a/api/src/slices/reins/knowledge/knowledgeAdmin.tool.spec.ts b/api/src/slices/reins/knowledge/knowledgeAdmin.tool.spec.ts
new file mode 100644
index 00000000..83814a49
--- /dev/null
+++ b/api/src/slices/reins/knowledge/knowledgeAdmin.tool.spec.ts
@@ -0,0 +1,497 @@
+import {
+  ConflictException,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import type { Request } from 'express';
+import { KnowledgeAdminTool } from './knowledgeAdmin.tool';
+import type { KnowledgeService } from './domain/knowledge.service';
+import type { IKnowledgeData } from './domain/knowledge.types';
+import type { IKnowledgeConfigGateway } from '../config/domain/knowledgeConfig.gateway';
+import type { ILightragClient } from '../lightrag/domain/lightrag.client';
+import type { ILlmGateway } from '#/llm/domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * These tools let an agent decide what every other agent is allowed to read,
+ * and delete it. So beyond the happy paths: a plain agent must not see or
+ * call them, a delete must not happen on a bare request, a wrong id must be
+ * reported as such and never as a request for confirmation, and the service
+ * api key must never appear in a status answer.
+ */
+const API_KEY = 'lightrag-secret-key-1234';
+
+const base = (overrides: Partial<IKnowledgeData> = {}): IKnowledgeData => ({
+  id: 'kb-1',
+  name: 'Returns policy',
+  description: 'How returns and refunds work',
+  workspace: 'ws-kb-1',
+  indexStatus: 'ready',
+  indexError: null,
+  indexedAt: new Date('2026-09-17T10:00:00.000Z'),
+  indexStartedAt: null,
+  instanceState: 'ready',
+  instanceError: null,
+  instanceEndpoint: null,
+  migrationState: 'done',
+  createdAt: new Date('2026-09-17T09:00:00.000Z'),
+  updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  sourceCount: 3,
+  indexedCount: 3,
+  failedCount: 0,
+  retryingCount: 0,
+  processingCount: 0,
+  indexRunAlive: false,
+  ...overrides,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: KnowledgeAdminTool;
+  service: {
+    listPage: jest.Mock;
+    getWithDerivedStatus: jest.Mock;
+    get: jest.Mock;
+    create: jest.Mock;
+    update: jest.Mock;
+    delete: jest.Mock;
+    startIndex: jest.Mock;
+    getOverview: jest.Mock;
+    getGraphLabels: jest.Mock;
+  };
+  config: {
+    isEnabled: jest.Mock;
+    resolve: jest.Mock;
+    getSelectedCredentialIds: jest.Mock;
+  };
+  lightrag: { health: jest.Mock };
+  llm: { hasCredentialWithCapability: jest.Mock };
+}
+
+function harness(): Harness {
+  const service = {
+    listPage: jest.fn().mockResolvedValue({
+      items: [{ ...base(), sourcesCount: 3, totalSizeBytes: 2048 }],
+      total: 1,
+      page: 1,
+      perPage: 50,
+    }),
+    getWithDerivedStatus: jest.fn().mockResolvedValue(base()),
+    get: jest.fn().mockResolvedValue(base()),
+    create: jest
+      .fn()
+      .mockResolvedValue(
+        base({ id: 'kb-2', name: 'Shipping', sourceCount: 0 }),
+      ),
+    update: jest.fn().mockResolvedValue(base({ name: 'Returns & refunds' })),
+    delete: jest.fn().mockResolvedValue(undefined),
+    startIndex: jest.fn().mockResolvedValue(undefined),
+    getOverview: jest.fn().mockResolvedValue({
+      sourceCount: 3,
+      indexedCount: 3,
+      failedCount: 0,
+      retryingCount: 0,
+      processingCount: 0,
+      byType: { file: 2, url: 1, text: 0 },
+      totalSizeBytes: 2048,
+    }),
+    getGraphLabels: jest.fn().mockResolvedValue({
+      labels: ['Refund', 'Return window'],
+      total: 2,
+      truncated: false,
+    }),
+  };
+  const config = {
+    isEnabled: jest.fn().mockResolvedValue(true),
+    resolve: jest.fn().mockResolvedValue({
+      url: 'http://lightrag:9621',
+      apiKey: API_KEY,
+      bucket: 'ranch-knowledge',
+      enabled: true,
+    }),
+    getSelectedCredentialIds: jest
+      .fn()
+      .mockResolvedValue({ chat: 'cred-chat', embedding: null }),
+  };
+  const lightrag = {
+    health: jest.fn().mockResolvedValue({
+      ok: true,
+      configuration: {
+        llmBinding: 'openai',
+        llmModel: 'gpt-4o-mini',
+        embeddingBinding: 'openai',
+        embeddingModel: 'text-embedding-3-small',
+        embeddingBindingHost: null,
+      },
+    }),
+  };
+  const llm = {
+    hasCredentialWithCapability: jest.fn().mockResolvedValue(true),
+  };
+
+  const tool = new KnowledgeAdminTool(
+    service as unknown as KnowledgeService,
+    config as unknown as IKnowledgeConfigGateway,
+    lightrag as unknown as ILightragClient,
+    llm as unknown as ILlmGateway,
+  );
+  return { tool, service, config, lightrag, llm };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('KnowledgeAdminTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, service } = harness();
+    await expect(
+      tool.deleteKnowledge({ id: 'kb-1', confirm: true }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(service.delete).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool, service } = harness();
+    await expect(
+      tool.listKnowledges({}, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(service.listPage).not.toHaveBeenCalled();
+  });
+});
+
+describe('KnowledgeAdminTool — reading', () => {
+  it('lists a page with the search and paging the route accepts', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.listKnowledges(
+        { search: 'return', page: 2, perPage: 10 },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.listPage).toHaveBeenCalledWith({
+      search: 'return',
+      page: 2,
+      perPage: 10,
+    });
+    expect(text).toContain('Returns policy');
+    expect(text).toContain('"total": 1');
+  });
+
+  it('answers an empty page, not a refusal, when the service is not configured', async () => {
+    const { tool, service, config } = harness();
+    config.isEnabled.mockResolvedValue(false);
+    const result = await tool.listKnowledges({ perPage: 5 }, null, operator());
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('"total": 0');
+    expect(textOf(result)).toContain('"perPage": 5');
+    expect(textOf(result)).toContain('get_knowledge_status');
+    expect(service.listPage).not.toHaveBeenCalled();
+  });
+
+  it('shows one base with the status derived from its sources', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.getKnowledge({ id: 'kb-1' }, null, operator()),
+    );
+    expect(service.getWithDerivedStatus).toHaveBeenCalledWith('kb-1');
+    expect(text).toContain('Returns policy');
+    expect(text).toContain('"indexStatus": "ready"');
+  });
+
+  it('names list_knowledges when the id does not exist', async () => {
+    const { tool, service } = harness();
+    service.getWithDerivedStatus.mockRejectedValue(
+      new NotFoundException('Knowledge kb-9 not found'),
+    );
+    const text = textOf(
+      await tool.getKnowledge({ id: 'kb-9' }, null, operator()),
+    );
+    expect(text).toContain('kb-9 not found');
+    expect(text).toContain('list_knowledges');
+  });
+
+  it('refuses a per-base read when the service is not configured, naming the status tool', async () => {
+    const { tool, service, config } = harness();
+    config.isEnabled.mockResolvedValue(false);
+    const result = await tool.getKnowledge({ id: 'kb-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('get_knowledge_status');
+    expect(service.getWithDerivedStatus).not.toHaveBeenCalled();
+  });
+
+  it('reads the overview in one call', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.getKnowledgeOverview({ id: 'kb-1' }, null, operator()),
+    );
+    expect(service.getOverview).toHaveBeenCalledWith('kb-1');
+    expect(text).toContain('"totalSizeBytes": 2048');
+    expect(text).toContain('"url": 1');
+  });
+
+  it('passes the label filter and cap through to the service', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.listKnowledgeGraphLabels(
+        { id: 'kb-1', search: 'ref', limit: 10 },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.getGraphLabels).toHaveBeenCalledWith('kb-1', {
+      search: 'ref',
+      limit: 10,
+    });
+    expect(text).toContain('Refund');
+    expect(text).toContain('"truncated": false');
+  });
+
+  it('reports a missing base for labels too', async () => {
+    const { tool, service } = harness();
+    service.getGraphLabels.mockRejectedValue(
+      new NotFoundException('Knowledge kb-9 not found'),
+    );
+    const text = textOf(
+      await tool.listKnowledgeGraphLabels({ id: 'kb-9' }, null, operator()),
+    );
+    expect(text).toContain('kb-9 not found');
+    expect(text).toContain('list_knowledges');
+  });
+});
+
+describe('KnowledgeAdminTool — service status', () => {
+  it('reports readiness the way GET knowledges/status does', async () => {
+    const { tool, lightrag, llm } = harness();
+    const text = textOf(await tool.getKnowledgeStatus({}, null, operator()));
+    expect(llm.hasCredentialWithCapability).toHaveBeenCalledWith('chat');
+    expect(llm.hasCredentialWithCapability).toHaveBeenCalledWith('embedding');
+    expect(lightrag.health).toHaveBeenCalled();
+    expect(text).toContain('"enabled": true');
+    expect(text).toContain('"isHealthy": true');
+    expect(text).toContain('"hasCredentialsSelected": true');
+    expect(text).toContain('"llmModel": "gpt-4o-mini"');
+  });
+
+  it('never includes the service api key', async () => {
+    const { tool } = harness();
+    const text = textOf(await tool.getKnowledgeStatus({}, null, operator()));
+    expect(text).not.toContain(API_KEY);
+    expect(text).not.toContain('apiKey');
+  });
+
+  it('does not probe health without a URL, and reports unhealthy', async () => {
+    const { tool, config, lightrag } = harness();
+    config.resolve.mockResolvedValue({
+      url: '',
+      apiKey: '',
+      bucket: '',
+      enabled: false,
+    });
+    const text = textOf(await tool.getKnowledgeStatus({}, null, operator()));
+    expect(lightrag.health).not.toHaveBeenCalled();
+    expect(text).toContain('"hasUrl": false');
+    expect(text).toContain('"hasBucket": false');
+    expect(text).toContain('"isHealthy": false');
+    expect(text).toContain('"runtime": null');
+  });
+
+  it('treats a failing health check as unhealthy rather than as an error', async () => {
+    const { tool, lightrag } = harness();
+    lightrag.health.mockRejectedValue(new Error('ECONNREFUSED'));
+    const result = await tool.getKnowledgeStatus({}, null, operator());
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('"isHealthy": false');
+  });
+});
+
+describe('KnowledgeAdminTool — changing', () => {
+  it('creates a base with the fields POST knowledges takes', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.createKnowledge(
+        { name: 'Shipping', description: 'Carriers and delivery times' },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.create).toHaveBeenCalledWith({
+      name: 'Shipping',
+      description: 'Carriers and delivery times',
+    });
+    expect(text).toContain('"id": "kb-2"');
+    expect(text).toContain('Shipping');
+  });
+
+  it('refuses to create when the service is not configured', async () => {
+    const { tool, service, config } = harness();
+    config.isEnabled.mockResolvedValue(false);
+    const result = await tool.createKnowledge(
+      { name: 'Shipping' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(service.create).not.toHaveBeenCalled();
+  });
+
+  it('updates only what was passed', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.updateKnowledge(
+        { id: 'kb-1', name: 'Returns & refunds' },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.update).toHaveBeenCalledWith('kb-1', {
+      name: 'Returns & refunds',
+      description: undefined,
+    });
+    expect(text).toContain('Returns & refunds');
+  });
+
+  it('lets a null description clear it', async () => {
+    const { tool, service } = harness();
+    await tool.updateKnowledge(
+      { id: 'kb-1', description: null },
+      null,
+      operator(),
+    );
+    expect(service.update).toHaveBeenCalledWith('kb-1', {
+      name: undefined,
+      description: null,
+    });
+  });
+
+  it('refuses an update that changes nothing without touching the service', async () => {
+    const { tool, service } = harness();
+    const result = await tool.updateKnowledge({ id: 'kb-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Nothing to change');
+    expect(service.update).not.toHaveBeenCalled();
+  });
+
+  it('reports a missing base on update', async () => {
+    const { tool, service } = harness();
+    service.update.mockRejectedValue(
+      new NotFoundException('Knowledge kb-9 not found'),
+    );
+    const text = textOf(
+      await tool.updateKnowledge({ id: 'kb-9', name: 'x' }, null, operator()),
+    );
+    expect(text).toContain('kb-9 not found');
+    expect(text).toContain('list_knowledges');
+  });
+
+  it('starts an index run and says where to watch it', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.indexKnowledge({ id: 'kb-1' }, null, operator()),
+    );
+    expect(service.startIndex).toHaveBeenCalledWith('kb-1');
+    expect(text).toContain('Indexing started');
+    expect(text).toContain('get_knowledge_overview');
+  });
+
+  it("surfaces the service's refusal when a run is already going", async () => {
+    const { tool, service } = harness();
+    service.startIndex.mockRejectedValue(
+      new ConflictException(
+        'Knowledge kb-1 is already being indexed (started 3 min ago).',
+      ),
+    );
+    const result = await tool.indexKnowledge({ id: 'kb-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('already being indexed');
+  });
+
+  it('reports a missing base on index', async () => {
+    const { tool, service } = harness();
+    service.startIndex.mockRejectedValue(
+      new NotFoundException('Knowledge kb-9 not found'),
+    );
+    const text = textOf(
+      await tool.indexKnowledge({ id: 'kb-9' }, null, operator()),
+    );
+    expect(text).toContain('kb-9 not found');
+    expect(text).toContain('list_knowledges');
+  });
+});
+
+describe('KnowledgeAdminTool — deleting', () => {
+  it('refuses without the confirmation argument and names the base (CLEAN-109)', async () => {
+    const { tool, service } = harness();
+    const result = await tool.deleteKnowledge({ id: 'kb-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('«Returns policy»');
+    expect(textOf(result)).toContain('3 source(s)');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(service.delete).not.toHaveBeenCalled();
+  });
+
+  it('deletes once confirmed and says what agents lose', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.deleteKnowledge(
+        { id: 'kb-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.delete).toHaveBeenCalledWith('kb-1');
+    expect(text).toContain('«Returns policy» (kb-1) deleted');
+    expect(text).toContain('Agents that had it bound');
+  });
+
+  it('reports a wrong id as not found, not as a request for confirmation', async () => {
+    const { tool, service } = harness();
+    service.get.mockRejectedValue(
+      new NotFoundException('Knowledge kb-9 not found'),
+    );
+    const result = await tool.deleteKnowledge({ id: 'kb-9' }, null, operator());
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('kb-9 not found');
+    expect(textOf(result)).toContain('list_knowledges');
+    expect(service.delete).not.toHaveBeenCalled();
+  });
+
+  it("surfaces the service's refusal to delete", async () => {
+    const { tool, service } = harness();
+    service.delete.mockRejectedValue(
+      new ConflictException('Knowledge kb-1 is bound to 2 agent(s).'),
+    );
+    const result = await tool.deleteKnowledge(
+      { id: 'kb-1', confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('bound to 2 agent(s)');
+  });
+
+  it('lets a non-HTTP failure escape, so the MCP layer reports it as an error', async () => {
+    const { tool, service } = harness();
+    service.delete.mockRejectedValue(new Error('database is down'));
+    await expect(
+      tool.deleteKnowledge({ id: 'kb-1', confirm: true }, null, operator()),
+    ).rejects.toThrow('database is down');
+  });
+});
diff --git a/api/src/slices/reins/knowledge/knowledgeAdmin.tool.ts b/api/src/slices/reins/knowledge/knowledgeAdmin.tool.ts
new file mode 100644
index 00000000..4a22aed5
--- /dev/null
+++ b/api/src/slices/reins/knowledge/knowledgeAdmin.tool.ts
@@ -0,0 +1,450 @@
+import {
+  HttpException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { ILlmGateway } from '#/llm/domain';
+import { KnowledgeService } from './domain/knowledge.service';
+import { IKnowledgeConfigGateway } from '../config/domain/knowledgeConfig.gateway';
+import { ILightragClient } from '../lightrag/domain/lightrag.client';
+import { ILightragRuntimeConfig } from '../lightrag/domain/lightrag.types';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** Mirrors `FilterKnowledgeDto` / `GetGraphLabelsDto`, so the tool accepts what the route accepts. */
+const LIST_DEFAULT_PER_PAGE = 50;
+const LIST_MAX_PER_PAGE = 100;
+const LABELS_MAX_LIMIT = 200;
+
+const NOT_CONFIGURED =
+  'The knowledge service is not configured. Call get_knowledge_status to ' +
+  'see what is missing, then set it up in the console under Knowledge.';
+
+/**
+ * Managing knowledge bases from the chat, as the console does (CLEAN-109).
+ *
+ * `knowledge.tool.ts` next door is `query_knowledge`: any agent may ask its
+ * bound bases a question. This class is the other half — creating, indexing,
+ * inspecting and deleting bases — and it is for Ranch operators only, because
+ * a plain agent must never be able to enlarge or empty what it, or another
+ * agent, is allowed to read.
+ *
+ * Every call goes through `KnowledgeService`, the same service
+ * `KnowledgeController` calls, and each tool keeps the controller's guard: the
+ * service must be configured before anything but the list and the status can
+ * answer, exactly as the routes refuse with 503.
+ */
+@Injectable()
+export class KnowledgeAdminTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(KnowledgeAdminTool.name);
+
+  constructor(
+    private readonly service: KnowledgeService,
+    private readonly knowledgeConfig: IKnowledgeConfigGateway,
+    private readonly lightrag: ILightragClient,
+    private readonly llm: ILlmGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  // ─── Reading ─────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'list_knowledges',
+    topic: ToolTopics.Knowledge,
+    title: 'List knowledge bases',
+    template: 'List the knowledge bases',
+    description:
+      'Every knowledge base of this Ranch, paged and searchable by name: ' +
+      'its id, index status, source counts and size. Call this first to ' +
+      'turn a name the person said into the id the other knowledge tools ' +
+      'take. Returns an empty page when the knowledge service is not ' +
+      'configured.',
+    parameters: z.object({
+      search: z
+        .string()
+        .optional()
+        .describe('Substring of the name to filter by'),
+      page: z.number().int().min(1).optional().describe('1-based. Default 1.'),
+      perPage: z
+        .number()
+        .int()
+        .min(1)
+        .max(LIST_MAX_PER_PAGE)
+        .optional()
+        .describe(`Default ${LIST_DEFAULT_PER_PAGE}.`),
+    }),
+  })
+  async listKnowledges(
+    {
+      search,
+      page,
+      perPage,
+    }: { search?: string; page?: number; perPage?: number },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    if (!(await this.knowledgeConfig.isEnabled())) {
+      // The route answers an empty page rather than 503 here, so the console
+      // list renders; the tool does the same and says why it is empty.
+      return ok({
+        items: [],
+        total: 0,
+        page: 1,
+        perPage: perPage ?? LIST_DEFAULT_PER_PAGE,
+        note: NOT_CONFIGURED,
+      });
+    }
+    return ok(await this.service.listPage({ search, page, perPage }));
+  }
+
+  @Tool({
+    name: 'get_knowledge',
+    topic: ToolTopics.Knowledge,
+    title: 'Show a knowledge base',
+    template: 'Show the knowledge base «name»',
+    description:
+      'One knowledge base in full: name, description, index status as ' +
+      'derived from its sources, whether an index run is alive right now, ' +
+      'and the state of its retrieval instance. Resolve the name with ' +
+      'list_knowledges first.',
+    parameters: z.object({
+      id: z.string().describe('Knowledge base id (list_knowledges has them)'),
+    }),
+  })
+  async getKnowledge(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    return this.whenConfigured(id, async () =>
+      ok(await this.service.getWithDerivedStatus(id)),
+    );
+  }
+
+  @Tool({
+    name: 'get_knowledge_overview',
+    topic: ToolTopics.Knowledge,
+    title: 'Source counts and size',
+    template: 'How big is the knowledge base «name» and what is in it?',
+    description:
+      "A knowledge base's sources in numbers: how many there are, how many " +
+      'are indexed, failed for good, being retried or still in the pipeline, ' +
+      'the split by type (file, url, text) and the total stored size in ' +
+      'bytes. Read this before deciding whether to index or to add sources.',
+    parameters: z.object({
+      id: z.string().describe('Knowledge base id (list_knowledges has them)'),
+    }),
+  })
+  async getKnowledgeOverview(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    return this.whenConfigured(id, async () =>
+      ok(await this.service.getOverview(id)),
+    );
+  }
+
+  @Tool({
+    name: 'list_knowledge_graph_labels',
+    topic: ToolTopics.Knowledge,
+    title: 'Entity labels',
+    template: 'Which entity labels does the knowledge base «name» have?',
+    description:
+      'The entity labels the index extracted from a knowledge base, with a ' +
+      'case-insensitive filter and a cap. `total` counts every match and ' +
+      '`truncated` says whether the cap cut the list. Empty labels on a ' +
+      'base with sources usually means it has not been indexed yet.',
+    parameters: z.object({
+      id: z.string().describe('Knowledge base id (list_knowledges has them)'),
+      search: z
+        .string()
+        .optional()
+        .describe('Case-insensitive substring of the label'),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(LABELS_MAX_LIMIT)
+        .optional()
+        .describe('Default 50.'),
+    }),
+  })
+  async listKnowledgeGraphLabels(
+    { id, search, limit }: { id: string; search?: string; limit?: number },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    return this.whenConfigured(id, async () =>
+      ok(await this.service.getGraphLabels(id, { search, limit })),
+    );
+  }
+
+  @Tool({
+    name: 'get_knowledge_status',
+    topic: ToolTopics.Knowledge,
+    title: 'Knowledge service status',
+    template: 'Is the knowledge service ready?',
+    description:
+      'Whether the knowledge service can be used and, if not, what is ' +
+      'missing: a chat and an embedding credential, the service URL, the ' +
+      'storage bucket, a chat credential selected for it, and whether the ' +
+      'retrieval service answers its health check. `runtime` is what the ' +
+      'running retrieval service reports about its own models. Read this ' +
+      'when any knowledge tool says the service is not configured.',
+    parameters: z.object({}),
+  })
+  async getKnowledgeStatus(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const [config, selected, hasChat, hasEmbedding] = await Promise.all([
+      this.knowledgeConfig.resolve(),
+      this.knowledgeConfig.getSelectedCredentialIds(),
+      this.llm.hasCredentialWithCapability('chat'),
+      this.llm.hasCredentialWithCapability('embedding'),
+    ]);
+
+    let isHealthy = false;
+    let runtime: ILightragRuntimeConfig | null = null;
+    if (config.url.length > 0) {
+      try {
+        const health = await this.lightrag.health();
+        isHealthy = health.ok;
+        runtime = health.configuration;
+      } catch {
+        isHealthy = false;
+      }
+    }
+
+    // Same shape as GET knowledges/status. `config` itself never leaves this
+    // method: it carries the service api key.
+    return ok({
+      enabled: config.enabled,
+      setup: {
+        hasChatCredential: hasChat,
+        hasEmbeddingCredential: hasEmbedding,
+        hasUrl: config.url.length > 0,
+        hasBucket: config.bucket.length > 0,
+        hasCredentialsSelected: selected.chat !== null,
+        isHealthy,
+      },
+      runtime,
+    });
+  }
+
+  // ─── Changing ────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'create_knowledge',
+    topic: ToolTopics.Knowledge,
+    title: 'Create a knowledge base',
+    template: 'Create a knowledge base «name» described as «description»',
+    description:
+      'Create an empty knowledge base. When per-base retrieval instances ' +
+      'are enabled this also provisions its instance, which the result ' +
+      'reports under instanceState. Returns the new base with its id; add ' +
+      'sources with add_knowledge_source next, then index_knowledge.',
+    parameters: z.object({
+      name: z.string().min(1),
+      description: z
+        .string()
+        .optional()
+        .describe(
+          'What the base is for — agents read it to decide when to search',
+        ),
+    }),
+  })
+  async createKnowledge(
+    { name, description }: { name: string; description?: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    if (!(await this.knowledgeConfig.isEnabled())) return err(NOT_CONFIGURED);
+    return this.surfacingRefusals(async () => {
+      const created = await this.service.create({ name, description });
+      this.logger.log(
+        `Knowledge base created through MCP: id=${created.id} name=${created.name}`,
+      );
+      return ok(created);
+    });
+  }
+
+  @Tool({
+    name: 'update_knowledge',
+    topic: ToolTopics.Knowledge,
+    title: 'Update a knowledge base',
+    template: 'Change the knowledge base «name»: «what to change»',
+    description:
+      'Rename a knowledge base or change its description. Pass only what ' +
+      'changes; a null description clears it. Content is not touched — use ' +
+      'the source tools for that. Returns the updated base.',
+    parameters: z.object({
+      id: z.string().describe('Knowledge base id (list_knowledges has them)'),
+      name: z.string().min(1).optional(),
+      description: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('New description; null clears it'),
+    }),
+  })
+  async updateKnowledge(
+    {
+      id,
+      name,
+      description,
+    }: { id: string; name?: string; description?: string | null },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    if (name === undefined && description === undefined) {
+      return err('Nothing to change: pass a name and/or a description.');
+    }
+    return this.whenConfigured(id, async () =>
+      ok(await this.service.update(id, { name, description })),
+    );
+  }
+
+  @Tool({
+    name: 'index_knowledge',
+    topic: ToolTopics.Knowledge,
+    title: 'Start indexing',
+    template: 'Index the knowledge base «name»',
+    description:
+      'Start an index run over every source of a knowledge base, in the ' +
+      'background: sources never processed are ingested and failed ones are ' +
+      'retried, so this is also the way to retry a failed run. Returns at ' +
+      'once; watch progress with get_knowledge (indexStatus) and ' +
+      'get_knowledge_overview (counts). Refused while a run that has not ' +
+      'exhausted its time budget is still going.',
+    parameters: z.object({
+      id: z.string().describe('Knowledge base id (list_knowledges has them)'),
+    }),
+  })
+  async indexKnowledge(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    return this.whenConfigured(id, async () => {
+      await this.service.startIndex(id);
+      this.logger.log(`Index run started through MCP: knowledge=${id}`);
+      return ok(
+        `Indexing started for knowledge base ${id}. It runs in the ` +
+          'background: get_knowledge shows indexStatus and ' +
+          'get_knowledge_overview the per-source counts as it progresses.',
+      );
+    });
+  }
+
+  @Tool({
+    name: 'delete_knowledge',
+    topic: ToolTopics.Knowledge,
+    title: 'Delete a knowledge base',
+    template: 'Delete the knowledge base «name»',
+    destructive: true,
+    description:
+      'Delete a knowledge base with all of its sources, its index and its ' +
+      'retrieval instance. Not reversible: the stored files and the ' +
+      'extracted graph are gone. Agents bound to it simply stop finding it ' +
+      '— bind them to another base afterwards if they need one. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string().describe('Knowledge base id (list_knowledges has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteKnowledge(
+    args: { id: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { id } = args;
+    return this.whenConfigured(id, async () => {
+      // Resolved before the confirmation check, so a wrong id is reported as
+      // "not found" instead of as a request for confirmation.
+      const base = await this.service.get(id);
+      const refusal = confirmed(
+        args,
+        `delete the knowledge base «${base.name}» with its ${base.sourceCount} ` +
+          'source(s), its index and its retrieval instance',
+      );
+      if (refusal) return refusal;
+      await this.service.delete(id);
+      this.logger.log(
+        `Knowledge base deleted through MCP: id=${id} name=${base.name}`,
+      );
+      return ok(
+        `Knowledge base «${base.name}» (${id}) deleted, with its ` +
+          `${base.sourceCount} source(s) and its index. Agents that had it ` +
+          'bound no longer search it; use update_agent to bind them to ' +
+          'another base if they need one.',
+      );
+    });
+  }
+
+  // ─── Plumbing ────────────────────────────────────────────────────────
+
+  /**
+   * The controller's `requireEnabled()` plus the two refusals every
+   * per-base route can produce: the id does not exist, or the service
+   * refuses the operation (already indexing, instance not ready). Both come
+   * back as text with the next move; anything else is a real failure and
+   * escapes to the MCP layer as before.
+   */
+  private async whenConfigured(
+    id: string,
+    run: () => Promise<ToolResult>,
+  ): Promise<ToolResult> {
+    if (!(await this.knowledgeConfig.isEnabled())) return err(NOT_CONFIGURED);
+    return this.surfacingRefusals(run, id);
+  }
+
+  private async surfacingRefusals(
+    run: () => Promise<ToolResult>,
+    id?: string,
+  ): Promise<ToolResult> {
+    try {
+      return await run();
+    } catch (e) {
+      if (e instanceof NotFoundException && id !== undefined) {
+        return ok({
+          error: `Knowledge base ${id} not found — call list_knowledges to find the id`,
+        });
+      }
+      if (e instanceof HttpException) return err(e.message);
+      throw e;
+    }
+  }
+}
diff --git a/api/src/slices/reins/source/source.module.ts b/api/src/slices/reins/source/source.module.ts
index c6961246..08879e4d 100644
--- a/api/src/slices/reins/source/source.module.ts
+++ b/api/src/slices/reins/source/source.module.ts
@@ -10,6 +10,7 @@ import { ISourceGateway } from './domain/source.gateway';
 import { ImportJobRegistry } from './domain/importJob.registry';
 import { SourceGateway } from './data/source.gateway';
 import { SourceMapper } from './data/source.mapper';
+import { SourceTool } from './source.tool';
 
 @Module({
   imports: [
@@ -23,6 +24,7 @@ import { SourceMapper } from './data/source.mapper';
   providers: [
     SourceMapper,
     SourceService,
+    SourceTool,
     ImportJobRegistry,
     { provide: ISourceGateway, useClass: SourceGateway },
   ],
diff --git a/api/src/slices/reins/source/source.tool.spec.ts b/api/src/slices/reins/source/source.tool.spec.ts
new file mode 100644
index 00000000..d201f41d
--- /dev/null
+++ b/api/src/slices/reins/source/source.tool.spec.ts
@@ -0,0 +1,456 @@
+import {
+  BadRequestException,
+  ForbiddenException,
+  NotFoundException,
+} from '@nestjs/common';
+import type { Request } from 'express';
+import { SourceTool } from './source.tool';
+import type { SourceService } from './domain/source.service';
+import type { ISourceGateway } from './domain/source.gateway';
+import type { IImportJob, ISourceData } from './domain/source.types';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * These tools let an agent decide what other agents answer from. What
+ * matters most is therefore that a plain agent cannot see or call them,
+ * that a delete names the row and asks before it acts, and that every
+ * refusal is a sentence naming the next move.
+ */
+const source = (overrides: Partial<ISourceData> = {}): ISourceData => ({
+  id: 'src-1',
+  knowledgeId: 'kb-1',
+  type: 'url',
+  name: 'Returns policy',
+  url: 'https://shop.example/returns',
+  mimeType: null,
+  content: null,
+  sizeBytes: null,
+  indexed: false,
+  indexStatus: 'pending',
+  indexState: 'queued',
+  indexError: null,
+  indexedAt: null,
+  indexAttempts: 0,
+  indexRetryAt: null,
+  textState: 'none',
+  textUrl: null,
+  textError: null,
+  createdAt: new Date('2026-09-17T10:00:00.000Z'),
+  updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  ...overrides,
+});
+
+const importJob = (): IImportJob => ({
+  id: 'job-1',
+  knowledgeId: 'kb-1',
+  kind: 'archive',
+  status: 'running',
+  detected: 12,
+  added: 4,
+  skipped: 1,
+  failed: 0,
+  errors: [],
+  startedAt: new Date('2026-09-17T10:00:00.000Z'),
+  finishedAt: null,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: SourceTool;
+  service: jest.Mocked<
+    Pick<
+      SourceService,
+      | 'findPage'
+      | 'listImports'
+      | 'addUrl'
+      | 'addText'
+      | 'addFromSitemap'
+      | 'reindexSource'
+      | 'reextractSource'
+      | 'delete'
+    >
+  >;
+  gateway: jest.Mocked<Pick<ISourceGateway, 'findById'>>;
+}
+
+function harness(): Harness {
+  const service = {
+    findPage: jest.fn().mockResolvedValue({
+      items: [source()],
+      total: 1,
+      page: 1,
+      perPage: 50,
+    }),
+    listImports: jest.fn().mockReturnValue([importJob()]),
+    addUrl: jest.fn().mockResolvedValue(source()),
+    addText: jest.fn().mockResolvedValue(
+      source({
+        id: 'src-2',
+        type: 'text',
+        name: 'FAQ',
+        url: null,
+        content: 'Q: … A: …',
+      }),
+    ),
+    addFromSitemap: jest.fn().mockResolvedValue({ added: 3, discovered: 5 }),
+    reindexSource: jest.fn().mockResolvedValue(undefined),
+    reextractSource: jest.fn().mockResolvedValue(undefined),
+    delete: jest.fn().mockResolvedValue(undefined),
+  } as unknown as Harness['service'];
+
+  const gateway = {
+    findById: jest.fn().mockResolvedValue(source()),
+  } as unknown as Harness['gateway'];
+
+  const tool = new SourceTool(
+    service as unknown as SourceService,
+    gateway as unknown as ISourceGateway,
+  );
+  return { tool, service, gateway };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('SourceTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, service } = harness();
+    await expect(
+      tool.addKnowledgeSource(
+        {
+          knowledgeId: 'kb-1',
+          kind: 'url',
+          name: 'x',
+          url: 'https://x.example',
+        },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(service.addUrl).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool } = harness();
+    await expect(
+      tool.listKnowledgeSources({ knowledgeId: 'kb-1' }, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('SourceTool — reading', () => {
+  it('lists a page with the controller defaults', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.listKnowledgeSources(
+        { knowledgeId: 'kb-1' },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.findPage).toHaveBeenCalledWith('kb-1', {
+      page: 1,
+      perPage: 50,
+      search: undefined,
+      status: undefined,
+      type: undefined,
+    });
+    expect(text).toContain('Returns policy');
+    expect(text).toContain('"total": 1');
+  });
+
+  it('passes the filter and paging through', async () => {
+    const { tool, service } = harness();
+    await tool.listKnowledgeSources(
+      {
+        knowledgeId: 'kb-1',
+        page: 2,
+        perPage: 10,
+        search: 'return',
+        status: 'failed',
+        type: 'url',
+      },
+      null,
+      operator(),
+    );
+    expect(service.findPage).toHaveBeenCalledWith('kb-1', {
+      page: 2,
+      perPage: 10,
+      search: 'return',
+      status: 'failed',
+      type: 'url',
+    });
+  });
+
+  it('lists the background imports of a base', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.listKnowledgeImports(
+        { knowledgeId: 'kb-1' },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.listImports).toHaveBeenCalledWith('kb-1');
+    expect(text).toContain('job-1');
+    expect(text).toContain('"status": "running"');
+  });
+});
+
+describe('SourceTool — adding', () => {
+  it('adds a url source the way the controller does', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.addKnowledgeSource(
+        {
+          knowledgeId: 'kb-1',
+          kind: 'url',
+          name: 'Returns policy',
+          url: 'https://shop.example/returns',
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.addUrl).toHaveBeenCalledWith('kb-1', {
+      name: 'Returns policy',
+      url: 'https://shop.example/returns',
+    });
+    expect(service.addText).not.toHaveBeenCalled();
+    expect(text).toContain('src-1');
+  });
+
+  it('adds a text source, mapping text to the content field', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.addKnowledgeSource(
+        { knowledgeId: 'kb-1', kind: 'text', name: 'FAQ', text: 'Q: … A: …' },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.addText).toHaveBeenCalledWith('kb-1', {
+      name: 'FAQ',
+      content: 'Q: … A: …',
+    });
+    expect(text).toContain('src-2');
+  });
+
+  it('refuses a url source without a url, as the controller refuses it', async () => {
+    const { tool, service } = harness();
+    const result = await tool.addKnowledgeSource(
+      { knowledgeId: 'kb-1', kind: 'url', name: 'x' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('url is required');
+    expect(service.addUrl).not.toHaveBeenCalled();
+  });
+
+  it('refuses a text source without text', async () => {
+    const { tool, service } = harness();
+    const result = await tool.addKnowledgeSource(
+      { knowledgeId: 'kb-1', kind: 'text', name: 'x' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('text is required');
+    expect(service.addText).not.toHaveBeenCalled();
+  });
+
+  it('adds every page of a sitemap under a prefix', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.addKnowledgeSourcesFromSitemap(
+        {
+          knowledgeId: 'kb-1',
+          sitemapUrl: 'https://docs.example/sitemap.xml',
+          urlPrefix: 'https://docs.example/guide/',
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.addFromSitemap).toHaveBeenCalledWith(
+      'kb-1',
+      'https://docs.example/sitemap.xml',
+      'https://docs.example/guide/',
+    );
+    expect(text).toContain('"added": 3');
+    expect(text).toContain('"discovered": 5');
+  });
+
+  it('relays a sitemap that cannot be read as a refusal with the reason', async () => {
+    const { tool, service } = harness();
+    service.addFromSitemap.mockRejectedValue(
+      new BadRequestException('Sitemap returned 404'),
+    );
+    const result = await tool.addKnowledgeSourcesFromSitemap(
+      { knowledgeId: 'kb-1', sitemapUrl: 'https://docs.example/nope.xml' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Sitemap returned 404');
+  });
+});
+
+describe('SourceTool — per-source actions', () => {
+  it('reindexes a source of the base', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.reindexKnowledgeSource(
+        { knowledgeId: 'kb-1', sourceId: 'src-1' },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.reindexSource).toHaveBeenCalledWith('kb-1', 'src-1');
+    expect(text).toContain('Returns policy');
+    expect(text).toContain('list_knowledge_sources');
+  });
+
+  it('reports an unknown source and names the list to call', async () => {
+    const { tool, service, gateway } = harness();
+    gateway.findById.mockResolvedValue(null);
+    const result = await tool.reindexKnowledgeSource(
+      { knowledgeId: 'kb-1', sourceId: 'nope' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(textOf(result)).toContain('list_knowledge_sources');
+    expect(service.reindexSource).not.toHaveBeenCalled();
+  });
+
+  it('treats a source of another base as not found', async () => {
+    const { tool, service } = harness();
+    const result = await tool.reindexKnowledgeSource(
+      { knowledgeId: 'kb-other', sourceId: 'src-1' },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('not found');
+    expect(textOf(result)).toContain('kb-other');
+    expect(service.reindexSource).not.toHaveBeenCalled();
+  });
+
+  it('schedules extraction for a PDF source', async () => {
+    const { tool, service, gateway } = harness();
+    gateway.findById.mockResolvedValue(
+      source({ type: 'file', mimeType: 'application/pdf', name: 'scan.pdf' }),
+    );
+    const text = textOf(
+      await tool.extractKnowledgeSource(
+        { knowledgeId: 'kb-1', sourceId: 'src-1' },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.reextractSource).toHaveBeenCalledWith('kb-1', 'src-1');
+    expect(text).toContain('scan.pdf');
+    expect(text).toContain('textState');
+  });
+
+  it('relays the service refusal for a source that is not a PDF', async () => {
+    const { tool, service } = harness();
+    service.reextractSource.mockRejectedValue(
+      new BadRequestException('Only PDF file sources can be re-extracted'),
+    );
+    const result = await tool.extractKnowledgeSource(
+      { knowledgeId: 'kb-1', sourceId: 'src-1' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Only PDF file sources');
+  });
+
+  it('reports an unknown source for extraction without calling the service', async () => {
+    const { tool, service, gateway } = harness();
+    gateway.findById.mockResolvedValue(null);
+    const result = await tool.extractKnowledgeSource(
+      { knowledgeId: 'kb-1', sourceId: 'nope' },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('not found');
+    expect(service.reextractSource).not.toHaveBeenCalled();
+  });
+});
+
+describe('SourceTool — deleting', () => {
+  it('refuses without the confirmation argument and touches nothing', async () => {
+    const { tool, service } = harness();
+    const result = await tool.deleteKnowledgeSource(
+      { knowledgeId: 'kb-1', sourceId: 'src-1' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(textOf(result)).toContain('«Returns policy»');
+    expect(service.delete).not.toHaveBeenCalled();
+  });
+
+  it('reports not found before asking for a confirmation', async () => {
+    const { tool, service, gateway } = harness();
+    gateway.findById.mockResolvedValue(null);
+    const result = await tool.deleteKnowledgeSource(
+      { knowledgeId: 'kb-1', sourceId: 'nope' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(service.delete).not.toHaveBeenCalled();
+  });
+
+  it('deletes once confirmed and names what went', async () => {
+    const { tool, service } = harness();
+    const text = textOf(
+      await tool.deleteKnowledgeSource(
+        { knowledgeId: 'kb-1', sourceId: 'src-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(service.delete).toHaveBeenCalledWith('src-1');
+    expect(text).toContain('"deleted": true');
+    expect(text).toContain('Returns policy');
+  });
+
+  it('reports a source that vanished between the read and the delete', async () => {
+    const { tool, service } = harness();
+    service.delete.mockRejectedValue(
+      new NotFoundException('Source src-1 not found'),
+    );
+    const result = await tool.deleteKnowledgeSource(
+      { knowledgeId: 'kb-1', sourceId: 'src-1', confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+  });
+});
diff --git a/api/src/slices/reins/source/source.tool.ts b/api/src/slices/reins/source/source.tool.ts
new file mode 100644
index 00000000..cb5f0469
--- /dev/null
+++ b/api/src/slices/reins/source/source.tool.ts
@@ -0,0 +1,452 @@
+import {
+  BadRequestException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { SourceService } from './domain/source.service';
+import { ISourceGateway } from './domain/source.gateway';
+import type { ISourceData } from './domain/source.types';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+// The same defaults and ceiling `SourceController.list` / FilterSourcesDto use.
+const DEFAULT_PAGE = 1;
+const DEFAULT_PER_PAGE = 50;
+const MAX_PER_PAGE = 200;
+
+const SOURCE_INDEX_STATUSES = [
+  'indexed',
+  'pending',
+  'retrying',
+  'failed',
+] as const;
+const SOURCE_TYPES = ['file', 'url', 'text'] as const;
+
+const SOURCE_NOT_FOUND = (sourceId: string, knowledgeId: string) =>
+  ok({
+    error:
+      `Source ${sourceId} not found in knowledge base ${knowledgeId} — call ` +
+      'list_knowledge_sources to find the id, or list_knowledges for the base',
+  });
+
+/**
+ * The source-level half of the Knowledge section (CLEAN-109): what the
+ * console does on a knowledge base's Sources tab, from the chat. The
+ * base-level tools (`list_knowledges`, `create_knowledge`, `index_knowledge`,
+ * …) live next door in `knowledge/knowledgeAdmin.tool.ts`.
+ *
+ * Every call goes through `SourceService`, the one thing `SourceController`
+ * injects, with the controller's own argument mapping and validation (a url
+ * source needs a url, a text source needs text). File and archive uploads
+ * stay console-only: they carry bytes from a person's machine, which a chat
+ * cannot supply. `add_knowledge_source` covers what an agent can produce —
+ * text and URLs.
+ *
+ * `ISourceGateway` is injected on top of the service for one thing: to read
+ * a row before acting on it, so a not-found is reported as a sentence the
+ * model can act on and a delete can name what it is about to remove.
+ *
+ * Operator-only: a plain agent must not be able to feed documents into a
+ * base other agents answer from, nor delete what they answer from.
+ */
+@Injectable()
+export class SourceTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(SourceTool.name);
+
+  constructor(
+    private readonly service: SourceService,
+    private readonly sources: ISourceGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  /**
+   * The row, or null when it does not exist or belongs to another base. The
+   * service checks the same pair itself; this is the friendly version.
+   */
+  private async resolve(
+    knowledgeId: string,
+    sourceId: string,
+  ): Promise<ISourceData | null> {
+    const source = await this.sources.findById(sourceId);
+    if (!source || source.knowledgeId !== knowledgeId) return null;
+    return source;
+  }
+
+  // ─── Reading ─────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'list_knowledge_sources',
+    topic: ToolTopics.Knowledge,
+    title: 'List sources',
+    template: 'List the sources of the knowledge base «name»',
+    description:
+      'List the sources of one knowledge base, one page at a time: each ' +
+      'with its id, name, type (file, url or text), index status ' +
+      '(indexed, pending, retrying, failed) and any index error. Takes the ' +
+      'knowledge id — resolve a name with list_knowledges first. Filter by ' +
+      'a name substring, a status or a type to find the rows to reindex or ' +
+      'delete. Returns `items`, `total`, `page` and `perPage`.',
+    parameters: z.object({
+      knowledgeId: z
+        .string()
+        .describe('Knowledge base id (list_knowledges has them)'),
+      page: z.number().int().min(1).optional().describe('Page number, from 1'),
+      perPage: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_PER_PAGE)
+        .optional()
+        .describe(
+          `Rows per page (default ${DEFAULT_PER_PAGE}, max ${MAX_PER_PAGE})`,
+        ),
+      search: z
+        .string()
+        .optional()
+        .describe('Case-insensitive substring match on the source name'),
+      status: z
+        .enum(SOURCE_INDEX_STATUSES)
+        .optional()
+        .describe('Only sources in this index status'),
+      type: z
+        .enum(SOURCE_TYPES)
+        .optional()
+        .describe('Only sources of this type'),
+    }),
+  })
+  async listKnowledgeSources(
+    args: {
+      knowledgeId: string;
+      page?: number;
+      perPage?: number;
+      search?: string;
+      status?: (typeof SOURCE_INDEX_STATUSES)[number];
+      type?: (typeof SOURCE_TYPES)[number];
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const page = await this.service.findPage(args.knowledgeId, {
+      page: args.page ?? DEFAULT_PAGE,
+      perPage: args.perPage ?? DEFAULT_PER_PAGE,
+      search: args.search,
+      status: args.status,
+      type: args.type,
+    });
+    return ok(page);
+  }
+
+  @Tool({
+    name: 'list_knowledge_imports',
+    topic: ToolTopics.Knowledge,
+    title: 'Imports in progress',
+    template: 'Are any imports running for the knowledge base «name»?',
+    description:
+      'List the background jobs of one knowledge base: archive imports and ' +
+      'text extractions, running and finished within the last hour, each ' +
+      'with its status and counts (detected, added, skipped, failed) and ' +
+      'the first failures. Takes the knowledge id — resolve a name with ' +
+      'list_knowledges first. An empty list means nothing is running and ' +
+      'nothing finished recently.',
+    parameters: z.object({
+      knowledgeId: z
+        .string()
+        .describe('Knowledge base id (list_knowledges has them)'),
+    }),
+  })
+  async listKnowledgeImports(
+    { knowledgeId }: { knowledgeId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    return ok(this.service.listImports(knowledgeId));
+  }
+
+  // ─── Adding ──────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'add_knowledge_source',
+    topic: ToolTopics.Knowledge,
+    title: 'Add a URL or text source',
+    template: 'Add «url or text» to the knowledge base «name»',
+    description:
+      'Add one source to a knowledge base: a web page by URL (kind "url") ' +
+      'or a piece of text you have (kind "text"), with a display name. ' +
+      'Takes the knowledge id — resolve a name with list_knowledges first. ' +
+      'Returns the new source row; it is queued, not indexed yet — run ' +
+      'index_knowledge on the base (or reindex_knowledge_source on the row) ' +
+      'to make it searchable. File and archive uploads stay console-only: ' +
+      'ask the person to upload those from the Sources tab.',
+    parameters: z.object({
+      knowledgeId: z
+        .string()
+        .describe('Knowledge base id (list_knowledges has them)'),
+      kind: z
+        .enum(['url', 'text'])
+        .describe('What the source is: a web page or text'),
+      name: z.string().min(1).describe('Display name for the source'),
+      url: z
+        .string()
+        .url()
+        .optional()
+        .describe('The page address (kind "url")'),
+      text: z.string().optional().describe('The text body (kind "text")'),
+    }),
+  })
+  async addKnowledgeSource(
+    args: {
+      knowledgeId: string;
+      kind: 'url' | 'text';
+      name: string;
+      url?: string;
+      text?: string;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { knowledgeId, kind, name } = args;
+    // Same checks as SourceController.add, as tool refusals rather than 400s.
+    if (kind === 'url') {
+      if (!args.url) return err('url is required when kind is "url"');
+      const created = await this.service.addUrl(knowledgeId, {
+        name,
+        url: args.url,
+      });
+      this.logger.log(
+        `Url source added through MCP: ${created.name} (${created.id})`,
+      );
+      return ok(created);
+    }
+    if (!args.text) return err('text is required when kind is "text"');
+    const created = await this.service.addText(knowledgeId, {
+      name,
+      content: args.text,
+    });
+    this.logger.log(
+      `Text source added through MCP: ${created.name} (${created.id})`,
+    );
+    return ok(created);
+  }
+
+  @Tool({
+    name: 'add_knowledge_sources_from_sitemap',
+    topic: ToolTopics.Knowledge,
+    title: 'Add URLs from a sitemap',
+    template: 'Add every page of «sitemap url» to the knowledge base «name»',
+    description:
+      'Fetch a sitemap.xml (or a sitemap index) and add one url source per ' +
+      'page it lists, optionally only the pages under a URL prefix. Pages ' +
+      'already present as url sources are skipped, so running it twice does ' +
+      'not duplicate them. Takes the knowledge id — resolve a name with ' +
+      'list_knowledges first. Returns `discovered` (pages in the sitemap) ' +
+      'and `added` (new rows). Nothing is indexed yet — run index_knowledge ' +
+      'on the base afterwards. A sitemap that cannot be fetched or parsed ' +
+      'is reported as an error with the reason.',
+    parameters: z.object({
+      knowledgeId: z
+        .string()
+        .describe('Knowledge base id (list_knowledges has them)'),
+      sitemapUrl: z
+        .string()
+        .url()
+        .describe('Address of the sitemap.xml or sitemap index'),
+      urlPrefix: z
+        .string()
+        .optional()
+        .describe(
+          'Only add pages whose URL starts with this, e.g. https://docs.example.com/guide/',
+        ),
+    }),
+  })
+  async addKnowledgeSourcesFromSitemap(
+    args: { knowledgeId: string; sitemapUrl: string; urlPrefix?: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    try {
+      const result = await this.service.addFromSitemap(
+        args.knowledgeId,
+        args.sitemapUrl,
+        args.urlPrefix,
+      );
+      this.logger.log(
+        `Sitemap ${args.sitemapUrl} added ${result.added}/${result.discovered} ` +
+          `sources to knowledge ${args.knowledgeId} through MCP`,
+      );
+      return ok(result);
+    } catch (e) {
+      // The service turns a sitemap fetch/parse failure into a 400; the
+      // model needs the reason, not a stack, to tell the person what to fix.
+      if (e instanceof BadRequestException) return err(e.message);
+      throw e;
+    }
+  }
+
+  // ─── Per-source actions ──────────────────────────────────────────────
+
+  @Tool({
+    name: 'reindex_knowledge_source',
+    topic: ToolTopics.Knowledge,
+    title: 'Retry one source',
+    template: 'Reindex the source «name» in the knowledge base «base»',
+    description:
+      'Requeue one source and re-ingest it, without touching the rest of ' +
+      'the base — for a row whose status reads failed, or whose content ' +
+      'changed. Takes the knowledge id and the source id — resolve names ' +
+      'with list_knowledges and list_knowledge_sources first. Indexing runs ' +
+      'in the background; check the row with list_knowledge_sources later ' +
+      '(its indexState goes queued → processing → indexed or failed).',
+    parameters: z.object({
+      knowledgeId: z
+        .string()
+        .describe('Knowledge base id (list_knowledges has them)'),
+      sourceId: z
+        .string()
+        .describe('Source id (list_knowledge_sources has them)'),
+    }),
+  })
+  async reindexKnowledgeSource(
+    { knowledgeId, sourceId }: { knowledgeId: string; sourceId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const source = await this.resolve(knowledgeId, sourceId);
+    if (!source) return SOURCE_NOT_FOUND(sourceId, knowledgeId);
+    await this.service.reindexSource(knowledgeId, sourceId);
+    return ok({
+      ok: true,
+      message:
+        `Source «${source.name}» requeued for indexing. Check its status ` +
+        'with list_knowledge_sources in a moment.',
+    });
+  }
+
+  @Tool({
+    name: 'extract_knowledge_source',
+    topic: ToolTopics.Knowledge,
+    title: 'Re-extract a scanned PDF',
+    template: 'Re-run text extraction for «source» in «base»',
+    description:
+      'Re-run text extraction for one PDF file source: probes it for a ' +
+      'text layer and, if it has none, sends it to OCR in the background. ' +
+      'Only PDF file sources qualify; the call says so otherwise. Takes ' +
+      'the knowledge id and the source id — resolve names with ' +
+      'list_knowledges and list_knowledge_sources first. Progress shows on ' +
+      "the row's textState (pending → ready or failed); once it reads " +
+      'ready, reindex_knowledge_source makes the text searchable.',
+    parameters: z.object({
+      knowledgeId: z
+        .string()
+        .describe('Knowledge base id (list_knowledges has them)'),
+      sourceId: z
+        .string()
+        .describe('Source id (list_knowledge_sources has them)'),
+    }),
+  })
+  async extractKnowledgeSource(
+    { knowledgeId, sourceId }: { knowledgeId: string; sourceId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const source = await this.resolve(knowledgeId, sourceId);
+    if (!source) return SOURCE_NOT_FOUND(sourceId, knowledgeId);
+    try {
+      await this.service.reextractSource(knowledgeId, sourceId);
+    } catch (e) {
+      // "Only PDF file sources can be re-extracted" — a refusal to relay,
+      // not a failure.
+      if (e instanceof BadRequestException) return err(e.message);
+      throw e;
+    }
+    return ok({
+      ok: true,
+      message:
+        `Text extraction scheduled for «${source.name}». Check its textState ` +
+        'with list_knowledge_sources; reindex it once that reads ready.',
+    });
+  }
+
+  @Tool({
+    name: 'delete_knowledge_source',
+    topic: ToolTopics.Knowledge,
+    title: 'Delete a source',
+    template: 'Delete the source «name» from the knowledge base «base»',
+    destructive: true,
+    description:
+      'Delete one source from a knowledge base: its row, its stored file ' +
+      'if it has one, and its copy in the retrieval index, so agents stop ' +
+      'answering from it. Not reversible — a file source has to be ' +
+      'uploaded again from the console. Takes the knowledge id and the ' +
+      'source id — resolve names with list_knowledges and ' +
+      'list_knowledge_sources first. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      knowledgeId: z
+        .string()
+        .describe('Knowledge base id (list_knowledges has them)'),
+      sourceId: z
+        .string()
+        .describe('Source id (list_knowledge_sources has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteKnowledgeSource(
+    args: { knowledgeId: string; sourceId: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { knowledgeId, sourceId } = args;
+    const source = await this.resolve(knowledgeId, sourceId);
+    if (!source) return SOURCE_NOT_FOUND(sourceId, knowledgeId);
+
+    const refusal = confirmed(
+      args,
+      `delete the ${source.type} source «${source.name}» from knowledge base ${knowledgeId}`,
+    );
+    if (refusal) return refusal;
+
+    try {
+      await this.service.delete(sourceId);
+    } catch (e) {
+      // Gone between the read above and the delete: the outcome the person
+      // asked for, reported as such.
+      if (e instanceof NotFoundException)
+        return SOURCE_NOT_FOUND(sourceId, knowledgeId);
+      throw e;
+    }
+    this.logger.log(`Source deleted through MCP: ${source.name} (${sourceId})`);
+    return ok({
+      deleted: true,
+      id: sourceId,
+      name: source.name,
+      message: `Source «${source.name}» deleted from knowledge base ${knowledgeId}.`,
+    });
+  }
+}
diff --git a/api/src/slices/setting/domain/index.ts b/api/src/slices/setting/domain/index.ts
index c3fe9a25..47c673b5 100644
--- a/api/src/slices/setting/domain/index.ts
+++ b/api/src/slices/setting/domain/index.ts
@@ -1,5 +1,6 @@
 export * from './setting.types';
 export { ISettingGateway } from './setting.gateway';
+export * from './settingCatalog';
 export {
   IInfraConfigGateway,
   type WorkflowProviderTypes,
diff --git a/api/src/slices/setting/domain/settingCatalog.spec.ts b/api/src/slices/setting/domain/settingCatalog.spec.ts
new file mode 100644
index 00000000..28ae9e40
--- /dev/null
+++ b/api/src/slices/setting/domain/settingCatalog.spec.ts
@@ -0,0 +1,78 @@
+import {
+  SETTING_CATALOG,
+  describeSettingCatalog,
+  findSettingDefinition,
+  nearestSettingDefinition,
+} from './settingCatalog';
+
+describe('SETTING_CATALOG', () => {
+  it('is non-empty and every entry is complete', () => {
+    expect(SETTING_CATALOG.length).toBeGreaterThan(0);
+    for (const def of SETTING_CATALOG) {
+      expect(def.group).toBeTruthy();
+      expect(def.name).toBeTruthy();
+      expect(def.description).toBeTruthy();
+      expect(['string', 'json']).toContain(def.valueType);
+      expect(typeof def.restartRequired).toBe('boolean');
+    }
+  });
+
+  it('has no duplicate keys', () => {
+    const keys = SETTING_CATALOG.map((d) => `${d.group}.${d.name}`);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+
+  it('marks every password-type console field as secret', () => {
+    for (const key of [
+      'integrations.github_pat',
+      'integrations.bridle_api_key',
+      'integrations.aws_secret_access_key',
+      'knowledge.api_key',
+    ]) {
+      const [group, name] = key.split('.');
+      expect(findSettingDefinition(group, name)?.secret).toBe(true);
+    }
+  });
+});
+
+describe('describeSettingCatalog', () => {
+  it('mentions every key with its meaning and flags', () => {
+    const text = describeSettingCatalog();
+    for (const def of SETTING_CATALOG) {
+      expect(text).toContain(`${def.group}.${def.name} — ${def.description}`);
+    }
+    expect(text).toContain('[integrations]');
+    expect(text).toContain('(string, restart required)');
+    expect(text).toContain('(json)');
+  });
+});
+
+describe('findSettingDefinition', () => {
+  it('finds an exact key and nothing else', () => {
+    expect(
+      findSettingDefinition('auth', 'registration_enabled')?.valueType,
+    ).toBe('string');
+    expect(findSettingDefinition('auth', 'registration')).toBeNull();
+    expect(findSettingDefinition('nope', 'registration_enabled')).toBeNull();
+  });
+});
+
+describe('nearestSettingDefinition', () => {
+  it('finds an obvious near miss in the same group', () => {
+    expect(nearestSettingDefinition('integrations', 's3_buckt')?.name).toBe(
+      's3_bucket',
+    );
+    expect(nearestSettingDefinition('auth', 'registration')?.name).toBe(
+      'registration_enabled',
+    );
+    expect(nearestSettingDefinition('knowledge', 'ocr_pages')?.name).toBe(
+      'ocr_max_pages',
+    );
+  });
+
+  it('never crosses groups and gives up when nothing overlaps', () => {
+    expect(nearestSettingDefinition('auth', 's3_bucket')).toBeNull();
+    expect(nearestSettingDefinition('integrations', 'zzz')).toBeNull();
+    expect(nearestSettingDefinition('unknown_group', 's3_bucket')).toBeNull();
+  });
+});
diff --git a/api/src/slices/setting/domain/settingCatalog.ts b/api/src/slices/setting/domain/settingCatalog.ts
new file mode 100644
index 00000000..f9c42491
--- /dev/null
+++ b/api/src/slices/setting/domain/settingCatalog.ts
@@ -0,0 +1,455 @@
+import type { SettingValueTypes } from './setting.types';
+
+/**
+ * What a setting means, as the admin console's settings pages present it.
+ *
+ * Settings are free-form `group.name` rows, so an agent asked to "turn off
+ * registration" has no way to learn that the key is `auth.registration_enabled`
+ * — it would guess, and `upsert_setting` would happily save the guess as a
+ * new row nothing reads (CLEAN-109). This catalogue is the list the console
+ * pages under `admin/slices/setting/pages/settings/*.vue` read and write,
+ * plus the `infrastructure` group the API seeds from env at boot. It is
+ * descriptive, not a schema: unknown keys stay allowed, as they are in the
+ * console, and the tools use it to name the nearest known key instead.
+ */
+export interface ISettingDefinition {
+  group: string;
+  name: string;
+  valueType: SettingValueTypes;
+  /** One line, in the words of the console page. */
+  description: string;
+  /**
+   * The value reaches an agent pod as env at deploy time, so a running agent
+   * keeps the old one until it restarts.
+   */
+  restartRequired: boolean;
+  /** Password-type field in the console — a tool must never echo its value. */
+  secret?: true;
+}
+
+/**
+ * Every key on the ordering of the settings menu (Organization, Agent
+ * defaults, Authentication, GitHub, Bridle, Knowledge, Rancher, Storage,
+ * Secrets), then the boot-seeded infrastructure keys.
+ */
+export const SETTING_CATALOG: ISettingDefinition[] = [
+  // ─── Organization ────────────────────────────────────────────────────
+  {
+    group: 'organization',
+    name: 'name',
+    valueType: 'string',
+    description: 'Organization name shown across the admin UI.',
+    restartRequired: false,
+  },
+
+  // ─── Agent defaults ──────────────────────────────────────────────────
+  {
+    group: 'agent_defaults',
+    name: 'cpu',
+    valueType: 'string',
+    description:
+      'Default CPU request for agent pods (e.g. 500m), applied when a ' +
+      'template does not specify its own.',
+    restartRequired: true,
+  },
+  {
+    group: 'agent_defaults',
+    name: 'memory',
+    valueType: 'string',
+    description:
+      'Default memory request for agent pods (e.g. 512Mi), applied when a ' +
+      'template does not specify its own.',
+    restartRequired: true,
+  },
+  {
+    group: 'agent_defaults',
+    name: 'image',
+    valueType: 'string',
+    description:
+      'Container image override for the built-in Rancher template, read when ' +
+      'that template is first created.',
+    restartRequired: true,
+  },
+  {
+    group: 'a2a',
+    name: 'agentSelfService',
+    valueType: 'string',
+    description:
+      "'true' or 'false' — whether an agent asked in the chat may connect its " +
+      "own peers (never another agent's). Off, only operators and operator " +
+      'agents connect peers. Unset reads as on.',
+    restartRequired: false,
+  },
+
+  // ─── Authentication ──────────────────────────────────────────────────
+  {
+    group: 'auth',
+    name: 'registration_enabled',
+    valueType: 'string',
+    description:
+      "'true' or 'false' — whether anyone can create a User account on the " +
+      '/register page of the public app. Unset reads as off.',
+    restartRequired: false,
+  },
+
+  // ─── GitHub ──────────────────────────────────────────────────────────
+  {
+    group: 'integrations',
+    name: 'github_username',
+    valueType: 'string',
+    description: 'GitHub username the personal access token belongs to.',
+    restartRequired: false,
+  },
+  {
+    group: 'integrations',
+    name: 'github_pat',
+    valueType: 'string',
+    description:
+      'GitHub personal access token (scope read:packages) used to pull ' +
+      'private images and to search skill repositories.',
+    restartRequired: false,
+    secret: true,
+  },
+
+  // ─── Bridle ──────────────────────────────────────────────────────────
+  {
+    group: 'integrations',
+    name: 'bridle_url',
+    valueType: 'string',
+    description:
+      'Bridle chat hub URL agents connect to on startup, including the ' +
+      '/ws/agent namespace (default http://host.k3d.internal:3333/ws/agent).',
+    restartRequired: true,
+  },
+  {
+    group: 'integrations',
+    name: 'bridle_api_key',
+    valueType: 'string',
+    description:
+      'Shared secret agents send on the /ws/agent handshake; must match ' +
+      'BRIDLE_API_KEY of the API.',
+    restartRequired: true,
+    secret: true,
+  },
+
+  // ─── Knowledge ───────────────────────────────────────────────────────
+  {
+    group: 'knowledge',
+    name: 'enabled',
+    valueType: 'json',
+    description:
+      'Boolean — whether the external knowledge (RAG) service is on. Off, the ' +
+      '/knowledges API answers disabled and the admin hides knowledge pickers. ' +
+      'Unset reads as on.',
+    restartRequired: false,
+  },
+  {
+    group: 'knowledge',
+    name: 'url',
+    valueType: 'string',
+    description:
+      'Knowledge service (LightRAG) URL, e.g. ' +
+      'http://lightrag.platform.svc.cluster.local:9621.',
+    restartRequired: false,
+  },
+  {
+    group: 'knowledge',
+    name: 'api_key',
+    valueType: 'string',
+    description: 'API key shared with the knowledge service.',
+    restartRequired: false,
+    secret: true,
+  },
+  {
+    group: 'knowledge',
+    name: 's3_bucket',
+    valueType: 'string',
+    description: 'S3 bucket that keeps knowledge source files.',
+    restartRequired: false,
+  },
+  {
+    group: 'knowledge',
+    name: 'chat_credential_id',
+    valueType: 'string',
+    description:
+      'Id of the LLM credential LightRAG uses for chat (LLM_BINDING / ' +
+      'LLM_MODEL). Takes effect after the LightRAG container restarts.',
+    restartRequired: false,
+  },
+  {
+    group: 'knowledge',
+    name: 'embedding_credential_id',
+    valueType: 'string',
+    description:
+      'Id of the LLM credential LightRAG uses for embeddings ' +
+      '(EMBEDDING_BINDING / EMBEDDING_MODEL). Takes effect after the ' +
+      'LightRAG container restarts.',
+    restartRequired: false,
+  },
+  {
+    group: 'knowledge',
+    name: 'ocr_enabled',
+    valueType: 'json',
+    description:
+      'Boolean — recognise text in scanned PDFs with AWS Textract when a ' +
+      'source is added. Off, a scanned PDF is recorded as failed. Unset reads ' +
+      'as on.',
+    restartRequired: false,
+  },
+  {
+    group: 'knowledge',
+    name: 'ocr_max_pages',
+    valueType: 'json',
+    description:
+      'Number — page limit per PDF for OCR (default 500); a longer scan is ' +
+      'skipped with a reason.',
+    restartRequired: false,
+  },
+
+  // ─── Rancher ─────────────────────────────────────────────────────────
+  {
+    group: 'integrations',
+    name: 'ranch_api_url',
+    valueType: 'string',
+    description:
+      'Base URL of this API as seen from agent pods, injected as ' +
+      'RANCH_API_URL (local k3d http://host.k3d.internal:3333, in-cluster ' +
+      'http://ranch-api.platform.svc.cluster.local).',
+    restartRequired: true,
+  },
+
+  // ─── Storage ─────────────────────────────────────────────────────────
+  {
+    group: 'integrations',
+    name: 's3_bucket',
+    valueType: 'string',
+    description:
+      'S3 bucket for agent persistence; when set, an agent syncs .agent/ to ' +
+      'S3 on shutdown and restores on boot (prefix agents/{agent-id}).',
+    restartRequired: true,
+  },
+  {
+    group: 'integrations',
+    name: 's3_endpoint',
+    valueType: 'string',
+    description:
+      'S3 endpoint as the API reaches it (e.g. http://localhost:9000 for ' +
+      'MinIO); blank for AWS.',
+    restartRequired: true,
+  },
+  {
+    group: 'integrations',
+    name: 's3_endpoint_agent',
+    valueType: 'string',
+    description:
+      'S3 endpoint as agent pods reach it (e.g. ' +
+      'http://cleanslice-ranch-minio-1:9000); blank reuses s3_endpoint.',
+    restartRequired: true,
+  },
+  {
+    group: 'integrations',
+    name: 'aws_region',
+    valueType: 'string',
+    description: 'AWS region for S3 and Textract (default us-east-1).',
+    restartRequired: true,
+  },
+  {
+    group: 'integrations',
+    name: 'aws_access_key_id',
+    valueType: 'string',
+    description:
+      'AWS access key id for S3 / Textract / Secrets Manager; blank on EKS ' +
+      'to use the pod identity. Must be set together with the secret key.',
+    restartRequired: true,
+  },
+  {
+    group: 'integrations',
+    name: 'aws_secret_access_key',
+    valueType: 'string',
+    description: 'AWS secret access key paired with aws_access_key_id.',
+    restartRequired: true,
+    secret: true,
+  },
+
+  // ─── Secrets ─────────────────────────────────────────────────────────
+  {
+    group: 'integrations',
+    name: 'secret_provider',
+    valueType: 'string',
+    description:
+      "Where agents keep user-scoped secrets: 'file' (JSON in the pod, dev " +
+      "only) or 'aws' (AWS Secrets Manager under aws_secret_prefix).",
+    restartRequired: true,
+  },
+  {
+    group: 'integrations',
+    name: 'aws_secret_prefix',
+    valueType: 'string',
+    description:
+      'AWS Secrets Manager name prefix for user secrets, no trailing slash ' +
+      '(e.g. cleanslice/users → cleanslice/users/<userId>).',
+    restartRequired: true,
+  },
+
+  // ─── Infrastructure (seeded from env at boot, no console page) ───────
+  {
+    group: 'infrastructure',
+    name: 'argo_url',
+    valueType: 'string',
+    description:
+      'Argo Workflows server URL the API submits agent workflows to ' +
+      '(env ARGO_WORKFLOWS_URL).',
+    restartRequired: false,
+  },
+  {
+    group: 'infrastructure',
+    name: 'workflow_provider',
+    valueType: 'string',
+    description:
+      "'argo' or 'mock' — how agent pods are launched (env WORKFLOW_PROVIDER).",
+    restartRequired: false,
+  },
+  {
+    group: 'infrastructure',
+    name: 'agents_namespace',
+    valueType: 'string',
+    description:
+      'Kubernetes namespace agent pods run in (env AGENTS_NAMESPACE, ' +
+      'default agents).',
+    restartRequired: false,
+  },
+  {
+    group: 'infrastructure',
+    name: 'kube_skip_tls_verify',
+    valueType: 'string',
+    description:
+      "'true' to skip TLS verification against the cluster API " +
+      '(env KUBE_INSECURE).',
+    restartRequired: false,
+  },
+  {
+    group: 'infrastructure',
+    name: 'lightrag_url',
+    valueType: 'string',
+    description:
+      'LightRAG URL fallback used by infrastructure config (env LIGHTRAG_URL); ' +
+      'the Knowledge page sets knowledge.url instead.',
+    restartRequired: false,
+  },
+  {
+    group: 'infrastructure',
+    name: 'lightrag_api_key',
+    valueType: 'string',
+    description:
+      'LightRAG API key fallback (env LIGHTRAG_API_KEY); the Knowledge page ' +
+      'sets knowledge.api_key instead.',
+    restartRequired: false,
+    secret: true,
+  },
+  {
+    group: 'infrastructure',
+    name: 'reins_bucket',
+    valueType: 'string',
+    description:
+      'S3 bucket for knowledge source files at the infrastructure level ' +
+      '(env REINS_S3_BUCKET).',
+    restartRequired: false,
+  },
+  {
+    group: 'infrastructure',
+    name: 'api_public_url',
+    valueType: 'string',
+    description:
+      'Public origin of this API for A2A agent cards and OAuth callbacks ' +
+      '(env PUBLIC_API_URL); unset falls back to integrations.ranch_api_url.',
+    restartRequired: false,
+  },
+];
+
+export const settingKey = (group: string, name: string): string =>
+  `${group}.${name}`;
+
+export function findSettingDefinition(
+  group: string,
+  name: string,
+): ISettingDefinition | null {
+  return (
+    SETTING_CATALOG.find((d) => d.group === group && d.name === name) ?? null
+  );
+}
+
+/**
+ * The catalogued key an unknown one most likely meant: same group, the most
+ * characters shared at the start and the end (so a dropped middle like
+ * `ocr_pages` → `ocr_max_pages` still lands), or one name containing the
+ * other. Null when the group has no entries or nothing overlaps — a bare
+ * guess would mislead more than no hint.
+ */
+export function nearestSettingDefinition(
+  group: string,
+  name: string,
+): ISettingDefinition | null {
+  const wanted = name.toLowerCase();
+  let best: { def: ISettingDefinition; score: number } | null = null;
+  for (const def of SETTING_CATALOG) {
+    if (def.group !== group) continue;
+    const known = def.name.toLowerCase();
+    const shortest = Math.min(wanted.length, known.length);
+    let score = Math.min(
+      shortest,
+      commonPrefixLength(wanted, known) + commonSuffixLength(wanted, known),
+    );
+    if (known.includes(wanted) || wanted.includes(known)) {
+      score = Math.max(score, shortest);
+    }
+    if (score >= MIN_NEAR_SCORE && (!best || score > best.score)) {
+      best = { def, score };
+    }
+  }
+  return best?.def ?? null;
+}
+
+/** Two characters in common is a coincidence; three starts to be a key. */
+const MIN_NEAR_SCORE = 3;
+
+function commonPrefixLength(a: string, b: string): number {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i += 1;
+  return i;
+}
+
+function commonSuffixLength(a: string, b: string): number {
+  let i = 0;
+  while (
+    i < a.length &&
+    i < b.length &&
+    a[a.length - 1 - i] === b[b.length - 1 - i]
+  ) {
+    i += 1;
+  }
+  return i;
+}
+
+/**
+ * The catalogue as text for a tool description, one line per key, grouped:
+ * `group.name — meaning (string, restart required)`.
+ */
+export function describeSettingCatalog(): string {
+  const groups = new Map<string, ISettingDefinition[]>();
+  for (const def of SETTING_CATALOG) {
+    const list = groups.get(def.group) ?? [];
+    list.push(def);
+    groups.set(def.group, list);
+  }
+  const sections: string[] = [];
+  for (const [group, defs] of groups) {
+    const lines = defs.map((d) => {
+      const flags = [d.valueType, d.restartRequired ? 'restart required' : null]
+        .filter((f): f is string => f !== null)
+        .join(', ');
+      return `${settingKey(d.group, d.name)} — ${d.description} (${flags})`;
+    });
+    sections.push(`[${group}]\n${lines.join('\n')}`);
+  }
+  return 'Known settings:\n' + sections.join('\n\n');
+}
diff --git a/api/src/slices/setting/setting.module.ts b/api/src/slices/setting/setting.module.ts
index d130a1e6..76f79b9e 100644
--- a/api/src/slices/setting/setting.module.ts
+++ b/api/src/slices/setting/setting.module.ts
@@ -6,12 +6,14 @@ import { IInfraConfigGateway } from './domain/infraConfig.gateway';
 import { SettingGateway } from './data/setting.gateway';
 import { InfraConfigGateway } from './data/infraConfig.gateway';
 import { SettingMapper } from './data/setting.mapper';
+import { SettingTool } from './setting.tool';
 
 @Module({
   imports: [ConfigModule],
   controllers: [SettingController],
   providers: [
     SettingMapper,
+    SettingTool,
     {
       provide: ISettingGateway,
       useClass: SettingGateway,
diff --git a/api/src/slices/setting/setting.tool.spec.ts b/api/src/slices/setting/setting.tool.spec.ts
new file mode 100644
index 00000000..6b643747
--- /dev/null
+++ b/api/src/slices/setting/setting.tool.spec.ts
@@ -0,0 +1,199 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { SettingTool } from './setting.tool';
+import type {
+  IInfraConfigGateway,
+  ISettingData,
+  ISettingGateway,
+} from './domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * Settings hold the bridle secret and the AWS keys, so what matters most here
+ * is that a plain agent never sees these tools, that a secret value is never
+ * echoed, and that a misspelt key comes back with the key that was meant —
+ * a model that reads "not found" and invents a new row has failed the person.
+ */
+const row = (overrides: Partial<ISettingData> = {}): ISettingData => ({
+  id: 'setting-1',
+  group: 'integrations',
+  name: 's3_bucket',
+  valueType: 'string',
+  value: 'ranch-agent-data',
+  updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  ...overrides,
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+function harness() {
+  const settings = {
+    findByKey: jest.fn().mockResolvedValue(row()),
+    delete: jest.fn().mockResolvedValue(undefined),
+  };
+  const infraConfig = { invalidate: jest.fn() };
+  const tool = new SettingTool(
+    settings as unknown as ISettingGateway,
+    infraConfig as unknown as IInfraConfigGateway,
+  );
+  return { tool, settings, infraConfig };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('SettingTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, settings } = harness();
+    await expect(
+      tool.getSetting(
+        { group: 'integrations', name: 's3_bucket' },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(settings.findByKey).not.toHaveBeenCalled();
+  });
+});
+
+describe('SettingTool — get_setting', () => {
+  it('returns the row with its catalogued meaning', async () => {
+    const { tool, settings } = harness();
+    const text = textOf(
+      await tool.getSetting(
+        { group: 'integrations', name: 's3_bucket' },
+        null,
+        operator(),
+      ),
+    );
+    expect(settings.findByKey).toHaveBeenCalledWith(
+      'integrations',
+      's3_bucket',
+    );
+    expect(text).toContain('ranch-agent-data');
+    expect(text).toContain('"restartRequired": true');
+    expect(text).toContain('S3 bucket for agent persistence');
+  });
+
+  it('reports a secret as set without echoing it', async () => {
+    const { tool, settings } = harness();
+    settings.findByKey.mockResolvedValue(
+      row({ name: 'bridle_api_key', value: 'hunter2-bridle-secret' }),
+    );
+    const text = textOf(
+      await tool.getSetting(
+        { group: 'integrations', name: 'bridle_api_key' },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).not.toContain('hunter2-bridle-secret');
+    expect(text).toContain('(secret — set)');
+  });
+
+  it('names the nearest catalogued key when the row does not exist', async () => {
+    const { tool, settings } = harness();
+    settings.findByKey.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getSetting(
+        { group: 'integrations', name: 's3_buckt' },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('«integrations.s3_buckt» is not set');
+    expect(text).toContain('Did you mean «integrations.s3_bucket»');
+    expect(text).toContain('list_settings');
+  });
+
+  it('offers no guess when nothing in the group is close', async () => {
+    const { tool, settings } = harness();
+    settings.findByKey.mockResolvedValue(null);
+    const text = textOf(
+      await tool.getSetting(
+        { group: 'integrations', name: 'zzz' },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).not.toContain('Did you mean');
+    expect(text).toContain('list_settings');
+  });
+});
+
+describe('SettingTool — delete_setting', () => {
+  it('refuses without the confirmation argument and touches nothing', async () => {
+    const { tool, settings, infraConfig } = harness();
+    const result = await tool.deleteSetting(
+      { group: 'integrations', name: 's3_bucket' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('reset «integrations.s3_bucket»');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(settings.delete).not.toHaveBeenCalled();
+    expect(infraConfig.invalidate).not.toHaveBeenCalled();
+  });
+
+  it('reports a missing row before asking for confirmation', async () => {
+    const { tool, settings } = harness();
+    settings.findByKey.mockResolvedValue(null);
+    const result = await tool.deleteSetting(
+      { group: 'integrations', name: 's3_buckt' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('Did you mean «integrations.s3_bucket»');
+    expect(settings.delete).not.toHaveBeenCalled();
+  });
+
+  it('deletes once confirmed and says agents need a restart for a deploy-time key', async () => {
+    const { tool, settings, infraConfig } = harness();
+    const text = textOf(
+      await tool.deleteSetting(
+        { group: 'integrations', name: 's3_bucket', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(settings.delete).toHaveBeenCalledWith('integrations', 's3_bucket');
+    expect(infraConfig.invalidate).not.toHaveBeenCalled();
+    expect(text).toContain('«integrations.s3_bucket» removed');
+    expect(text).toContain('restart_agent');
+  });
+
+  it('drops the infrastructure cache as the controller does', async () => {
+    const { tool, settings, infraConfig } = harness();
+    settings.findByKey.mockResolvedValue(
+      row({ group: 'infrastructure', name: 'argo_url', value: 'http://argo' }),
+    );
+    const text = textOf(
+      await tool.deleteSetting(
+        { group: 'infrastructure', name: 'argo_url', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(settings.delete).toHaveBeenCalledWith('infrastructure', 'argo_url');
+    expect(infraConfig.invalidate).toHaveBeenCalledTimes(1);
+    expect(text).not.toContain('restart_agent');
+  });
+});
diff --git a/api/src/slices/setting/setting.tool.ts b/api/src/slices/setting/setting.tool.ts
new file mode 100644
index 00000000..fe8e9f84
--- /dev/null
+++ b/api/src/slices/setting/setting.tool.ts
@@ -0,0 +1,165 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  CONFIRM_SENTENCE,
+  callerIsOperator,
+  confirmed,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import {
+  IInfraConfigGateway,
+  ISettingGateway,
+  findSettingDefinition,
+  nearestSettingDefinition,
+  settingKey,
+  type ISettingData,
+} from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/**
+ * Reading and resetting one setting from the chat (CLEAN-109). Mirrors
+ * `GET settings/:group/:name` and `DELETE settings/:group/:name` of
+ * `SettingController`; listing and upserting stay in `rancher.tool.ts`.
+ *
+ * A setting is a free-form `group.name` row, so "not found" here usually
+ * means a misspelt key rather than an empty value. Both tools therefore
+ * answer with the nearest catalogued key (`domain/settingCatalog.ts`) so the
+ * model corrects itself instead of inventing a row the platform never reads.
+ *
+ * Operator-only: platform settings are the console's Settings section, and
+ * a plain agent has no business reading the AWS keys or the bridle secret
+ * that live there.
+ */
+@Injectable()
+export class SettingTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(SettingTool.name);
+
+  constructor(
+    private readonly settings: ISettingGateway,
+    private readonly infraConfig: IInfraConfigGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'get_setting',
+    topic: ToolTopics.Settings,
+    title: 'Show one setting',
+    template: 'What is «group».«name» set to?',
+    description:
+      'Read a single platform setting by group and name: its value, value ' +
+      'type and when it was last changed, plus what the key means when it is ' +
+      'a known one. A secret (API key, token, password) is reported as set or ' +
+      'empty, never shown. An unknown key names the closest catalogued key so ' +
+      'you can retry — list_settings shows every row that exists.',
+    parameters: z.object({
+      group: z.string().describe('Setting group, e.g. integrations, auth'),
+      name: z
+        .string()
+        .describe('Setting name inside the group, e.g. s3_bucket'),
+    }),
+  })
+  async getSetting(
+    { group, name }: { group: string; name: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const setting = await this.settings.findByKey(group, name);
+    if (!setting) return ok(notFound(group, name));
+    const definition = findSettingDefinition(group, name);
+    return ok({
+      ...presentable(setting, Boolean(definition?.secret)),
+      ...(definition && {
+        meaning: definition.description,
+        restartRequired: definition.restartRequired,
+      }),
+    });
+  }
+
+  @Tool({
+    name: 'delete_setting',
+    topic: ToolTopics.Settings,
+    title: 'Delete a setting',
+    template: 'Reset «group».«name» to its default',
+    destructive: true,
+    description:
+      'Remove a platform setting row, so the platform falls back to its ' +
+      'built-in default (or the env value, for the infrastructure group). ' +
+      'There is no undo — the old value is gone; set it again with ' +
+      'upsert_setting if needed. For keys agents receive at deploy time the ' +
+      'change reaches a running agent only after restart_agent. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      group: z.string(),
+      name: z.string(),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteSetting(
+    args: { group: string; name: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { group, name } = args;
+    const existing = await this.settings.findByKey(group, name);
+    if (!existing) return ok(notFound(group, name));
+    const refusal = confirmed(
+      args,
+      `reset «${settingKey(group, name)}» to its default`,
+    );
+    if (refusal) return refusal;
+
+    await this.settings.delete(group, name);
+    // The controller drops the infra cache on this group so the next read
+    // sees the env/default value instead of the row that no longer exists.
+    if (group === 'infrastructure') this.infraConfig.invalidate();
+    this.logger.log(`Setting deleted through MCP: ${settingKey(group, name)}`);
+
+    const definition = findSettingDefinition(group, name);
+    return ok({
+      ok: true,
+      group,
+      name,
+      message:
+        `«${settingKey(group, name)}» removed — the platform now uses its default.` +
+        (definition?.restartRequired
+          ? ' Running agents keep the old value until they restart — offer restart_agent.'
+          : ''),
+    });
+  }
+}
+
+/** The row as a tool may show it: a secret value is reported, not echoed. */
+function presentable(
+  setting: ISettingData,
+  secret: boolean,
+): Record<string, unknown> {
+  const { value, ...rest } = setting;
+  if (!secret) return { ...rest, value };
+  const isSet = typeof value === 'string' ? value.length > 0 : value != null;
+  return { ...rest, value: isSet ? '(secret — set)' : '(secret — empty)' };
+}
+
+function notFound(group: string, name: string): { error: string } {
+  const key = settingKey(group, name);
+  const near = nearestSettingDefinition(group, name);
+  const hint = near
+    ? ` Did you mean «${settingKey(near.group, near.name)}» (${near.description})?`
+    : '';
+  return {
+    error: `Setting «${key}» is not set.${hint} Call list_settings to see every row that exists.`,
+  };
+}
diff --git a/api/src/slices/skill/skill.controller.ts b/api/src/slices/skill/skill.controller.ts
index 319f0bfd..c315bf90 100644
--- a/api/src/slices/skill/skill.controller.ts
+++ b/api/src/slices/skill/skill.controller.ts
@@ -158,7 +158,8 @@ export class SkillController {
   }
 }
 
-function deriveSlug(path: string): string {
+/** Exported so `skill.tool.ts` derives the same slug the console import does. */
+export function deriveSlug(path: string): string {
   const parts = path.split('/').filter(Boolean);
   const fname = parts.pop() ?? '';
   const parent = parts.pop();
diff --git a/api/src/slices/skill/skill.module.ts b/api/src/slices/skill/skill.module.ts
index e36c47ce..8e41480b 100644
--- a/api/src/slices/skill/skill.module.ts
+++ b/api/src/slices/skill/skill.module.ts
@@ -4,6 +4,7 @@ import { ISkillGateway } from './domain/skill.gateway';
 import { SkillGateway } from './data/skill.gateway';
 import { SkillMapper } from './data/skill.mapper';
 import { GithubSearch } from './data/github.search';
+import { SkillTool } from './skill.tool';
 import { SettingModule } from '#/setting/setting.module';
 
 @Module({
@@ -12,6 +13,7 @@ import { SettingModule } from '#/setting/setting.module';
   providers: [
     SkillMapper,
     GithubSearch,
+    SkillTool,
     {
       provide: ISkillGateway,
       useClass: SkillGateway,
diff --git a/api/src/slices/skill/skill.tool.spec.ts b/api/src/slices/skill/skill.tool.spec.ts
new file mode 100644
index 00000000..c0e36db9
--- /dev/null
+++ b/api/src/slices/skill/skill.tool.spec.ts
@@ -0,0 +1,379 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { SkillTool } from './skill.tool';
+import type { ISkillGateway } from './domain';
+import type { ISkillData } from './domain';
+import type { GithubSearch } from './data/github.search';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * These tools let an agent rewrite the instructions other agents are deployed
+ * with. Worth more than the happy path: that a plain agent cannot see or call
+ * them, that a delete asks before it acts and says who loses the skill, and
+ * that an import lands exactly where the console import would — same slug,
+ * same dedup, same refusal when the slug is taken.
+ */
+const skill = (overrides: Partial<ISkillData> = {}): ISkillData => ({
+  id: 'skill-1',
+  name: 'devops',
+  title: 'DevOps engineer',
+  description: 'Ships things',
+  body: '# DevOps\n\nDo the deploys.',
+  files: [{ path: 'references/ci.md', content: 'ci notes' }],
+  source: null,
+  createdAt: new Date('2026-09-17T10:00:00.000Z'),
+  updatedAt: new Date('2026-09-17T10:00:00.000Z'),
+  ...overrides,
+});
+
+const bundle = () => ({
+  title: 'PDF parsing',
+  body: '# PDF\n\nParse PDFs.',
+  description: 'Reads PDFs',
+  files: [{ path: 'scripts/parse.py', content: 'print(1)' }],
+});
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+interface Harness {
+  tool: SkillTool;
+  skills: jest.Mocked<
+    Pick<
+      ISkillGateway,
+      | 'findById'
+      | 'findByName'
+      | 'create'
+      | 'update'
+      | 'delete'
+      | 'findDependentAgents'
+    >
+  >;
+  github: jest.Mocked<
+    Pick<
+      GithubSearch,
+      'listSources' | 'search' | 'fetchBundle' | 'fetchBundleFromUrl'
+    >
+  >;
+}
+
+function harness(): Harness {
+  const skills = {
+    findById: jest.fn().mockResolvedValue(skill()),
+    findByName: jest.fn().mockResolvedValue(null),
+    create: jest
+      .fn()
+      .mockImplementation(async (data: Partial<ISkillData>) =>
+        skill({ id: 'skill-new', ...data }),
+      ),
+    update: jest
+      .fn()
+      .mockImplementation(async (id: string, data: Partial<ISkillData>) =>
+        skill({ id, ...data }),
+      ),
+    delete: jest.fn().mockResolvedValue(undefined),
+    findDependentAgents: jest.fn().mockResolvedValue([]),
+  } as unknown as Harness['skills'];
+
+  const github = {
+    listSources: jest
+      .fn()
+      .mockReturnValue([{ repo: 'anthropics/skills', label: 'Anthropic' }]),
+    search: jest.fn().mockResolvedValue([
+      {
+        source: 'github:anthropics/skills',
+        repo: 'anthropics/skills',
+        path: 'skills/pdf/SKILL.md',
+        name: 'pdf',
+        title: 'PDF parsing',
+        description: 'Reads PDFs',
+        url: 'https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md',
+        snippet: null,
+      },
+    ]),
+    fetchBundle: jest.fn().mockResolvedValue(bundle()),
+    fetchBundleFromUrl: jest.fn().mockResolvedValue({
+      repo: 'anthropics/skills',
+      skillPath: 'skills/pdf/SKILL.md',
+      bundle: bundle(),
+    }),
+  } as unknown as Harness['github'];
+
+  const tool = new SkillTool(
+    skills as unknown as ISkillGateway,
+    github as unknown as GithubSearch,
+  );
+  return { tool, skills, github };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('SkillTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, skills } = harness();
+    await expect(
+      tool.createSkill(
+        { name: 'x', title: 'X', body: 'body' },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(skills.create).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool } = harness();
+    await expect(
+      tool.getSkill({ id: 'skill-1' }, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('SkillTool — reading', () => {
+  it('returns the whole skill, body and files included', async () => {
+    const { tool, skills } = harness();
+    const text = textOf(
+      await tool.getSkill({ id: 'skill-1' }, null, operator()),
+    );
+    expect(skills.findById).toHaveBeenCalledWith('skill-1');
+    expect(text).toContain('"name": "devops"');
+    expect(text).toContain('Do the deploys.');
+    expect(text).toContain('references/ci.md');
+  });
+
+  it('points at list_skills when the id is unknown', async () => {
+    const { tool, skills } = harness();
+    skills.findById.mockResolvedValue(null);
+    const text = textOf(await tool.getSkill({ id: 'nope' }, null, operator()));
+    expect(text).toContain('not found');
+    expect(text).toContain('list_skills');
+  });
+
+  it('searches the curated repos and names them next to the hits', async () => {
+    const { tool, github } = harness();
+    const text = textOf(
+      await tool.searchSkills({ q: 'pdf parsing' }, null, operator()),
+    );
+    expect(github.search).toHaveBeenCalledWith('pdf parsing');
+    expect(text).toContain('"sources"');
+    expect(text).toContain('anthropics/skills');
+    expect(text).toContain('"hits"');
+    expect(text).toContain('skills/pdf/SKILL.md');
+  });
+});
+
+describe('SkillTool — creating', () => {
+  it('creates the skill with the fields the console form sends', async () => {
+    const { tool, skills } = harness();
+    const text = textOf(
+      await tool.createSkill(
+        { name: 'pdf', title: 'PDF parsing', body: '# PDF', description: 'x' },
+        null,
+        operator(),
+      ),
+    );
+    expect(skills.create).toHaveBeenCalledWith({
+      name: 'pdf',
+      title: 'PDF parsing',
+      body: '# PDF',
+      description: 'x',
+    });
+    expect(text).toContain('"id": "skill-new"');
+    expect(text).toContain('"name": "pdf"');
+  });
+});
+
+describe('SkillTool — deleting', () => {
+  it('refuses without the confirmation argument and touches nothing', async () => {
+    const { tool, skills } = harness();
+    const result = await tool.deleteSkill({ id: 'skill-1' }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(textOf(result)).toContain('«DevOps engineer»');
+    expect(skills.delete).not.toHaveBeenCalled();
+  });
+
+  it('names the agents that use it in the confirmation', async () => {
+    const { tool, skills } = harness();
+    skills.findDependentAgents.mockResolvedValue([
+      {
+        id: 'agent-a',
+        name: 'Ops Bot',
+        status: 'running',
+        templateId: 't-1',
+        templateName: 'ops',
+      },
+    ]);
+    const result = await tool.deleteSkill({ id: 'skill-1' }, null, operator());
+    expect(textOf(result)).toContain('1 agent(s) use');
+    expect(skills.delete).not.toHaveBeenCalled();
+  });
+
+  it('reports not found before asking for a confirmation', async () => {
+    const { tool, skills } = harness();
+    skills.findById.mockResolvedValue(null);
+    const result = await tool.deleteSkill({ id: 'nope' }, null, operator());
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('not found');
+    expect(skills.delete).not.toHaveBeenCalled();
+  });
+
+  it('deletes once confirmed and says who still runs the old copy', async () => {
+    const { tool, skills } = harness();
+    skills.findDependentAgents.mockResolvedValue([
+      {
+        id: 'agent-a',
+        name: 'Ops Bot',
+        status: 'running',
+        templateId: 't-1',
+        templateName: 'ops',
+      },
+    ]);
+    const text = textOf(
+      await tool.deleteSkill(
+        { id: 'skill-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(skills.delete).toHaveBeenCalledWith('skill-1');
+    expect(text).toContain('deleted');
+    expect(text).toContain('ops');
+    expect(text).toContain('restart_agent');
+    expect(text).toContain('agent-a');
+  });
+
+  it('says so when nobody was using it', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.deleteSkill(
+        { id: 'skill-1', confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('No agent was using it');
+  });
+});
+
+describe('SkillTool — importing', () => {
+  it('imports from a URL under the slug the console would derive', async () => {
+    const { tool, skills, github } = harness();
+    const url = 'https://github.com/anthropics/skills/tree/main/skills/pdf';
+    const text = textOf(
+      await tool.importSkillFromUrl({ url }, null, operator()),
+    );
+    expect(github.fetchBundleFromUrl).toHaveBeenCalledWith(url);
+    expect(skills.findByName).toHaveBeenCalledWith('pdf');
+    expect(skills.create).toHaveBeenCalledWith({
+      name: 'pdf',
+      title: 'PDF parsing',
+      body: '# PDF\n\nParse PDFs.',
+      description: 'Reads PDFs',
+      files: [{ path: 'scripts/parse.py', content: 'print(1)' }],
+      source:
+        'https://github.com/anthropics/skills/blob/HEAD/skills/pdf/SKILL.md',
+    });
+    expect(text).toContain('"name": "pdf"');
+    expect(text).toContain('scripts/parse.py');
+  });
+
+  it('imports a search hit by repo and path, honouring a chosen slug', async () => {
+    const { tool, skills, github } = harness();
+    const text = textOf(
+      await tool.importSkill(
+        {
+          repo: 'anthropics/skills',
+          path: 'skills/pdf/SKILL.md',
+          name: 'pdf-tools',
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(github.fetchBundle).toHaveBeenCalledWith(
+      'anthropics/skills',
+      'skills/pdf/SKILL.md',
+    );
+    expect(skills.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'pdf-tools',
+        source:
+          'https://github.com/anthropics/skills/blob/HEAD/skills/pdf/SKILL.md',
+      }),
+    );
+    expect(text).toContain('"name": "pdf-tools"');
+  });
+
+  it('refuses to import over an existing slug and names both ways forward', async () => {
+    const { tool, skills } = harness();
+    skills.findByName.mockResolvedValue(
+      skill({ id: 'skill-old', name: 'pdf', title: 'Old PDF' }),
+    );
+    const result = await tool.importSkill(
+      { repo: 'anthropics/skills', path: 'skills/pdf/SKILL.md' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('already exists');
+    expect(textOf(result)).toContain('skill-old');
+    expect(textOf(result)).toContain('overwrite: true');
+    expect(skills.create).not.toHaveBeenCalled();
+    expect(skills.update).not.toHaveBeenCalled();
+  });
+
+  it('replaces the existing skill in full when overwrite is true', async () => {
+    const { tool, skills } = harness();
+    skills.findByName.mockResolvedValue(
+      skill({ id: 'skill-old', name: 'pdf' }),
+    );
+    const text = textOf(
+      await tool.importSkillFromUrl(
+        {
+          url: 'https://github.com/anthropics/skills/tree/main/skills/pdf',
+          overwrite: true,
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(skills.create).not.toHaveBeenCalled();
+    expect(skills.update).toHaveBeenCalledWith('skill-old', {
+      title: 'PDF parsing',
+      body: '# PDF\n\nParse PDFs.',
+      description: 'Reads PDFs',
+      files: [{ path: 'scripts/parse.py', content: 'print(1)' }],
+      source:
+        'https://github.com/anthropics/skills/blob/HEAD/skills/pdf/SKILL.md',
+    });
+    expect(text).toContain('"id": "skill-old"');
+  });
+
+  it('lets a GitHub failure escape, so the MCP layer reports it as an error', async () => {
+    const { tool, github, skills } = harness();
+    github.fetchBundleFromUrl.mockRejectedValue(
+      new Error('Not a recognised GitHub URL: https://example.com'),
+    );
+    await expect(
+      tool.importSkillFromUrl({ url: 'https://example.com' }, null, operator()),
+    ).rejects.toThrow('Not a recognised GitHub URL');
+    expect(skills.create).not.toHaveBeenCalled();
+  });
+});
diff --git a/api/src/slices/skill/skill.tool.ts b/api/src/slices/skill/skill.tool.ts
new file mode 100644
index 00000000..e8897fbd
--- /dev/null
+++ b/api/src/slices/skill/skill.tool.ts
@@ -0,0 +1,367 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { ISkillGateway } from './domain';
+import type { ISkillFile } from './domain';
+import { GithubSearch } from './data/github.search';
+import { deriveSlug } from './skill.controller';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** Same rule as the create/import DTOs: a skill name is a slug. */
+const SLUG = /^[a-z0-9][a-z0-9-]*$/;
+const SLUG_MESSAGE =
+  'name must be a slug: lowercase letters, digits and dashes (e.g. "devops")';
+
+const NOT_FOUND = (id: string) =>
+  ok({ error: `Skill ${id} not found — call list_skills to find the id` });
+
+/**
+ * The skill capabilities the console has and `rancher.tool.ts` did not
+ * (CLEAN-109): read one, create one, delete one, and the two GitHub import
+ * paths with the search that feeds them. `list_skills`, `update_skill`,
+ * `list_skill_agents` and `redeploy_skill_agents` stay in `rancher.tool.ts`.
+ *
+ * Every call goes through `ISkillGateway` and `GithubSearch`, the two things
+ * `SkillController` injects, in the order the controller calls them. The
+ * import dedup (same slug → refuse unless `overwrite`) is the controller's
+ * rule, kept here verbatim so a chat import cannot silently replace a skill
+ * the console would have asked about.
+ *
+ * Operator-only: a plain agent must not be able to rewrite the instructions
+ * other agents are deployed with.
+ */
+@Injectable()
+export class SkillTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(SkillTool.name);
+
+  constructor(
+    private readonly skills: ISkillGateway,
+    private readonly github: GithubSearch,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  // ─── Reading ─────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'get_skill',
+    topic: ToolTopics.Skills,
+    title: 'Show a skill',
+    template: 'Show the skill «name»',
+    description:
+      'Read one skill in full: its slug, title, description, the SKILL.md ' +
+      'body, its helper files and where it was imported from. Takes the ' +
+      'skill id — resolve a name with list_skills first. Read this before ' +
+      'update_skill so you change only what the person asked for.',
+    parameters: z.object({
+      id: z.string().describe('Skill id (list_skills has them)'),
+    }),
+  })
+  async getSkill(
+    { id }: { id: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const skill = await this.skills.findById(id);
+    if (!skill) return NOT_FOUND(id);
+    return ok(skill);
+  }
+
+  @Tool({
+    name: 'search_skills',
+    topic: ToolTopics.Skills,
+    title: 'Search public skills',
+    template: 'Find public skills about «topic»',
+    description:
+      'Search the curated public GitHub repos for skills matching a topic. ' +
+      'Returns the repos searched (`sources`) and the matching skills ' +
+      '(`hits`), each with the repo and path import_skill needs, a proposed ' +
+      'slug, title and description, and a link to read it on GitHub. Needs ' +
+      'a GitHub token in Settings (integrations/github_pat); the call ' +
+      'reports it when one is missing. Show the person the hits and import ' +
+      'the one they pick with import_skill.',
+    parameters: z.object({
+      q: z
+        .string()
+        .min(2)
+        .describe('What the skill should be about, e.g. "pdf parsing"'),
+    }),
+  })
+  async searchSkills(
+    { q }: { q: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    // Sources first so the model can tell the person where it looked even
+    // when nothing matched — the controller exposes them as GET skills/sources.
+    const sources = this.github.listSources();
+    const hits = await this.github.search(q);
+    return ok({ sources, hits });
+  }
+
+  // ─── Changing ────────────────────────────────────────────────────────
+
+  @Tool({
+    name: 'create_skill',
+    topic: ToolTopics.Skills,
+    title: 'Create a skill',
+    template: 'Create a skill «title» that «what it does»',
+    description:
+      'Create a skill from scratch: a slug, a title and the SKILL.md markdown ' +
+      'body that agents will read. Returns the created skill with its id. A ' +
+      'new skill does nothing on its own — attach it to a template with ' +
+      'set_template_skills, then redeploy the agents of that template. To ' +
+      'bring in an existing skill from GitHub use import_skill_from_url or ' +
+      'search_skills + import_skill instead.',
+    parameters: z.object({
+      name: z
+        .string()
+        .regex(SLUG, SLUG_MESSAGE)
+        .describe('Unique slug — lowercase letters, digits, dashes'),
+      title: z.string().describe('Human title, e.g. "DevOps engineer"'),
+      body: z.string().describe('Markdown body of the skill (the SKILL.md)'),
+      description: z
+        .string()
+        .optional()
+        .describe('One line on when an agent should reach for it'),
+    }),
+  })
+  async createSkill(
+    args: { name: string; title: string; body: string; description?: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const created = await this.skills.create(args);
+    this.logger.log(
+      `Skill created through MCP: ${created.name} (${created.id})`,
+    );
+    return ok(created);
+  }
+
+  @Tool({
+    name: 'delete_skill',
+    topic: ToolTopics.Skills,
+    title: 'Delete a skill',
+    template: 'Delete the skill «name»',
+    destructive: true,
+    description:
+      'Delete a skill and detach it from every template that includes it. ' +
+      'Not reversible — the body and helper files are gone; re-import from ' +
+      'the source URL if it had one. Agents already running keep the copy ' +
+      'baked into their pod until they restart. Check list_skill_agents ' +
+      'first and tell the person which agents will lose it. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string().describe('Skill id (list_skills has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteSkill(
+    args: { id: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { id } = args;
+    const skill = await this.skills.findById(id);
+    if (!skill) return NOT_FOUND(id);
+
+    // The gateway does not refuse a skill in use (the template link is an
+    // implicit many-to-many, dropped with the row), so the tool names the
+    // fallout in the confirmation instead of finding out afterwards.
+    const dependents = await this.skills.findDependentAgents(id);
+    const inUse =
+      dependents.length > 0
+        ? `, which ${dependents.length} agent(s) use through their templates`
+        : '';
+    const refusal = confirmed(
+      args,
+      `delete the skill «${skill.title}»${inUse}`,
+    );
+    if (refusal) return refusal;
+
+    await this.skills.delete(id);
+    this.logger.log(`Skill deleted through MCP: ${skill.name} (${id})`);
+
+    const templates = [...new Set(dependents.map((d) => d.templateName))];
+    return ok(
+      `Skill «${skill.title}» (${skill.name}) deleted.` +
+        (dependents.length === 0
+          ? ' No agent was using it.'
+          : ` It was detached from ${templates.length} template(s): ` +
+            `${templates.join(', ')}. ${dependents.length} agent(s) still ` +
+            'run with the old copy baked in — restart_agent each of them ' +
+            `(${dependents.map((d) => d.id).join(', ')}) when the person ` +
+            'is ready.'),
+    );
+  }
+
+  @Tool({
+    name: 'import_skill_from_url',
+    topic: ToolTopics.Skills,
+    title: 'Import a skill from GitHub',
+    template: 'Import the skill at «github url»',
+    description:
+      'Import a skill from any GitHub link: a folder (tree/…) holding a ' +
+      'SKILL.md or README.md, or a direct link to a .md file (blob/…). ' +
+      'Fetches the file and its sibling files, derives a slug from the path ' +
+      '(pass `name` to choose one) and saves the skill with its source URL. ' +
+      'Refuses if a skill with that slug already exists unless `overwrite` ' +
+      'is true, in which case it is replaced in full. Returns the saved ' +
+      'skill. Attach it to a template with set_template_skills afterwards.',
+    parameters: z.object({
+      url: z
+        .string()
+        .url()
+        .describe(
+          'GitHub URL, e.g. https://github.com/owner/repo/tree/main/skills/my-skill',
+        ),
+      name: z
+        .string()
+        .regex(SLUG, SLUG_MESSAGE)
+        .optional()
+        .describe('Slug to save it under instead of the derived one'),
+      overwrite: z
+        .boolean()
+        .optional()
+        .describe('Replace a skill that already has this slug'),
+    }),
+  })
+  async importSkillFromUrl(
+    {
+      url,
+      name,
+      overwrite,
+    }: { url: string; name?: string; overwrite?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { repo, skillPath, bundle } =
+      await this.github.fetchBundleFromUrl(url);
+    const slug = name ?? deriveSlug(skillPath);
+    return this.upsertSkill(slug, overwrite === true, {
+      title: bundle.title,
+      body: bundle.body,
+      description: bundle.description,
+      files: bundle.files,
+      source: `https://github.com/${repo}/blob/HEAD/${skillPath}`,
+    });
+  }
+
+  @Tool({
+    name: 'import_skill',
+    topic: ToolTopics.Skills,
+    title: 'Import a found skill',
+    template: 'Import the skill «name» from «repo»',
+    description:
+      'Import a skill that search_skills found: pass the `repo` and `path` ' +
+      'of the hit. Fetches the SKILL.md and its sibling files, derives a ' +
+      'slug from the path (pass `name` to choose one) and saves the skill ' +
+      'with its source URL. Refuses if a skill with that slug already exists ' +
+      'unless `overwrite` is true, in which case it is replaced in full. ' +
+      'Returns the saved skill. Attach it to a template with ' +
+      'set_template_skills afterwards.',
+    parameters: z.object({
+      repo: z
+        .string()
+        .describe(
+          'GitHub owner/repo from the search hit, e.g. anthropics/skills',
+        ),
+      path: z
+        .string()
+        .describe('Path to the SKILL.md inside the repo, from the search hit'),
+      name: z
+        .string()
+        .regex(SLUG, SLUG_MESSAGE)
+        .optional()
+        .describe('Slug to save it under instead of the derived one'),
+      overwrite: z
+        .boolean()
+        .optional()
+        .describe('Replace a skill that already has this slug'),
+    }),
+  })
+  async importSkill(
+    {
+      repo,
+      path,
+      name,
+      overwrite,
+    }: { repo: string; path: string; name?: string; overwrite?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const bundle = await this.github.fetchBundle(repo, path);
+    const slug = name ?? deriveSlug(path);
+    return this.upsertSkill(slug, overwrite === true, {
+      title: bundle.title,
+      body: bundle.body,
+      description: bundle.description,
+      files: bundle.files,
+      source: `https://github.com/${repo}/blob/HEAD/${path}`,
+    });
+  }
+
+  /**
+   * `SkillController.upsertSkill`, with the 409 turned into a refusal the
+   * model can act on: it names the existing skill and the two ways forward.
+   */
+  private async upsertSkill(
+    slug: string,
+    overwrite: boolean,
+    data: {
+      title: string;
+      body: string;
+      description: string | null;
+      files: ISkillFile[];
+      source: string;
+    },
+  ): Promise<ToolResult> {
+    const existing = await this.skills.findByName(slug);
+    if (existing && !overwrite) {
+      return err(
+        `Skill "${slug}" already exists (id ${existing.id}, ` +
+          `«${existing.title}»` +
+          `${existing.source ? `, from ${existing.source}` : ''}). Ask the ` +
+          'person whether to replace it — then call again with overwrite: ' +
+          'true — or import it under another slug with name.',
+      );
+    }
+    if (existing && overwrite) {
+      const updated = await this.skills.update(existing.id, {
+        title: data.title,
+        body: data.body,
+        description: data.description,
+        files: data.files,
+        source: data.source,
+      });
+      this.logger.log(`Skill replaced through MCP: ${slug} (${existing.id})`);
+      return ok(updated);
+    }
+    const created = await this.skills.create({ name: slug, ...data });
+    this.logger.log(`Skill imported through MCP: ${slug} (${created.id})`);
+    return ok(created);
+  }
+}
diff --git a/api/src/slices/upgrade/upgrade.module.ts b/api/src/slices/upgrade/upgrade.module.ts
index 1174c438..6190f054 100644
--- a/api/src/slices/upgrade/upgrade.module.ts
+++ b/api/src/slices/upgrade/upgrade.module.ts
@@ -3,6 +3,7 @@ import { UpgradeController } from './upgrade.controller';
 import { IUpgradeGateway } from './domain/upgrade.gateway';
 import { UpgradeService } from './domain/upgrade.service';
 import { UpgradeGateway } from './data/upgrade.gateway';
+import { UpgradeTool } from './upgrade.tool';
 import { AuthModule } from '#/user/auth/auth.module';
 
 @Module({
@@ -10,6 +11,8 @@ import { AuthModule } from '#/user/auth/auth.module';
   controllers: [UpgradeController],
   providers: [
     UpgradeService,
+    // MCP tools: get_upgrade_status / run_upgrade, operator-only (CLEAN-109).
+    UpgradeTool,
     {
       provide: IUpgradeGateway,
       useClass: UpgradeGateway,
diff --git a/api/src/slices/upgrade/upgrade.tool.spec.ts b/api/src/slices/upgrade/upgrade.tool.spec.ts
new file mode 100644
index 00000000..f188339a
--- /dev/null
+++ b/api/src/slices/upgrade/upgrade.tool.spec.ts
@@ -0,0 +1,66 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { UpgradeTool } from './upgrade.tool';
+import { UserRoleTypes } from '#/user/user/domain';
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({ user: { sub: 'agent:x', email: '', roles } }) as unknown as Request;
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+const harness = (eligible = true) => {
+  const upgrade = {
+    getStatus: jest.fn(async () => ({
+      eligible,
+      reason: eligible ? null : 'working tree is dirty',
+      currentVersion: '1.2.3',
+    })),
+    run: jest.fn(async () => ({ ok: true, output: 'pulled' })),
+  };
+  return { tool: new UpgradeTool(upgrade as never), upgrade };
+};
+
+const textOf = (r: { content: { text: string }[] }) => r.content[0].text;
+
+describe('UpgradeTool (CLEAN-109)', () => {
+  it('is listed for operators only', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('refuses a plain agent before touching the service', async () => {
+    const { tool, upgrade } = harness();
+    await expect(tool.status({}, null, plainAgent())).rejects.toThrow(
+      ForbiddenException,
+    );
+    expect(upgrade.getStatus).not.toHaveBeenCalled();
+  });
+
+  it('reports the status', async () => {
+    const { tool } = harness(false);
+    const text = textOf(await tool.status({}, null, operator()));
+    expect(text).toContain('"eligible": false');
+    expect(text).toContain('working tree is dirty');
+  });
+
+  it('refuses to run when not eligible, without asking for confirmation', async () => {
+    const { tool, upgrade } = harness(false);
+    const result = await tool.run({ confirm: true }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('working tree is dirty');
+    expect(upgrade.run).not.toHaveBeenCalled();
+  });
+
+  it('asks for confirmation when eligible and runs once confirmed', async () => {
+    const { tool, upgrade } = harness();
+    const refused = await tool.run({}, null, operator());
+    expect(refused.isError).toBe(true);
+    expect(textOf(refused)).toContain('confirm: true');
+    expect(upgrade.run).not.toHaveBeenCalled();
+
+    const done = await tool.run({ confirm: true }, null, operator());
+    expect(upgrade.run).toHaveBeenCalledTimes(1);
+    expect(textOf(done)).toContain('pulled');
+  });
+});
diff --git a/api/src/slices/upgrade/upgrade.tool.ts b/api/src/slices/upgrade/upgrade.tool.ts
new file mode 100644
index 00000000..83ff1917
--- /dev/null
+++ b/api/src/slices/upgrade/upgrade.tool.ts
@@ -0,0 +1,88 @@
+import { Injectable, Logger } from '@nestjs/common';
+import type { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import {
+  CONFIRM_SENTENCE,
+  callerIsOperator,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IAuthTokenPayload } from '#/user/auth/domain';
+import { UpgradeService } from './domain/upgrade.service';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/**
+ * Ranch's own upgrade, from the chat (CLEAN-109). Mirrors `UpgradeController`:
+ * status is a read, running it is gated by the same eligibility check and,
+ * because it replaces the running code, by the person's confirmation.
+ */
+@Injectable()
+export class UpgradeTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(UpgradeTool.name);
+
+  constructor(private readonly upgrade: UpgradeService) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'get_upgrade_status',
+    topic: ToolTopics.Platform,
+    title: 'Ranch upgrade status',
+    template: 'Is a Ranch upgrade available?',
+    description:
+      'Whether this Ranch checkout can be upgraded in place (clean git tree, on main, .git present, not in deployed mode) and, when it cannot, why. Read-only.',
+    parameters: z.object({}),
+  })
+  async status(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    return ok(await this.upgrade.getStatus());
+  }
+
+  @Tool({
+    name: 'run_upgrade',
+    topic: ToolTopics.Platform,
+    title: 'Upgrade Ranch',
+    template: 'Upgrade Ranch to the latest version',
+    destructive: true,
+    description:
+      'Pull the latest Ranch from main, install dependencies and run migrations. The dev watchers pick the new code up, so the API may restart mid-call and the chat may drop for a moment. Refused when get_upgrade_status says not eligible. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async run(
+    args: { confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const eligibility = await this.upgrade.getStatus();
+    if (!eligibility.eligible) {
+      return err(
+        `Upgrade not allowed: ${eligibility.reason ?? 'this checkout is not eligible'}. Fix that first, then call get_upgrade_status again.`,
+      );
+    }
+    const refusal = confirmed(
+      args,
+      'upgrade Ranch in place (pull main, install, migrate) and restart the API',
+    );
+    if (refusal) return refusal;
+    this.logger.log('Upgrade started through MCP');
+    return ok(await this.upgrade.run());
+  }
+}
diff --git a/api/src/slices/usage/domain/index.ts b/api/src/slices/usage/domain/index.ts
index 77139fed..7d1a051c 100644
--- a/api/src/slices/usage/domain/index.ts
+++ b/api/src/slices/usage/domain/index.ts
@@ -1,3 +1,13 @@
 export * from './usage.types';
 export { IUsageGateway } from './usage.gateway';
 export { costUsd } from './model-pricing';
+export {
+  dayKey,
+  resolveAgentNames,
+  rollUpAcrossAgents,
+} from './usage-rollup';
+export type {
+  IAgentUsageTotals,
+  IUsageRollup,
+  IUsageTotals,
+} from './usage-rollup';
diff --git a/api/src/slices/usage/domain/usage-rollup.ts b/api/src/slices/usage/domain/usage-rollup.ts
new file mode 100644
index 00000000..8a523b1c
--- /dev/null
+++ b/api/src/slices/usage/domain/usage-rollup.ts
@@ -0,0 +1,142 @@
+import { costUsd } from './model-pricing';
+import type {
+  ICredentialUsageResponse,
+  IUsageDailyEntry,
+  IUsageData,
+} from './usage.types';
+
+/**
+ * The cross-agent roll-up behind `GET llms/:id/usage` and `GET usage/overview`,
+ * shared with the `get_usage_overview` tool so the chat and the console
+ * report the same dollars from the same rows (CLEAN-109).
+ */
+
+export interface IUsageTotals {
+  inputTokens: number;
+  outputTokens: number;
+  callCount: number;
+  costUsd: number;
+}
+
+export interface IAgentUsageTotals extends IUsageTotals {
+  agentId: string;
+}
+
+export interface IUsageRollup {
+  last30days: IUsageDailyEntry[];
+  totals: IUsageTotals;
+  topModel: string | null;
+  /** Sorted by cost, most expensive agent first. */
+  agentTotals: IAgentUsageTotals[];
+}
+
+export function dayKey(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+/**
+ * Rolls multi-agent usage rows up to the `${date}|${model}` grain the
+ * per-agent endpoint uses, plus per-agent totals.
+ */
+export function rollUpAcrossAgents(rows: IUsageData[]): IUsageRollup {
+  const dailyMap = new Map<string, IUsageDailyEntry>();
+  const agentMap = new Map<string, IAgentUsageTotals>();
+
+  for (const r of rows) {
+    const date = dayKey(r.date);
+    const dailyKey = `${date}|${r.model}`;
+    const cost = costUsd(r.model, r.inputTokens, r.outputTokens);
+
+    const daily = dailyMap.get(dailyKey);
+    if (daily) {
+      daily.inputTokens += r.inputTokens;
+      daily.outputTokens += r.outputTokens;
+      daily.callCount += r.callCount;
+      daily.costUsd += cost;
+    } else {
+      dailyMap.set(dailyKey, {
+        date,
+        model: r.model,
+        inputTokens: r.inputTokens,
+        outputTokens: r.outputTokens,
+        callCount: r.callCount,
+        costUsd: cost,
+      });
+    }
+
+    const agent = agentMap.get(r.agentId);
+    if (agent) {
+      agent.inputTokens += r.inputTokens;
+      agent.outputTokens += r.outputTokens;
+      agent.callCount += r.callCount;
+      agent.costUsd += cost;
+    } else {
+      agentMap.set(r.agentId, {
+        agentId: r.agentId,
+        inputTokens: r.inputTokens,
+        outputTokens: r.outputTokens,
+        callCount: r.callCount,
+        costUsd: cost,
+      });
+    }
+  }
+
+  const last30days = Array.from(dailyMap.values()).sort((a, b) =>
+    b.date.localeCompare(a.date),
+  );
+
+  const totals = last30days.reduce<IUsageTotals>(
+    (acc, e) => ({
+      inputTokens: acc.inputTokens + e.inputTokens,
+      outputTokens: acc.outputTokens + e.outputTokens,
+      callCount: acc.callCount + e.callCount,
+      costUsd: acc.costUsd + e.costUsd,
+    }),
+    { inputTokens: 0, outputTokens: 0, callCount: 0, costUsd: 0 },
+  );
+
+  const perModelTokens = new Map<string, number>();
+  for (const e of last30days) {
+    perModelTokens.set(
+      e.model,
+      (perModelTokens.get(e.model) ?? 0) + e.inputTokens + e.outputTokens,
+    );
+  }
+  let topModel: string | null = null;
+  let topTokens = -1;
+  for (const [m, t] of perModelTokens) {
+    if (t > topTokens) {
+      topTokens = t;
+      topModel = m;
+    }
+  }
+
+  const agentTotals = Array.from(agentMap.values()).sort(
+    (a, b) => b.costUsd - a.costUsd,
+  );
+
+  return { last30days, totals, topModel, agentTotals };
+}
+
+/**
+ * Resolve agent names. Failed lookups (deleted agents) fall back to the raw
+ * ID so the row is still visible — usage outlives the agent record.
+ */
+export async function resolveAgentNames(
+  agentTotals: IAgentUsageTotals[],
+  findAgent: (agentId: string) => Promise<{ name: string } | null>,
+): Promise<ICredentialUsageResponse['byAgent']> {
+  return Promise.all(
+    agentTotals.map(async (entry) => {
+      const agent = await findAgent(entry.agentId).catch(() => null);
+      return {
+        agentId: entry.agentId,
+        agentName: agent?.name ?? entry.agentId,
+        inputTokens: entry.inputTokens,
+        outputTokens: entry.outputTokens,
+        callCount: entry.callCount,
+        costUsd: entry.costUsd,
+      };
+    }),
+  );
+}
diff --git a/api/src/slices/usage/usage.controller.ts b/api/src/slices/usage/usage.controller.ts
index c3dd61e5..c6446b50 100644
--- a/api/src/slices/usage/usage.controller.ts
+++ b/api/src/slices/usage/usage.controller.ts
@@ -11,12 +11,16 @@ import {
 import { ApiTags, ApiOperation, ApiHeader } from '@nestjs/swagger';
 import { IUsageGateway } from './domain';
 import { costUsd } from './domain/model-pricing';
+import {
+  dayKey,
+  resolveAgentNames,
+  rollUpAcrossAgents,
+} from './domain/usage-rollup';
 import {
   IAgentUsageResponse,
   ICredentialUsageResponse,
   IOverviewUsageResponse,
   IUsageDailyEntry,
-  IUsageData,
 } from './domain/usage.types';
 import { ReportUsageDto } from './dtos';
 import { BridleApiKeyGuard } from '#/bridle/guards/bridleApiKey.guard';
@@ -32,10 +36,6 @@ interface IRuntimeUsageSnapshot {
   reportedAt: string | null;
 }
 
-function dayKey(d: Date): string {
-  return d.toISOString().slice(0, 10);
-}
-
 @ApiTags('usage')
 @Controller()
 export class UsageController {
@@ -212,8 +212,10 @@ export class UsageController {
   ): Promise<ICredentialUsageResponse> {
     const rows = await this.gateway.findRecentForCredential(credentialId, 30);
     const { last30days, totals, topModel, agentTotals } =
-      this.rollUpAcrossAgents(rows);
-    const byAgent = await this.resolveAgentNames(agentTotals);
+      rollUpAcrossAgents(rows);
+    const byAgent = await resolveAgentNames(agentTotals, (id) =>
+      this.agentGateway.findById(id),
+    );
     return { last30days, totals, topModel, byAgent };
   }
 
@@ -228,148 +230,10 @@ export class UsageController {
     // per agent per page view.
     const rows = await this.gateway.findRecentAll(30);
     const { last30days, totals, topModel, agentTotals } =
-      this.rollUpAcrossAgents(rows);
-    const byAgent = await this.resolveAgentNames(agentTotals);
-    return { last30days, totals, topModel, byAgent };
-  }
-
-  /**
-   * Rolls multi-agent usage rows up to the `${date}|${model}` grain the
-   * per-agent endpoint uses, plus per-agent totals. Shared by the
-   * credential and overview endpoints.
-   */
-  private rollUpAcrossAgents(rows: IUsageData[]): {
-    last30days: IUsageDailyEntry[];
-    totals: {
-      inputTokens: number;
-      outputTokens: number;
-      callCount: number;
-      costUsd: number;
-    };
-    topModel: string | null;
-    agentTotals: Array<{
-      agentId: string;
-      inputTokens: number;
-      outputTokens: number;
-      callCount: number;
-      costUsd: number;
-    }>;
-  } {
-    const dailyMap = new Map<string, IUsageDailyEntry>();
-    const agentMap = new Map<
-      string,
-      {
-        agentId: string;
-        inputTokens: number;
-        outputTokens: number;
-        callCount: number;
-        costUsd: number;
-      }
-    >();
-
-    for (const r of rows) {
-      const date = dayKey(r.date);
-      const dailyKey = `${date}|${r.model}`;
-      const cost = costUsd(r.model, r.inputTokens, r.outputTokens);
-
-      const daily = dailyMap.get(dailyKey);
-      if (daily) {
-        daily.inputTokens += r.inputTokens;
-        daily.outputTokens += r.outputTokens;
-        daily.callCount += r.callCount;
-        daily.costUsd += cost;
-      } else {
-        dailyMap.set(dailyKey, {
-          date,
-          model: r.model,
-          inputTokens: r.inputTokens,
-          outputTokens: r.outputTokens,
-          callCount: r.callCount,
-          costUsd: cost,
-        });
-      }
-
-      const agent = agentMap.get(r.agentId);
-      if (agent) {
-        agent.inputTokens += r.inputTokens;
-        agent.outputTokens += r.outputTokens;
-        agent.callCount += r.callCount;
-        agent.costUsd += cost;
-      } else {
-        agentMap.set(r.agentId, {
-          agentId: r.agentId,
-          inputTokens: r.inputTokens,
-          outputTokens: r.outputTokens,
-          callCount: r.callCount,
-          costUsd: cost,
-        });
-      }
-    }
-
-    const last30days = Array.from(dailyMap.values()).sort((a, b) =>
-      b.date.localeCompare(a.date),
-    );
-
-    const totals = last30days.reduce(
-      (acc, e) => ({
-        inputTokens: acc.inputTokens + e.inputTokens,
-        outputTokens: acc.outputTokens + e.outputTokens,
-        callCount: acc.callCount + e.callCount,
-        costUsd: acc.costUsd + e.costUsd,
-      }),
-      { inputTokens: 0, outputTokens: 0, callCount: 0, costUsd: 0 },
-    );
-
-    const perModelTokens = new Map<string, number>();
-    for (const e of last30days) {
-      perModelTokens.set(
-        e.model,
-        (perModelTokens.get(e.model) ?? 0) + e.inputTokens + e.outputTokens,
-      );
-    }
-    let topModel: string | null = null;
-    let topTokens = -1;
-    for (const [m, t] of perModelTokens) {
-      if (t > topTokens) {
-        topTokens = t;
-        topModel = m;
-      }
-    }
-
-    const agentTotals = Array.from(agentMap.values()).sort(
-      (a, b) => b.costUsd - a.costUsd,
-    );
-
-    return { last30days, totals, topModel, agentTotals };
-  }
-
-  /**
-   * Resolve agent names. Failed lookups (deleted agents) fall back to the
-   * raw ID so the row is still visible — usage outlives the agent record.
-   */
-  private async resolveAgentNames(
-    agentTotals: Array<{
-      agentId: string;
-      inputTokens: number;
-      outputTokens: number;
-      callCount: number;
-      costUsd: number;
-    }>,
-  ): Promise<ICredentialUsageResponse['byAgent']> {
-    return Promise.all(
-      agentTotals.map(async (entry) => {
-        const agent = await this.agentGateway
-          .findById(entry.agentId)
-          .catch(() => null);
-        return {
-          agentId: entry.agentId,
-          agentName: agent?.name ?? entry.agentId,
-          inputTokens: entry.inputTokens,
-          outputTokens: entry.outputTokens,
-          callCount: entry.callCount,
-          costUsd: entry.costUsd,
-        };
-      }),
+      rollUpAcrossAgents(rows);
+    const byAgent = await resolveAgentNames(agentTotals, (id) =>
+      this.agentGateway.findById(id),
     );
+    return { last30days, totals, topModel, byAgent };
   }
 }
diff --git a/api/src/slices/usage/usage.module.ts b/api/src/slices/usage/usage.module.ts
index 9e7a30c6..af59b99d 100644
--- a/api/src/slices/usage/usage.module.ts
+++ b/api/src/slices/usage/usage.module.ts
@@ -1,5 +1,6 @@
 import { Module } from '@nestjs/common';
 import { UsageController } from './usage.controller';
+import { UsageTool } from './usage.tool';
 import { IUsageGateway } from './domain/usage.gateway';
 import { UsageGateway } from './data/usage.gateway';
 import { UsageMapper } from './data/usage.mapper';
@@ -13,6 +14,7 @@ import { LlmModule } from '#/llm/llm.module';
   controllers: [UsageController],
   providers: [
     UsageMapper,
+    UsageTool,
     {
       provide: IUsageGateway,
       useClass: UsageGateway,
diff --git a/api/src/slices/usage/usage.tool.spec.ts b/api/src/slices/usage/usage.tool.spec.ts
new file mode 100644
index 00000000..61446ea4
--- /dev/null
+++ b/api/src/slices/usage/usage.tool.spec.ts
@@ -0,0 +1,209 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { UsageTool } from './usage.tool';
+import { costUsd } from './domain/model-pricing';
+import type { IUsageData } from './domain/usage.types';
+import type { IUsageGateway } from './domain';
+import type { IAgentGateway } from '#/agent/agent/domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * The tool must say the same dollars the console's Usage page says: same
+ * rows, same roll-up, same pricing. So the spec pins the gateway call the
+ * route makes (`findRecentAll(30)`) and the numbers that come out, not the
+ * tool's own arithmetic — it has none, it shares the controller's.
+ */
+const HAIKU = 'claude-haiku-4-5';
+const SONNET = 'claude-sonnet-4-6';
+
+const DAY_1 = new Date('2026-08-01T00:00:00.000Z');
+const DAY_2 = new Date('2026-08-02T00:00:00.000Z');
+
+function row(
+  p: Partial<IUsageData> & { agentId: string; model: string; date: Date },
+): IUsageData {
+  return {
+    id: `${p.agentId}|${p.model}|${p.date.toISOString()}`,
+    llmCredentialId: null,
+    inputTokens: 0,
+    outputTokens: 0,
+    callCount: 0,
+    createdAt: new Date(0),
+    updatedAt: new Date(0),
+    ...p,
+  };
+}
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+function harness(rows: IUsageData[], agentNames: Record<string, string> = {}) {
+  const findRecentAll = jest.fn().mockResolvedValue(rows);
+  const findById = jest.fn((id: string) => {
+    const name = agentNames[id];
+    if (!name) return Promise.reject(new Error('agent not found'));
+    return Promise.resolve({ id, name });
+  });
+  const tool = new UsageTool(
+    { findRecentAll } as unknown as IUsageGateway,
+    { findById } as unknown as IAgentGateway,
+  );
+  return { tool, findRecentAll, findById };
+}
+
+const text = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('UsageTool', () => {
+  describe('audience', () => {
+    it('is listed for an operator and hidden from a plain agent', async () => {
+      const { tool } = harness([]);
+      await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+      await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+    });
+
+    it('refuses the body for a plain agent without touching the gateway', async () => {
+      const { tool, findRecentAll } = harness([]);
+      await expect(
+        tool.getUsageOverview({}, undefined, plainAgent()),
+      ).rejects.toBeInstanceOf(ForbiddenException);
+      expect(findRecentAll).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('get_usage_overview', () => {
+    it('asks for the 30-day window and reports totals and per-agent cost like the route', async () => {
+      const rows = [
+        row({
+          agentId: 'agent-a',
+          model: HAIKU,
+          date: DAY_1,
+          inputTokens: 1000,
+          outputTokens: 500,
+          callCount: 3,
+        }),
+        row({
+          agentId: 'agent-b',
+          model: SONNET,
+          date: DAY_1,
+          inputTokens: 2000,
+          outputTokens: 1000,
+          callCount: 2,
+        }),
+        row({
+          agentId: 'agent-a',
+          model: HAIKU,
+          date: DAY_2,
+          inputTokens: 400,
+          outputTokens: 100,
+          callCount: 1,
+        }),
+      ];
+      const { tool, findRecentAll, findById } = harness(rows, {
+        'agent-a': 'Support Bot',
+        'agent-b': 'Research Bot',
+      });
+
+      const result = await tool.getUsageOverview({}, undefined, operator());
+
+      expect(findRecentAll).toHaveBeenCalledWith(30);
+      expect(findById).toHaveBeenCalledWith('agent-a');
+      expect(findById).toHaveBeenCalledWith('agent-b');
+
+      const expectedCost =
+        costUsd(HAIKU, 1000, 500) +
+        costUsd(SONNET, 2000, 1000) +
+        costUsd(HAIKU, 400, 100);
+      const body = JSON.parse(text(result)) as {
+        totals: {
+          inputTokens: number;
+          outputTokens: number;
+          callCount: number;
+          costUsd: number;
+        };
+        topModel: string | null;
+        last30days: { date: string; model: string }[];
+        byAgent: { agentId: string; agentName: string; costUsd: number }[];
+      };
+
+      expect(body.totals).toEqual({
+        inputTokens: 3400,
+        outputTokens: 1600,
+        callCount: 6,
+        costUsd: expectedCost,
+      });
+      // Sonnet carries 3000 tokens against Haiku's 2000.
+      expect(body.topModel).toBe(SONNET);
+      // Newest day first, one entry per date|model.
+      expect(body.last30days.map((e) => `${e.date}|${e.model}`)).toEqual([
+        `2026-08-02|${HAIKU}`,
+        `2026-08-01|${HAIKU}`,
+        `2026-08-01|${SONNET}`,
+      ]);
+      // Most expensive agent first, with the console's name for it.
+      expect(body.byAgent.map((a) => a.agentName)).toEqual([
+        'Research Bot',
+        'Support Bot',
+      ]);
+      expect(body.byAgent[0]).toEqual({
+        agentId: 'agent-b',
+        agentName: 'Research Bot',
+        inputTokens: 2000,
+        outputTokens: 1000,
+        callCount: 2,
+        costUsd: costUsd(SONNET, 2000, 1000),
+      });
+      expect(text(result)).toContain('"costUsd"');
+      expect(text(result)).toContain('"inputTokens": 3400');
+    });
+
+    it('keeps a deleted agent visible under its id', async () => {
+      const { tool } = harness(
+        [
+          row({
+            agentId: 'agent-gone',
+            model: HAIKU,
+            date: DAY_1,
+            inputTokens: 10,
+            outputTokens: 10,
+            callCount: 1,
+          }),
+        ],
+        {},
+      );
+
+      const result = await tool.getUsageOverview({}, undefined, operator());
+      const body = JSON.parse(text(result)) as {
+        byAgent: { agentId: string; agentName: string }[];
+      };
+
+      expect(body.byAgent).toEqual([
+        expect.objectContaining({
+          agentId: 'agent-gone',
+          agentName: 'agent-gone',
+        }),
+      ]);
+      expect(result.isError).toBeUndefined();
+    });
+
+    it('reports zero totals and no agents for an empty window', async () => {
+      const { tool, findById } = harness([]);
+
+      const result = await tool.getUsageOverview({}, undefined, operator());
+      const body = JSON.parse(text(result)) as Record<string, unknown>;
+
+      expect(body).toEqual({
+        last30days: [],
+        totals: { inputTokens: 0, outputTokens: 0, callCount: 0, costUsd: 0 },
+        topModel: null,
+        byAgent: [],
+      });
+      expect(findById).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/api/src/slices/usage/usage.tool.ts b/api/src/slices/usage/usage.tool.ts
new file mode 100644
index 00000000..daea7d51
--- /dev/null
+++ b/api/src/slices/usage/usage.tool.ts
@@ -0,0 +1,75 @@
+import { Injectable } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import { IAuthTokenPayload } from '#/user/auth/domain';
+import { IAgentGateway } from '#/agent/agent/domain';
+import { IUsageGateway } from './domain';
+import { resolveAgentNames, rollUpAcrossAgents } from './domain/usage-rollup';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** The console's overview window. `GET usage/overview` takes no other. */
+const OVERVIEW_DAYS = 30;
+
+/**
+ * The console's "Usage" overview from the chat (CLEAN-109): what
+ * `GET usage/overview` returns, computed the same way — the same DB rows
+ * from `IUsageGateway`, rolled up by `rollUpAcrossAgents` and priced by
+ * `costUsd`, with agent names resolved through `IAgentGateway`. Today's
+ * not-yet-reported runtime usage is excluded here as it is in the console;
+ * `agent_usage` is the per-agent view.
+ *
+ * Operator agents only: spend across the whole Ranch is not a plain agent's
+ * business. The class is hidden from a plain agent's list and refuses the
+ * body as well, like every other operator tool.
+ */
+@Injectable()
+export class UsageTool implements IConditionallyListedTool {
+  constructor(
+    private readonly usage: IUsageGateway,
+    private readonly agents: IAgentGateway,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'get_usage_overview',
+    topic: ToolTopics.ChatsUsage,
+    title: 'Usage across all agents',
+    template: 'How much did all agents cost in the last 30 days?',
+    description:
+      'Token usage and cost across every agent of this Ranch for the last ' +
+      "30 days, as the console's Usage overview shows it: `totals` " +
+      '(input/output tokens, calls, costUsd), `topModel`, `last30days` ' +
+      'rolled up per date and model, and `byAgent` sorted by cost with the ' +
+      'most expensive agent first (a deleted agent shows its id as the ' +
+      'name). Reported usage only — the current day is included once each ' +
+      'agent has posted its daily report. For one agent in detail, or a ' +
+      'different window, call agent_usage.',
+    parameters: z.object({}),
+  })
+  async getUsageOverview(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const rows = await this.usage.findRecentAll(OVERVIEW_DAYS);
+    const { last30days, totals, topModel, agentTotals } =
+      rollUpAcrossAgents(rows);
+    const byAgent = await resolveAgentNames(agentTotals, (id) =>
+      this.agents.findById(id),
+    );
+    return ok({ last30days, totals, topModel, byAgent });
+  }
+}
diff --git a/api/src/slices/user/apiKey/apiKey.module.ts b/api/src/slices/user/apiKey/apiKey.module.ts
index 0657f875..85cc409c 100644
--- a/api/src/slices/user/apiKey/apiKey.module.ts
+++ b/api/src/slices/user/apiKey/apiKey.module.ts
@@ -4,6 +4,7 @@ import { IApiKeyGateway } from './domain/apiKey.gateway';
 import { ApiKeyService } from './domain/apiKey.service';
 import { ApiKeyGateway } from './data/apiKey.gateway';
 import { ApiKeyMapper } from './data/apiKey.mapper';
+import { ApiKeyTool } from './apiKey.tool';
 import { AuthModule } from '#/user/auth/auth.module';
 
 @Module({
@@ -16,6 +17,7 @@ import { AuthModule } from '#/user/auth/auth.module';
       provide: IApiKeyGateway,
       useClass: ApiKeyGateway,
     },
+    ApiKeyTool,
   ],
   exports: [IApiKeyGateway, ApiKeyService],
 })
diff --git a/api/src/slices/user/apiKey/apiKey.tool.spec.ts b/api/src/slices/user/apiKey/apiKey.tool.spec.ts
new file mode 100644
index 00000000..8857bd3a
--- /dev/null
+++ b/api/src/slices/user/apiKey/apiKey.tool.spec.ts
@@ -0,0 +1,232 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { ApiKeyTool, KEY_SHOWN_ONCE } from './apiKey.tool';
+import { ApiKeyScopeTypes } from './domain';
+import type { IApiKeyGateway, ApiKeyService } from './domain';
+import { UserRoleTypes } from '#/user/user/domain';
+
+/**
+ * An API key with the `admin` scope is the whole API. Three properties matter
+ * more than any happy path: a plain agent cannot see or call these tools, a
+ * listing never carries a hash or a key, and the one place a key IS returned
+ * (creation) says out loud that it will not be shown again.
+ */
+const SENTINEL_HASH = 'SENTINEL-HASH';
+const PLAINTEXT_KEY = 'rk_PLAINTEXT-ONCE-abc123';
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+/**
+ * A row as a careless gateway might return it: the domain type has no hash,
+ * but the tool must not depend on that staying true.
+ */
+const row = (overrides: Record<string, unknown> = {}) => ({
+  id: 'apikey-1',
+  name: 'Marketing site embed',
+  prefix: 'x9Qz',
+  scopes: [ApiKeyScopeTypes.EmbedMint],
+  lastUsedAt: null,
+  expiresAt: new Date('2027-01-01T00:00:00.000Z'),
+  createdBy: 'user-1',
+  createdAt: new Date('2026-09-17T10:00:00.000Z'),
+  keyHash: SENTINEL_HASH,
+  key: SENTINEL_HASH,
+  ...overrides,
+});
+
+interface Harness {
+  tool: ApiKeyTool;
+  gateway: { findById: jest.Mock; findAll: jest.Mock };
+  service: { list: jest.Mock; create: jest.Mock; revoke: jest.Mock };
+}
+
+function harness(): Harness {
+  const gateway = {
+    findById: jest.fn().mockResolvedValue(row()),
+    findAll: jest.fn().mockResolvedValue([row()]),
+  };
+  const service = {
+    list: jest
+      .fn()
+      .mockResolvedValue([row(), row({ id: 'apikey-2', name: 'CI' })]),
+    create: jest.fn().mockResolvedValue({
+      apiKey: row({
+        id: 'apikey-new',
+        name: 'New key',
+        createdBy: 'agent:agent-ops',
+      }),
+      key: PLAINTEXT_KEY,
+    }),
+    revoke: jest.fn().mockResolvedValue(undefined),
+  };
+  const tool = new ApiKeyTool(
+    gateway as unknown as IApiKeyGateway,
+    service as unknown as ApiKeyService,
+  );
+  return { tool, gateway, service };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('ApiKeyTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, service } = harness();
+    await expect(
+      tool.createApiKey(
+        { name: 'Sneaky', scopes: [ApiKeyScopeTypes.Admin] },
+        null,
+        plainAgent(),
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(service.create).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool } = harness();
+    await expect(
+      tool.listApiKeys({}, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('ApiKeyTool — listing', () => {
+  it('lists prefix and metadata, never a hash or a key', async () => {
+    const { tool, service } = harness();
+    const text = textOf(await tool.listApiKeys({}, null, operator()));
+    expect(service.list).toHaveBeenCalled();
+    expect(text).toContain('apikey-1');
+    expect(text).toContain('Marketing site embed');
+    expect(text).toContain('x9Qz');
+    expect(text).toContain('embed:mint');
+    expect(text).toContain('2027-01-01T00:00:00.000Z');
+    expect(text).not.toContain(SENTINEL_HASH);
+    expect(text).not.toContain('keyHash');
+  });
+
+  it('tells the model where the id goes', async () => {
+    const { tool } = harness();
+    const parsed = JSON.parse(
+      textOf(await tool.listApiKeys({}, null, operator())),
+    );
+    expect(parsed.apiKeys).toHaveLength(2);
+    expect(parsed.apiKeys[1]).toMatchObject({ id: 'apikey-2', name: 'CI' });
+  });
+});
+
+describe('ApiKeyTool — creating', () => {
+  it('creates the key as the calling agent and returns the plaintext once', async () => {
+    const { tool, service } = harness();
+    const result = await tool.createApiKey(
+      {
+        name: 'New key',
+        scopes: [ApiKeyScopeTypes.EmbedMint, ApiKeyScopeTypes.EmbedMint],
+        expiresAt: '2027-01-01T00:00:00.000Z',
+      },
+      null,
+      operator(),
+    );
+    expect(service.create).toHaveBeenCalledWith({
+      name: 'New key',
+      scopes: [ApiKeyScopeTypes.EmbedMint],
+      expiresAt: new Date('2027-01-01T00:00:00.000Z'),
+      createdBy: 'agent:agent-ops',
+    });
+    const text = textOf(result);
+    expect(result.isError).toBeUndefined();
+    expect(text).toContain(PLAINTEXT_KEY);
+    expect(text).toContain(KEY_SHOWN_ONCE);
+    expect(text).toContain(
+      'This key is shown once. Hand it to the person verbatim and do not repeat it in later messages.',
+    );
+    expect(text).toContain('apikey-new');
+    // The hash is still not a thing a tool result carries, even here.
+    expect(text).not.toContain(SENTINEL_HASH);
+  });
+
+  it('passes no expiry when none is given', async () => {
+    const { tool, service } = harness();
+    await tool.createApiKey(
+      { name: 'Forever', scopes: [ApiKeyScopeTypes.Admin] },
+      null,
+      operator(),
+    );
+    expect(service.create).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'Forever', expiresAt: null }),
+    );
+  });
+
+  it('refuses a date it cannot parse without minting anything', async () => {
+    const { tool, service } = harness();
+    const result = await tool.createApiKey(
+      {
+        name: 'Oops',
+        scopes: [ApiKeyScopeTypes.Admin],
+        expiresAt: 'next tuesday',
+      },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('expiresAt');
+    expect(service.create).not.toHaveBeenCalled();
+  });
+});
+
+describe('ApiKeyTool — revoking', () => {
+  it('refuses without confirm, names the key, and touches nothing', async () => {
+    const { tool, service } = harness();
+    const result = await tool.revokeApiKey(
+      { id: 'apikey-1' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Marketing site embed');
+    expect(textOf(result)).toContain('confirm: true');
+    expect(service.revoke).not.toHaveBeenCalled();
+  });
+
+  it('revokes once confirmed', async () => {
+    const { tool, service } = harness();
+    const result = await tool.revokeApiKey(
+      { id: 'apikey-1', confirm: true },
+      null,
+      operator(),
+    );
+    expect(service.revoke).toHaveBeenCalledWith('apikey-1');
+    expect(result.isError).toBeUndefined();
+    expect(textOf(result)).toContain('Marketing site embed');
+    expect(textOf(result)).toContain('create_api_key');
+    expect(textOf(result)).not.toContain(SENTINEL_HASH);
+  });
+
+  it('reports a missing key before asking for a confirmation', async () => {
+    const { tool, gateway, service } = harness();
+    gateway.findById.mockResolvedValue(null);
+    const result = await tool.revokeApiKey(
+      { id: 'apikey-gone' },
+      null,
+      operator(),
+    );
+    expect(textOf(result)).toContain('apikey-gone');
+    expect(textOf(result)).toContain('list_api_keys');
+    expect(service.revoke).not.toHaveBeenCalled();
+  });
+});
diff --git a/api/src/slices/user/apiKey/apiKey.tool.ts b/api/src/slices/user/apiKey/apiKey.tool.ts
new file mode 100644
index 00000000..65d10083
--- /dev/null
+++ b/api/src/slices/user/apiKey/apiKey.tool.ts
@@ -0,0 +1,223 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import type { IAuthTokenPayload } from '#/user/auth/domain';
+import { ApiKeyScopeTypes, IApiKeyGateway, ApiKeyService } from './domain';
+import type { IApiKeyData } from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** What the person reads right after the key: it exists nowhere else. */
+export const KEY_SHOWN_ONCE =
+  'This key is shown once. Hand it to the person verbatim and do not ' +
+  'repeat it in later messages.';
+
+/** What `CreateApiKeyDto` allows for a name. */
+const MIN_NAME_LENGTH = 2;
+
+const scopeSchema = z
+  .nativeEnum(ApiKeyScopeTypes)
+  .describe(
+    'embed:mint — mint browser embed tokens; embed:mint-admin — the same ' +
+      'but keeping Owner/Admin roles (effectively admin); admin — the full API.',
+  );
+
+/**
+ * A row as a tool result: the prefix and the metadata the console table
+ * shows, listed field by field. A whitelist rather than a strip of known
+ * secret names, because the one thing this listing must never carry is the
+ * key hash, and a gateway that someday returns it (or the key itself) must
+ * not get a say (FR-004).
+ */
+function toToolApiKey(row: IApiKeyData) {
+  return {
+    id: row.id,
+    name: row.name,
+    prefix: row.prefix,
+    scopes: row.scopes,
+    lastUsedAt: row.lastUsedAt ? row.lastUsedAt.toISOString() : null,
+    expiresAt: row.expiresAt ? row.expiresAt.toISOString() : null,
+    createdBy: row.createdBy,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+function notFound(id: string): ToolResult {
+  return ok({
+    error: `API key ${id} not found — call list_api_keys to find the id`,
+  });
+}
+
+/**
+ * The API keys page from the chat (CLEAN-109). Every call goes through
+ * `ApiKeyService` and `IApiKeyGateway`, the pair `ApiKeyController` injects,
+ * so the key format, the hashing and the prefix are decided in one place.
+ *
+ * This is the one tool file allowed to hand a secret back: `create_api_key`
+ * returns the plaintext key once, exactly as the console does, because only
+ * its hash is persisted and the key exists nowhere else afterwards (research
+ * R6). Everything else here returns prefix and metadata only.
+ *
+ * Operator agents only: a key with the `admin` scope is the whole API, and a
+ * plain agent must not be able to mint one on a prompt's say-so.
+ */
+@Injectable()
+export class ApiKeyTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(ApiKeyTool.name);
+
+  constructor(
+    private readonly gateway: IApiKeyGateway,
+    private readonly service: ApiKeyService,
+  ) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'list_api_keys',
+    topic: ToolTopics.UsersKeys,
+    title: 'List API keys',
+    template: 'List the API keys',
+    description:
+      'Every API key of this Ranch with its id, name, the last 4 characters ' +
+      '(prefix), scopes, expiry, last use and who created it — never the key ' +
+      'itself; the server only keeps a hash, so no tool can show it again. ' +
+      'Read this to turn a name the person said into the id revoke_api_key ' +
+      'needs.',
+  })
+  async listApiKeys(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const rows = await this.service.list();
+    return ok({ apiKeys: rows.map(toToolApiKey) });
+  }
+
+  @Tool({
+    name: 'create_api_key',
+    topic: ToolTopics.UsersKeys,
+    title: 'Create an API key',
+    template: 'Create an API key named «name» with the scopes «scopes»',
+    description:
+      'Mint a new API key. The result carries the plaintext key ONCE: only ' +
+      'its hash is stored, so it cannot be shown again by any tool or the ' +
+      'console. ' +
+      KEY_SHOWN_ONCE +
+      ' Scopes: embed:mint mints browser embed tokens; embed:mint-admin ' +
+      'keeps Owner/Admin roles in them (treat it like admin); admin is the ' +
+      'full API. Omit expiresAt for a key that never expires. The key is ' +
+      'recorded as created by the calling agent (agent:<id>), which is what ' +
+      'the API keys page shows in its "created by" column.',
+    parameters: z.object({
+      name: z
+        .string()
+        .min(MIN_NAME_LENGTH)
+        .describe('A label for the key, e.g. "Marketing site embed"'),
+      scopes: z.array(scopeSchema).min(1).describe('At least one scope'),
+      expiresAt: z
+        .string()
+        .optional()
+        .describe(
+          'ISO date-time when the key stops working, e.g. 2027-01-01T00:00:00Z. Omit for no expiry.',
+        ),
+    }),
+  })
+  async createApiKey(
+    {
+      name,
+      scopes,
+      expiresAt,
+    }: { name: string; scopes: ApiKeyScopeTypes[]; expiresAt?: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    // The controller takes `req.user.sub` as-is; for an admin agent that is
+    // `agent:<id>`. The column is a plain string, so it is stored the same way.
+    const createdBy = httpRequest.user?.sub;
+    if (!createdBy)
+      return err('Cannot tell who is calling; not creating a key.');
+    const expiry = expiresAt ? new Date(expiresAt) : null;
+    if (expiry && Number.isNaN(expiry.getTime())) {
+      return err(
+        `expiresAt "${expiresAt}" is not an ISO date-time. Use e.g. 2027-01-01T00:00:00Z, or omit it.`,
+      );
+    }
+    const created = await this.service.create({
+      name,
+      // The DTO rejects duplicates with a 400; a tool call with the same
+      // scope twice means the same thing, so fold it instead of refusing.
+      scopes: Array.from(new Set(scopes)),
+      expiresAt: expiry,
+      createdBy,
+    });
+    // Log the id and name, never the key: the API log is not a secret store.
+    this.logger.log(
+      `API key created through MCP: id=${created.apiKey.id} name=${name} by=${createdBy}`,
+    );
+    return ok({
+      apiKey: toToolApiKey(created.apiKey),
+      key: created.key,
+      note: KEY_SHOWN_ONCE,
+    });
+  }
+
+  @Tool({
+    name: 'revoke_api_key',
+    topic: ToolTopics.UsersKeys,
+    title: 'Revoke an API key',
+    template: 'Revoke the API key «name»',
+    destructive: true,
+    description:
+      'Delete an API key. Anything still sending it stops authenticating ' +
+      'immediately, and it cannot be restored — the person would create a ' +
+      'new key and roll it out again. Takes the id: list_api_keys turns a ' +
+      'name into one. ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      id: z.string().describe('Key id, e.g. apikey-… (list_api_keys has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async revokeApiKey(
+    args: { id: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { id } = args;
+    const found = await this.gateway.findById(id);
+    if (!found) return notFound(id);
+    const refusal = confirmed(
+      args,
+      `revoke the API key «${found.name}» (…${found.prefix}) — whatever uses it stops working at once`,
+    );
+    if (refusal) return refusal;
+    await this.service.revoke(id);
+    this.logger.log(`API key revoked through MCP: id=${id} name=${found.name}`);
+    return ok({
+      ok: true,
+      id,
+      name: found.name,
+      note:
+        `API key «${found.name}» is revoked. Anything that was using it needs ` +
+        'a new key — create_api_key mints one.',
+    });
+  }
+}
diff --git a/api/src/slices/user/user/user.module.ts b/api/src/slices/user/user/user.module.ts
index 7867143a..df048a3c 100644
--- a/api/src/slices/user/user/user.module.ts
+++ b/api/src/slices/user/user/user.module.ts
@@ -1,5 +1,6 @@
 import { Module, forwardRef } from '@nestjs/common';
 import { UserController } from './user.controller';
+import { UserTool } from './user.tool';
 import { IUserGateway } from './domain/user.gateway';
 import { UserGateway } from './data/user.gateway';
 import { UserMapper } from './data/user.mapper';
@@ -10,6 +11,7 @@ import { AuthModule } from '#/user/auth/auth.module';
   controllers: [UserController],
   providers: [
     UserMapper,
+    UserTool,
     {
       provide: IUserGateway,
       useClass: UserGateway,
diff --git a/api/src/slices/user/user/user.tool.spec.ts b/api/src/slices/user/user/user.tool.spec.ts
new file mode 100644
index 00000000..1f4cb978
--- /dev/null
+++ b/api/src/slices/user/user/user.tool.spec.ts
@@ -0,0 +1,393 @@
+import { ForbiddenException } from '@nestjs/common';
+import type { Request } from 'express';
+import { UserTool } from './user.tool';
+import type { IUserGateway } from './domain';
+import { UserRoleTypes } from './domain';
+
+/**
+ * These tools put user accounts within a model's reach. Two properties are
+ * worth more than any happy path: a password that went in through a tool
+ * never comes back out of one (the sentinel below is the canary, also when
+ * the gateway hands back rows with a hash on them), and the Owner account
+ * survives whatever a prompt asks — the same rules `UserController` has.
+ */
+const SENTINEL = 'SENTINEL-PASS-99';
+
+const request = (roles: UserRoleTypes[]): Request =>
+  ({
+    user: { sub: 'agent:agent-ops', email: '', roles },
+  }) as unknown as Request;
+
+const operator = () => request([UserRoleTypes.Owner]);
+const plainAgent = () => request([UserRoleTypes.Agent]);
+
+const at = new Date('2026-09-17T10:00:00.000Z');
+
+const owner = {
+  id: 'user-owner',
+  name: 'Ranch Owner',
+  email: 'owner@ranch.test',
+  role: UserRoleTypes.Owner,
+  status: 'active' as const,
+  createdAt: at,
+  updatedAt: at,
+};
+
+const jane = {
+  id: 'user-jane',
+  name: 'Jane Doe',
+  email: 'jane@ranch.test',
+  role: UserRoleTypes.User,
+  status: 'invited' as const,
+  createdAt: at,
+  updatedAt: at,
+};
+
+interface Harness {
+  tool: UserTool;
+  users: {
+    findAll: jest.Mock;
+    findById: jest.Mock;
+    create: jest.Mock;
+    update: jest.Mock;
+    delete: jest.Mock;
+  };
+}
+
+function harness(): Harness {
+  const users = {
+    findAll: jest.fn().mockResolvedValue([owner, jane]),
+    findById: jest.fn(
+      async (id: string) => [owner, jane].find((u) => u.id === id) ?? null,
+    ),
+    create: jest.fn(async (data: { name: string; email: string }) => ({
+      ...jane,
+      id: 'user-new',
+      name: data.name,
+      email: data.email,
+    })),
+    update: jest.fn(async (id: string, patch: Record<string, unknown>) => ({
+      ...([owner, jane].find((u) => u.id === id) ?? jane),
+      ...patch,
+    })),
+    delete: jest.fn().mockResolvedValue(undefined),
+  };
+  const tool = new UserTool(users as unknown as IUserGateway);
+  return { tool, users };
+}
+
+const textOf = (result: { content: { text: string }[] }) =>
+  result.content[0].text;
+
+describe('UserTool — who may use it', () => {
+  it('hides the tools from an agent that is not a Ranch operator', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(plainAgent())).resolves.toBe(false);
+  });
+
+  it('lists them for an operator agent', async () => {
+    const { tool } = harness();
+    await expect(tool.isListedForRequest(operator())).resolves.toBe(true);
+  });
+
+  it('refuses a call from a plain agent even by name', async () => {
+    const { tool, users } = harness();
+    await expect(tool.listUsers({}, null, plainAgent())).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+    await expect(
+      tool.deleteUser({ userId: jane.id, confirm: true }, null, plainAgent()),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+    expect(users.findAll).not.toHaveBeenCalled();
+    expect(users.delete).not.toHaveBeenCalled();
+  });
+
+  it('refuses a caller with no roles at all', async () => {
+    const { tool } = harness();
+    await expect(
+      tool.getUser({ userId: jane.id }, null, {} as Request),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+});
+
+describe('UserTool — reading', () => {
+  it('lists every user with role and status', async () => {
+    const { tool, users } = harness();
+    const text = textOf(await tool.listUsers({}, null, operator()));
+    expect(users.findAll).toHaveBeenCalledTimes(1);
+    expect(text).toContain('jane@ranch.test');
+    expect(text).toContain('owner@ranch.test');
+    expect(text).toContain('"role": "User"');
+    expect(text).toContain('"status": "invited"');
+  });
+
+  it('never lists a password hash, even when the gateway hands one back', async () => {
+    const { tool, users } = harness();
+    users.findAll.mockResolvedValue([
+      { ...jane, password: SENTINEL },
+      { ...owner, passwordHash: SENTINEL },
+    ]);
+    const text = textOf(await tool.listUsers({}, null, operator()));
+    expect(text).toContain('jane@ranch.test');
+    expect(text).not.toContain(SENTINEL);
+    expect(text).not.toContain('password');
+  });
+
+  it('shows one user by id', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.getUser({ userId: jane.id }, null, operator()),
+    );
+    expect(users.findById).toHaveBeenCalledWith(jane.id);
+    expect(text).toContain('Jane Doe');
+    expect(text).toContain('"id": "user-jane"');
+  });
+
+  it('names list_users when the user does not exist', async () => {
+    const { tool } = harness();
+    const text = textOf(
+      await tool.getUser({ userId: 'user-nope' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_users');
+  });
+});
+
+describe('UserTool — creating', () => {
+  it('creates a user through the gateway and hands back the row without the password', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.createUser(
+        {
+          name: 'New Person',
+          email: 'new@ranch.test',
+          password: SENTINEL,
+          role: UserRoleTypes.Admin,
+        },
+        null,
+        operator(),
+      ),
+    );
+    expect(users.create).toHaveBeenCalledWith({
+      name: 'New Person',
+      email: 'new@ranch.test',
+      password: SENTINEL,
+      role: UserRoleTypes.Admin,
+    });
+    expect(text).toContain('"id": "user-new"');
+    expect(text).toContain('new@ranch.test');
+    expect(text).not.toContain(SENTINEL);
+  });
+
+  it('strips a password the gateway echoes back on the created row', async () => {
+    const { tool, users } = harness();
+    users.create.mockResolvedValue({ ...jane, password: SENTINEL });
+    const text = textOf(
+      await tool.createUser(
+        { name: 'Jane Doe', email: 'jane@ranch.test', password: SENTINEL },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).not.toContain(SENTINEL);
+  });
+});
+
+describe('UserTool — updating', () => {
+  it('passes only the given fields to the gateway', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.updateUser(
+        { userId: jane.id, name: 'Jane Smith', status: 'active' },
+        null,
+        operator(),
+      ),
+    );
+    expect(users.update).toHaveBeenCalledWith(jane.id, {
+      name: 'Jane Smith',
+      status: 'active',
+    });
+    expect(text).toContain('Jane Smith');
+    expect(text).toContain('"status": "active"');
+  });
+
+  it('accepts a new password and never repeats it', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.updateUser(
+        { userId: jane.id, password: SENTINEL },
+        null,
+        operator(),
+      ),
+    );
+    expect(users.update).toHaveBeenCalledWith(jane.id, { password: SENTINEL });
+    expect(text).not.toContain(SENTINEL);
+  });
+
+  it('refuses to change the Owner account status, as the controller does', async () => {
+    const { tool, users } = harness();
+    const result = await tool.updateUser(
+      { userId: owner.id, status: 'disabled' },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Owner account status cannot be changed');
+    expect(users.update).not.toHaveBeenCalled();
+  });
+
+  it('still lets the Owner rename themselves', async () => {
+    const { tool, users } = harness();
+    await tool.updateUser(
+      { userId: owner.id, name: 'The Boss' },
+      null,
+      operator(),
+    );
+    expect(users.update).toHaveBeenCalledWith(owner.id, { name: 'The Boss' });
+  });
+
+  it('asks for at least one field', async () => {
+    const { tool, users } = harness();
+    const result = await tool.updateUser({ userId: jane.id }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(users.update).not.toHaveBeenCalled();
+  });
+
+  it('names list_users when the user does not exist', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.updateUser(
+        { userId: 'user-nope', name: 'X Y' },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(users.update).not.toHaveBeenCalled();
+  });
+});
+
+describe('UserTool — setting a role', () => {
+  it('changes the role once confirmed', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.setUserRole(
+        { userId: jane.id, role: UserRoleTypes.Admin, confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(users.update).toHaveBeenCalledWith(jane.id, {
+      role: UserRoleTypes.Admin,
+    });
+    expect(text).toContain('"role": "Admin"');
+  });
+
+  it('refuses without the confirmation argument and names the user by email', async () => {
+    const { tool, users } = harness();
+    const result = await tool.setUserRole(
+      { userId: jane.id, role: UserRoleTypes.Admin },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(textOf(result)).toContain('«jane@ranch.test»');
+    expect(users.update).not.toHaveBeenCalled();
+  });
+
+  it('reports not-found before asking for a confirmation', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.setUserRole(
+        { userId: 'user-nope', role: UserRoleTypes.Admin },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('not found');
+    expect(users.update).not.toHaveBeenCalled();
+  });
+
+  it('never re-roles the Owner, as the controller does', async () => {
+    const { tool, users } = harness();
+    const result = await tool.setUserRole(
+      { userId: owner.id, role: UserRoleTypes.User, confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Owner role cannot be changed');
+    expect(users.update).not.toHaveBeenCalled();
+  });
+
+  it('never assigns Owner, as the DTO whitelist does', async () => {
+    const { tool, users } = harness();
+    const result = await tool.setUserRole(
+      { userId: jane.id, role: UserRoleTypes.Owner, confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(users.update).not.toHaveBeenCalled();
+  });
+
+  it('is a no-op when the user already has that role', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.setUserRole(
+        { userId: jane.id, role: UserRoleTypes.User },
+        null,
+        operator(),
+      ),
+    );
+    expect(text).toContain('already has the role');
+    expect(users.update).not.toHaveBeenCalled();
+  });
+});
+
+describe('UserTool — removing', () => {
+  it('removes the user once confirmed', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.deleteUser(
+        { userId: jane.id, confirm: true },
+        null,
+        operator(),
+      ),
+    );
+    expect(users.delete).toHaveBeenCalledWith(jane.id);
+    expect(text).toContain('jane@ranch.test');
+  });
+
+  it('refuses without the confirmation argument and names the user by email', async () => {
+    const { tool, users } = harness();
+    const result = await tool.deleteUser({ userId: jane.id }, null, operator());
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('confirm: true');
+    expect(textOf(result)).toContain('«jane@ranch.test»');
+    expect(users.delete).not.toHaveBeenCalled();
+  });
+
+  it('reports not-found before asking for a confirmation', async () => {
+    const { tool, users } = harness();
+    const text = textOf(
+      await tool.deleteUser({ userId: 'user-nope' }, null, operator()),
+    );
+    expect(text).toContain('not found');
+    expect(text).toContain('list_users');
+    expect(users.delete).not.toHaveBeenCalled();
+  });
+
+  it('never removes the Owner, as the controller does', async () => {
+    const { tool, users } = harness();
+    const result = await tool.deleteUser(
+      { userId: owner.id, confirm: true },
+      null,
+      operator(),
+    );
+    expect(result.isError).toBe(true);
+    expect(textOf(result)).toContain('Owner account cannot be removed');
+    expect(users.delete).not.toHaveBeenCalled();
+  });
+});
diff --git a/api/src/slices/user/user/user.tool.ts b/api/src/slices/user/user/user.tool.ts
new file mode 100644
index 00000000..12d1596c
--- /dev/null
+++ b/api/src/slices/user/user/user.tool.ts
@@ -0,0 +1,344 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { Request } from 'express';
+import { z } from 'zod';
+import { Tool, ToolTopics } from '#mcp';
+import {
+  callerIsOperator,
+  CONFIRM_SENTENCE,
+  confirmed,
+  err,
+  ok,
+  requireOperator,
+  stripSecrets,
+  type ToolResult,
+} from '#/mcp/tooling';
+import type { IConditionallyListedTool } from '#/mcp/interfaces/conditional-listing.interface';
+import type { IAuthTokenPayload } from '#/user/auth/domain';
+import {
+  ASSIGNABLE_USER_ROLES,
+  IUserGateway,
+  UserRoleTypes,
+  type IUpdateUserData,
+  type IUserData,
+  type UserStatusTypes,
+} from './domain';
+
+type AuthedRequest = Request & { user?: IAuthTokenPayload };
+
+/** What `CreateUserDto` / `UpdateUserDto` validate, expressed for the model. */
+const nameSchema = z.string().min(2).describe('Display name, at least 2 chars');
+const emailSchema = z.string().email().describe('Login email');
+const passwordSchema = z
+  .string()
+  .min(8)
+  .describe('Initial password, at least 8 chars — it is never shown again');
+const statusSchema = z
+  .enum(['active', 'invited', 'disabled'])
+  .describe('Account status');
+/** Owner is deliberately not assignable — it exists once, created via /init. */
+const roleSchema = z
+  .enum([UserRoleTypes.Admin, UserRoleTypes.User])
+  .describe(`Role to assign: ${ASSIGNABLE_USER_ROLES.join(' or ')}`);
+
+/** Fields that never leave a user row through a tool (FR-004). */
+const USER_SECRET_KEYS = ['password', 'passwordHash'] as const;
+
+/**
+ * The Users page of the console from the chat (CLEAN-109). Every call goes
+ * through `IUserGateway`, the gateway `UserController` injects, so hashing,
+ * email normalisation and the role whitelist stay where they are.
+ *
+ * The controller's rules are mirrored, not re-derived: the Owner account
+ * cannot be removed, re-roled or have its status changed, and the role
+ * endpoint only accepts Admin or User. Where the controller answers 403 the
+ * tool answers with the same sentence plus the next move, because a model
+ * that reads a bare "forbidden" wastes a turn guessing why.
+ *
+ * Passwords go IN through a tool and never come OUT: a result lands in a
+ * model's context and from there in a transcript, so rows are stripped of
+ * `password` / `passwordHash` even though the gateway's mapper already omits
+ * them — the mapper is one refactor away from not doing so.
+ *
+ * Operator agents only. Role changes and removals are Owner-only in the
+ * controller; operator gating already means the Owner role, so the same
+ * caller reaches both.
+ */
+@Injectable()
+export class UserTool implements IConditionallyListedTool {
+  private readonly logger = new Logger(UserTool.name);
+
+  constructor(private readonly users: IUserGateway) {}
+
+  async isListedForRequest(httpRequest: Request): Promise<boolean> {
+    return Promise.resolve(callerIsOperator(httpRequest));
+  }
+
+  @Tool({
+    name: 'list_users',
+    topic: ToolTopics.UsersKeys,
+    title: 'List users',
+    template: 'List the users of this Ranch',
+    description:
+      'Every user account of this Ranch: id, name, email, role and status. ' +
+      'Never a password. Read this to turn an email the person said into ' +
+      'the id the other user tools take.',
+  })
+  async listUsers(
+    _args: Record<string, never>,
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const rows = await this.users.findAll();
+    return ok({ users: rows.map(publicUser) });
+  }
+
+  @Tool({
+    name: 'get_user',
+    topic: ToolTopics.UsersKeys,
+    title: 'Show a user',
+    template: 'Show the user «email»',
+    description:
+      'One user account by id: name, email, role, status and timestamps, ' +
+      'never a password. Takes the user id — list_users turns an email into ' +
+      'one.',
+    parameters: z.object({
+      userId: z.string().describe('User id, e.g. user-… (list_users has them)'),
+    }),
+  })
+  async getUser(
+    { userId }: { userId: string },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const user = await this.users.findById(userId);
+    if (!user) return notFound(userId);
+    return ok(publicUser(user));
+  }
+
+  @Tool({
+    name: 'create_user',
+    topic: ToolTopics.UsersKeys,
+    title: 'Create a user',
+    template: 'Create a user «name» with email «email» and password «password»',
+    description:
+      'Create a user account with the password the person chose, as the ' +
+      'console does (there is no invitation email). Role defaults to User; ' +
+      'Admin is the other option — Owner exists once and cannot be created. ' +
+      'The result is the new account without the password; the person must ' +
+      'pass it on themselves, it is never shown again.',
+    parameters: z.object({
+      name: nameSchema,
+      email: emailSchema,
+      password: passwordSchema,
+      role: roleSchema.optional(),
+    }),
+  })
+  async createUser(
+    {
+      name,
+      email,
+      password,
+      role,
+    }: { name: string; email: string; password: string; role?: UserRoleTypes },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const user = await this.users.create({ name, email, password, role });
+    // Log who was created, never with what — the API log is not a vault.
+    this.logger.log(`User created through MCP: id=${user.id} email=${email}`);
+    return ok({
+      ok: true,
+      user: publicUser(user),
+      note: 'The password is not repeated here; the person hands it over.',
+    });
+  }
+
+  @Tool({
+    name: 'update_user',
+    topic: ToolTopics.UsersKeys,
+    title: 'Update a user',
+    template: 'Change the user «email»: «what to change»',
+    description:
+      "Change a user's name, email, password or status (active, invited, " +
+      'disabled). Pass only the fields to change. The role is not changed ' +
+      'here — use set_user_role. The Owner account cannot be disabled or ' +
+      'otherwise re-statused. Returns the updated account, never a password.',
+    parameters: z.object({
+      userId: z.string().describe('User id (list_users has them)'),
+      name: nameSchema.optional(),
+      email: emailSchema.optional(),
+      password: passwordSchema.optional().describe('New password, 8+ chars'),
+      status: statusSchema.optional(),
+    }),
+  })
+  async updateUser(
+    {
+      userId,
+      name,
+      email,
+      password,
+      status,
+    }: {
+      userId: string;
+      name?: string;
+      email?: string;
+      password?: string;
+      status?: UserStatusTypes;
+    },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const target = await this.users.findById(userId);
+    if (!target) return notFound(userId);
+    // Same rule as UserController.update: the Owner's status is not for
+    // changing, since a disabled Owner locks the Ranch.
+    if (status !== undefined && target.role === UserRoleTypes.Owner) {
+      return err(
+        'The Owner account status cannot be changed. Its name, email or ' +
+          'password can — call again without status.',
+      );
+    }
+    const patch: IUpdateUserData = {
+      ...(name !== undefined && { name }),
+      ...(email !== undefined && { email }),
+      ...(password !== undefined && { password }),
+      ...(status !== undefined && { status }),
+    };
+    if (Object.keys(patch).length === 0) {
+      return err(
+        'Nothing to change — pass at least one of name, email, password, status.',
+      );
+    }
+    const user = await this.users.update(userId, patch);
+    this.logger.log(
+      `User updated through MCP: id=${userId} fields=${Object.keys(patch).join(',')}`,
+    );
+    return ok({ ok: true, user: publicUser(user) });
+  }
+
+  @Tool({
+    name: 'set_user_role',
+    topic: ToolTopics.UsersKeys,
+    title: "Set a user's role",
+    template: 'Make «email» an «admin|user»',
+    destructive: true,
+    description:
+      "Change a user's role to Admin or User. Owner is not assignable: it " +
+      'exists once and the Owner account itself cannot be re-roled. Demoting ' +
+      'an Admin to User takes away their console access to agents and ' +
+      'users, so it counts as destructive. Takes the user id (list_users). ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      userId: z.string().describe('User id (list_users has them)'),
+      role: roleSchema,
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async setUserRole(
+    args: { userId: string; role: UserRoleTypes; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { userId, role } = args;
+    const target = await this.users.findById(userId);
+    if (!target) return notFound(userId);
+    // Same rule as UserController.updateRole (Owner-only there; the operator
+    // gate above is the same lock).
+    if (target.role === UserRoleTypes.Owner) {
+      return err(
+        `The Owner role cannot be changed — «${target.email}» stays Owner.`,
+      );
+    }
+    if (!(ASSIGNABLE_USER_ROLES as readonly string[]).includes(role)) {
+      return err(
+        `Role must be one of ${ASSIGNABLE_USER_ROLES.join(', ')}; Owner is not assignable.`,
+      );
+    }
+    if (target.role === role) {
+      return ok({
+        ok: true,
+        user: publicUser(target),
+        note: `«${target.email}» already has the role ${role}; nothing changed.`,
+      });
+    }
+    const refusal = confirmed(
+      args,
+      `make «${target.email}» a ${role} (currently ${target.role})`,
+    );
+    if (refusal) return refusal;
+    const user = await this.users.update(userId, { role });
+    this.logger.log(
+      `User role set through MCP: id=${userId} ${target.role}->${role}`,
+    );
+    return ok({ ok: true, user: publicUser(user) });
+  }
+
+  @Tool({
+    name: 'delete_user',
+    topic: ToolTopics.UsersKeys,
+    title: 'Remove a user',
+    template: 'Remove the user «email»',
+    destructive: true,
+    description:
+      'Remove a user account for good: their sessions stop working and the ' +
+      'row is gone — there is no undo, only creating them again. The Owner ' +
+      'account cannot be removed. Takes the user id (list_users). ' +
+      CONFIRM_SENTENCE,
+    parameters: z.object({
+      userId: z.string().describe('User id (list_users has them)'),
+      confirm: z
+        .boolean()
+        .describe('Set true only after the person confirmed in the chat.'),
+    }),
+  })
+  async deleteUser(
+    args: { userId: string; confirm?: boolean },
+    _context: unknown,
+    httpRequest: AuthedRequest,
+  ): Promise<ToolResult> {
+    requireOperator(httpRequest);
+    const { userId } = args;
+    const target = await this.users.findById(userId);
+    if (!target) return notFound(userId);
+    // Same rule as UserController.remove: the Owner is the one account a
+    // Ranch cannot be without.
+    if (target.role === UserRoleTypes.Owner) {
+      return err(
+        `The Owner account cannot be removed — «${target.email}» stays.`,
+      );
+    }
+    const refusal = confirmed(
+      args,
+      `remove the user «${target.email}» (${target.name}, ${target.role}) — this cannot be undone`,
+    );
+    if (refusal) return refusal;
+    await this.users.delete(userId);
+    this.logger.log(`User removed through MCP: id=${userId}`);
+    return ok({
+      ok: true,
+      removed: { id: target.id, email: target.email, name: target.name },
+    });
+  }
+}
+
+/**
+ * The row as the console shows it. `IUserData` carries no password today;
+ * the strip is there so a mapper change can never turn a listing into a
+ * hash dump (FR-004).
+ */
+function publicUser(user: IUserData) {
+  return stripSecrets(user, USER_SECRET_KEYS);
+}
+
+function notFound(userId: string): ToolResult {
+  return ok({
+    error: `User ${userId} not found — call list_users to find the id`,
+  });
+}
diff --git a/docs/agent-tools.md b/docs/agent-tools.md
new file mode 100644
index 00000000..1683e8a6
--- /dev/null
+++ b/docs/agent-tools.md
@@ -0,0 +1,158 @@
+# Agent tools: a module is not done until the agent can do it
+
+Applies to `api/` (where tools live) and to anyone adding a capability to the
+admin console.
+
+## The one rule that explains the rest
+
+**The console is a window; the chat is the hands.** Ranch was designed so an
+operator can say "create a researcher agent on the Claude credential with the
+docs knowledge base, connect it to «billing» and restart it" and have it
+happen. Every screen in the admin console is a convenience over something the
+agent can also do through a tool.
+
+The defect this rule exists for (CLEAN-109): feature by feature, the console
+gained screens whose actions had no tool. "Register the GitHub MCP server" got
+"I can't do that from here" — not because the platform couldn't, but because
+nobody handed the agent the tool. So, alongside tests:
+
+> **A module that adds or changes a console capability ships the matching
+> agent tool, with a topic, a title, a starter template, the right audience
+> gating, and a spec — in the same PR.**
+
+The API enforces the shape: it refuses to boot a tool without `topic`,
+`title` and `template`, or a destructive tool without a `confirm` parameter.
+The reviewer enforces the rest: the checklist at the end of this document.
+
+## Definition of done for a capability
+
+| The console can… | …so the API must have |
+|---|---|
+| list / show | a read tool (`list_x`, `get_x`) returning what the screen shows, minus secrets |
+| create / edit | a write tool taking the same fields as the DTO, calling the same service |
+| delete / revoke / replace all / change a role / restart everything | a **destructive** tool with `confirm: true` that names what it is about to do |
+| upload a file from the person's machine | nothing — say in a nearby tool's description that this stays in the console |
+| show something only after a restart | the tool's result says so ("restart required") |
+
+Plus: a spec beside the tool, and the tool visible in the chat's Tools panel
+(open the Rancher chat, press the wrench; if your topic is not there, the API
+did not boot your tool).
+
+## Where a tool lives
+
+```
+api/src/slices/<slice>/<name>.tool.ts        # the provider class with @Tool methods
+api/src/slices/<slice>/<name>.tool.spec.ts   # its spec
+api/src/slices/<slice>/<slice>.module.ts     # providers: [..., <Name>Tool]
+```
+
+The tool class injects the **same** gateways/services the slice's controller
+injects and calls them the way the controller does. A tool never re-implements
+a rule the controller has; if the controller validates, the tool validates
+through the same service. Reference module: `api/src/slices/agent/peer/`
+(`peerAdmin.tool.ts` for operator tools, `peerSelf.tool.ts` for agent
+self-service, `askAgent.tool.ts` for a tool that describes itself per caller).
+
+Shared helpers: `api/src/slices/mcp/tooling.ts` — `ok`, `err`,
+`requireOperator`, `requireAgent`, `callerIsOperator`, `callerAgentId`,
+`confirmed`, `stripSecrets`, `CONFIRM_SENTENCE`.
+
+## The `@Tool` metadata
+
+```ts
+@Tool({
+  name: 'register_mcp_server',          // snake_case verb_noun; never renamed once shipped
+  topic: ToolTopics.McpServers,         // an accordion of the Tools panel
+  title: 'Register an MCP server',      // ≤ 60 chars, sentence case, no period
+  template: 'Register the MCP server at «url» named «name»',  // ≤ 200 chars, «…» placeholders
+  destructive: false,                   // true ⇒ confirm parameter required
+  description: '…what it does, what it returns, what to do next…',
+  parameters: z.object({ … }),
+})
+```
+
+- **Topics** are in `api/src/slices/mcp/decorators/topics.ts`. Add one there
+  before using it; keep them mirroring console sections.
+- **Templates are starters, not forms.** They exist so a newcomer can come up
+  with an example message for that tool; the person edits freely. Write them
+  as one imperative English sentence; placeholders are `«noun»`, never an id
+  the person would not know (say `«agent name»`; the model resolves names via
+  `list_*`).
+- **Descriptions** are read by the model. Say what the tool returns and what
+  to call next on the usual failure ("call list_agents to find the id").
+
+## Audiences
+
+| audience | listing | inside every method |
+|---|---|---|
+| Operator (the Ranch admin agent; token carries Owner) | class `implements IConditionallyListedTool`, `isListedForRequest → callerIsOperator(req)` | `requireOperator(httpRequest)` |
+| Agent self-service (any runtime) | `callerAgentId(req) !== null` (+ a feature flag where one exists) | `requireAgent(httpRequest)` |
+| Everyone | always | — |
+
+One class, one audience. Split classes when a slice needs two (as `peer/` does).
+
+## Destructive tools
+
+```ts
+parameters: z.object({
+  id: z.string(),
+  confirm: z.boolean().describe('Set true only after the person confirmed in the chat.'),
+}),
+…
+const agent = await this.agents.findById(id);
+if (!agent) return ok({ error: `Agent ${id} not found — call list_agents` });
+const refusal = confirmed(args, `delete agent «${agent.name}» and its workspace`);
+if (refusal) return refusal;
+```
+
+The API cannot see the chat; the argument is the only server-side proof that
+the model went through a confirmation step. The description ends with
+`CONFIRM_SENTENCE`. Mark `destructive: true` on anything that deletes,
+revokes, replaces wholesale, changes a role, restarts a fleet or interrupts
+work.
+
+## Secrets
+
+Parameters may carry secrets. Results never do. Strip `apiKey`, `authValue`,
+`password`, `secret`, `token` before `ok(...)` (`stripSecrets` does the
+common cases) and acknowledge "set" operations without echoing the value. The
+one exception is `create_api_key`, which returns the key once, exactly as the
+console does. `api/src/slices/mcp/tool-secrets.spec.ts` feeds every
+secret-taking tool a sentinel and asserts it never comes back — add your tool
+there when it takes a secret.
+
+## Tests
+
+`<name>.tool.spec.ts`, jest, in the style of `peerAdmin.tool.spec.ts`:
+listed / not listed per audience; one happy path per tool asserting the
+gateway call and the result; not-found with the next move; every destructive
+tool refuses without `confirm` and touches nothing; no secret in any result.
+
+Run jest directly — `cd api && NODE_OPTIONS=--experimental-vm-modules npx jest <path>`.
+Never `bun run test` while a dev API is running.
+
+## Why "after restart" appears in the panel
+
+A pod reads its tool list once at boot. When the API ships a new tool, the
+running pod does not have it until a restart; the API records what each pod
+was last told (`AgentToolListing`) and the panel marks the difference. That is
+expected after every deploy that adds tools — the Restart button in the panel
+clears it.
+
+## Keeping this rule where coding agents look
+
+`CLAUDE.md` states the rule and links here. The graft skill
+(`.claude/skills/graft/SKILL.md`) and the Cursor graft rule
+(`.cursor/rules/graft.mdc`) carry a short pointer block between
+`<!-- ranch:agent-tools:start -->` and `<!-- ranch:agent-tools:end -->`.
+`graft init` rewrites those files; `node scripts/ensure-agent-tools-rule.mjs`
+puts the block back (it is idempotent and `make init` runs it).
+
+## Review checklist
+
+- Does the PR add or change a console capability? Then: is there a tool, in
+  the slice, with topic/title/template, gated to the right audience, with a
+  spec?
+- Does anything destructive lack `confirm`?
+- Does any result echo a secret?
+- Does the tool call the controller's service, or its own copy of the logic?
diff --git a/package.json b/package.json
index 08affae0..d666bcfb 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ranch",
-  "version": "0.3.60",
+  "version": "0.3.61",
   "private": true,
   "packageManager": "bun@1.2.12",
   "workspaces": [
diff --git a/scripts/ensure-agent-tools-rule.mjs b/scripts/ensure-agent-tools-rule.mjs
new file mode 100644
index 00000000..f8462e6b
--- /dev/null
+++ b/scripts/ensure-agent-tools-rule.mjs
@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Puts the agent-tools rule pointer back into the graft-owned guidance files
+ * (CLEAN-109). `graft init` rewrites `.claude/skills/graft/SKILL.md` and
+ * `.cursor/rules/graft.mdc` wholesale, so a rule written into them by hand is
+ * lost on the next init; this script re-inserts a short fenced block that
+ * points at the canonical doc. Idempotent: run it as often as you like.
+ *
+ *   node scripts/ensure-agent-tools-rule.mjs
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const START = '<!-- ranch:agent-tools:start -->';
+const END = '<!-- ranch:agent-tools:end -->';
+const BLOCK = [
+  START,
+  '## Project rule: agent tools',
+  '',
+  'A module is not done until the Ranch agent has tools for what the console',
+  'can do. Before adding or changing an admin-console capability, read',
+  '`docs/agent-tools.md`: tools live in the slice as `<name>.tool.ts` with',
+  '`topic` / `title` / `template`, audience gating, `confirm` on anything',
+  'destructive, no secrets in results, and a spec. The API refuses to boot a',
+  'tool without that metadata.',
+  END,
+  '',
+].join('\n');
+
+const targets = ['.claude/skills/graft/SKILL.md', '.cursor/rules/graft.mdc'];
+
+let changed = 0;
+for (const rel of targets) {
+  const path = join(root, rel);
+  if (!existsSync(path)) {
+    console.log(`skip  ${rel} (not present)`);
+    continue;
+  }
+  const current = readFileSync(path, 'utf8');
+  const eol = current.includes('\r\n') ? '\r\n' : '\n';
+  const block = BLOCK.replace(/\n/g, eol);
+  const start = current.indexOf(START);
+  const end = current.indexOf(END);
+  let next;
+  if (start !== -1 && end !== -1 && end > start) {
+    const existing = current.slice(start, end + END.length);
+    const fresh = block.trimEnd();
+    if (existing === fresh) {
+      console.log(`ok    ${rel}`);
+      continue;
+    }
+    next = current.slice(0, start) + fresh + current.slice(end + END.length);
+  } else {
+    const trimmed = current.replace(/\s+$/, '');
+    next = `${trimmed}${eol}${eol}${block}`;
+  }
+  writeFileSync(path, next);
+  changed += 1;
+  console.log(`wrote ${rel}`);
+}
+
+console.log(changed ? `${changed} file(s) updated` : 'nothing to do');
diff --git a/specs/016-agent-tool-parity/checklists/requirements.md b/specs/016-agent-tool-parity/checklists/requirements.md
new file mode 100644
index 00000000..6c0ad29a
--- /dev/null
+++ b/specs/016-agent-tool-parity/checklists/requirements.md
@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Agent tool parity
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-09-22
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs) — the audit names console sections and actions, not endpoints or classes
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain — 3 asked and settled 2026-09-22 (see Decisions in spec.md)
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded (in/out of scope in Overview; surfaces in Assumptions)
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- The audit table is derived from the console's actual sections and the agent's actual tool list as of 2026-09-22; it is the acceptance checklist for FR-001 and SC-001.
+- All items pass. Ready for `/speckit-plan`.
diff --git a/specs/016-agent-tool-parity/contracts/agent-tools.openapi.yaml b/specs/016-agent-tool-parity/contracts/agent-tools.openapi.yaml
new file mode 100644
index 00000000..3fb98cbd
--- /dev/null
+++ b/specs/016-agent-tool-parity/contracts/agent-tools.openapi.yaml
@@ -0,0 +1,83 @@
+openapi: 3.1.0
+info:
+  title: Ranch API — agent tool catalogue (CLEAN-109)
+  version: 1.0.0
+paths:
+  /agents/{id}/tools:
+    get:
+      operationId: getAgentTools
+      summary: >-
+        The tools this agent's runtime would receive from the built-in Ranch MCP
+        server, grouped by topic, with per-tool "present in the running pod"
+        flags, plus the agent's external MCP servers as opaque groups. Owner or
+        Admin only; agent tokens get their list from MCP tools/list instead.
+      tags: [Agents]
+      security: [{ bearer: [] }]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: The catalogue.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AgentToolCatalogDto' }
+        '403': { description: Caller is not Owner/Admin, or is an agent token. }
+        '404': { description: Agent not found. }
+components:
+  securitySchemes:
+    bearer: { type: http, scheme: bearer, bearerFormat: JWT }
+  schemas:
+    AgentToolCatalogDto:
+      type: object
+      required: [agentId, podStartedAt, listedAt, groups]
+      properties:
+        agentId: { type: string }
+        podStartedAt:
+          type: [string, 'null']
+          format: date-time
+          description: When the current pod started; null when no pod runs.
+        listedAt:
+          type: [string, 'null']
+          format: date-time
+          description: When the pod last called tools/list; null if it never did.
+        groups:
+          type: array
+          items: { $ref: '#/components/schemas/AgentToolGroupDto' }
+    AgentToolGroupDto:
+      type: object
+      required: [key, title, kind, afterRestart, tools]
+      properties:
+        key:
+          type: string
+          description: Topic key (e.g. mcp_servers) or mcp:<serverId> for an external server.
+        title: { type: string }
+        kind: { type: string, enum: [builtin, external] }
+        description:
+          type: string
+          description: External servers only — the server row's description. Never its url or auth value.
+        afterRestart:
+          type: boolean
+          description: >-
+            builtin — at least one tool has inPod=false; external — the server row changed
+            after the pod started (same rule as GET /agents/{id}/mcp-status).
+        tools:
+          type: array
+          items: { $ref: '#/components/schemas/AgentToolEntryDto' }
+          description: Empty for external groups; their tools are served by the server itself.
+    AgentToolEntryDto:
+      type: object
+      required: [name, title, description, template, destructive, inPod]
+      properties:
+        name: { type: string, description: Technical MCP tool name. }
+        title: { type: string }
+        description:
+          type: string
+          description: The per-caller description, exactly what the runtime would be given.
+        template: { type: string, description: Starter prompt with «…» placeholders. }
+        destructive: { type: boolean }
+        inPod:
+          type: [boolean, 'null']
+          description: null — no pod; false — the running pod did not list it; true — it did.
diff --git a/specs/016-agent-tool-parity/contracts/tool-metadata.md b/specs/016-agent-tool-parity/contracts/tool-metadata.md
new file mode 100644
index 00000000..03715f59
--- /dev/null
+++ b/specs/016-agent-tool-parity/contracts/tool-metadata.md
@@ -0,0 +1,83 @@
+# Contract: tool metadata, topics, gating, confirmation
+
+This is the contract every tool in `api/src/slices/**/*.tool.ts` follows from CLEAN-109 on. The registry enforces the shape at startup; the rule in `docs/agent-tools.md` explains it for people.
+
+## `@Tool` options
+
+```ts
+@Tool({
+  name: 'register_mcp_server',                       // snake_case verb_noun; never renamed once shipped
+  topic: ToolTopics.McpServers,                      // required
+  title: 'Register an MCP server',                   // required, ≤ 60 chars, sentence case, no trailing period
+  description: 'Register an external MCP server …',  // what the model reads; ends with the confirm sentence when destructive
+  template: 'Register the MCP server at «url» named «name» with «bearer|none» auth',  // required, ≤ 200 chars
+  destructive: false,                                // optional; true ⇒ confirm param required
+  parameters: z.object({ … }),
+})
+```
+
+Template conventions: imperative English sentence, placeholders as `«…»` with a short noun inside (`«agent name»`, `«url»`), never an id the person would not know (say `«agent name»`, the tool resolves names to ids or the model calls `list_*` first). One template per tool. A template is a starter, not a form (spec Decision 4).
+
+## Topics (`api/src/slices/mcp/decorators/topics.ts`)
+
+| key | title | order | what belongs |
+|---|---|---|---|
+| `agents` | Agents | 10 | lifecycle, config, admin flag, status/metrics/env/logs, MCP list, capacity |
+| `agent_workspace` | Agent workspace | 20 | files, secrets, channels, share link |
+| `templates` | Templates | 30 | templates, their files, skills/MCP bindings, install/export |
+| `skills` | Skills | 40 | skills, import, search, redeploy |
+| `llm` | LLM credentials | 50 | credentials, health, models, usage per credential |
+| `mcp_servers` | MCP servers | 60 | registry of servers, enable/disable, OAuth |
+| `knowledge` | Knowledge | 70 | bases, indexing, graph, sources, imports, `query_knowledge` |
+| `settings` | Settings | 80 | platform settings |
+| `peers` | Peers (A2A) | 90 | operator peer set, self-service set, `ask_agent` |
+| `paddock` | Paddock | 100 | scenarios, evaluations |
+| `users_keys` | Users & API keys | 110 | users, roles, API keys |
+| `chats_usage` | Chats & usage | 120 | chats, transcripts, summaries, usage overview, `agent_usage` |
+| `browser` | Browser & integrations | 130 | browser sessions, integration accounts |
+| `attachments` | Attachments | 140 | `query_attachment` |
+| `platform` | Platform | 150 | upgrade, rancher setup status |
+
+Empty topics are not returned by the catalogue endpoint.
+
+## Gating (who sees and may call)
+
+Three audiences, expressed with the shared helpers in `api/src/slices/mcp/tooling.ts` (moved from `agent/peer/toolSupport.ts`, which re-exports them):
+
+| audience | listing | call guard | helper |
+|---|---|---|---|
+| Operator (admin agent; token carries `Owner`) | `isListedForRequest → callerIsOperator(req)` | `requireOperator(req)` throws `ForbiddenException('… requires the Ranch operator role. Ask the operator to do it in the console.')` | `requireOperator` |
+| Agent self-service (any runtime; `sub = agent:<id>`) | `callerAgentId(req) !== null` (+ feature flag where one exists, e.g. peers self-service setting) | `requireAgent(req)` returns the agent id or throws | `requireAgent` |
+| Everyone (any authenticated caller) | always | none | — |
+
+A tool class declares one audience for all its methods (split classes when a slice needs two, as `peerAdmin.tool.ts` / `peerSelf.tool.ts` do). `RancherTool.requireOwner` is replaced by `requireOperator` so refusals read the same everywhere.
+
+## Confirmation (destructive tools)
+
+```ts
+parameters: z.object({
+  id: z.string(),
+  confirm: z.boolean().describe('Set true only after the person confirmed in the chat.'),
+})
+…
+const refusal = confirmed(args, `delete agent «${agent.name}» and its workspace`);
+if (refusal) return refusal; // err('This will delete agent «x» and its workspace. Ask the person to confirm, then call again with confirm: true.')
+```
+
+`destructive: true` on: delete/remove/revoke anything, replace-all secrets, set user role, run upgrade, stop agent (it interrupts work), regenerate share link (invalidates the old one).
+
+## Secrets
+
+Parameters may carry secrets. Results never do: strip `apiKey`, `authValue`, `password`, `secret`, `token` fields in the tool before `ok(...)`. Exception: `create_api_key` returns the key once (research R6). The cross-cutting spec `api/src/slices/mcp/tool-secrets.spec.ts` enforces this by sentinel.
+
+## Results
+
+Every tool returns `ToolResult` via `ok(value)` / `err(text)`. Errors name the next move ("Nothing was saved. …", "Call list_agents to find the id."). `HttpException`s thrown by domain services are turned into `isError` text by the MCP handler; tools that can hit coded refusals wrap with `withRefusalAdvice`.
+
+## Registration
+
+The tool class is a provider of its slice's module (`providers: [XService, XTool]`); the module imports whatever modules export the gateways the tool needs. Nothing else: `McpRegistryService` discovers every `@Tool` across all modules.
+
+## Tests
+
+`*.tool.spec.ts` beside the tool file. Minimum per tool: listed/not listed by audience; happy path maps arguments and returns `ok`; not-found returns advice; destructive without `confirm` refuses without calling the gateway.
diff --git a/specs/016-agent-tool-parity/contracts/tools.md b/specs/016-agent-tool-parity/contracts/tools.md
new file mode 100644
index 00000000..b00814ca
--- /dev/null
+++ b/specs/016-agent-tool-parity/contracts/tools.md
@@ -0,0 +1,208 @@
+# Contract: the tool inventory
+
+The complete list of tools after CLEAN-109. **Existing** tools keep their name and behaviour and only gain metadata. **New** tools are the audit's Gap column made concrete. "Backing" names the domain service/gateway the tool calls — the same one the console's controller uses (spec FR-008). Audience: **O** operator only, **A** agent self-service (any runtime), **E** everyone. ⚠ = destructive (requires `confirm`).
+
+Templates are indicative; the implementer may improve wording but keeps the placeholder convention.
+
+## agents — Agents
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| list_agents | existing | O | List agents | List all agents and their status | IAgentGateway |
+| get_agent | existing | O | Show an agent | Show the agent «name» | IAgentGateway |
+| create_agent | existing | O | Create an agent | Create an agent «name» from template «template» using the LLM credential «credential» | AgentDeployService |
+| update_agent | existing | O | Update an agent | Change the agent «name»: «what to change» | IAgentGateway + AgentDeployService |
+| set_agent_admin | existing | O | Make an agent the Ranch admin | Make «name» the Ranch admin agent | IAgentGateway/AgentDeployService |
+| restart_agent | existing | O | Restart an agent | Restart the agent «name» | AgentDeployService |
+| stop_agent | new | O ⚠ | Stop an agent | Stop the agent «name» | AgentDeployService (as `POST :id/stop`) |
+| start_agent | new | O | Start an agent | Start the agent «name» | AgentDeployService (as `POST :id/start`) |
+| delete_agent | new | O ⚠ | Delete an agent | Delete the agent «name» and its workspace | AgentDeployService + IAgentGateway (`DELETE :id`, `wipeS3` option) |
+| get_agent_status | new | O | Show live status and metrics | How is the agent «name» doing right now? | AgentStatusService + IPodGateway (`:id/metrics`, `status`) |
+| get_agent_env | new | O | Show the pod environment preview | Show the environment the agent «name» runs with | as `GET :id/env` (values of secrets masked as the console masks them) |
+| get_agent_logs | new | O | Read pod logs | Show the last «100» log lines of the agent «name» | LogController's gateway (`GET agents/:id/logs`, tail param) |
+| list_agent_mcps | new | O | Show the agent's MCP servers | Which MCP servers does the agent «name» have, and does it need a restart? | AgentMcpResolver + detectMcpConfigDrift (no authValue in result) |
+| get_cluster_capacity | new | O | Show cluster capacity | How much capacity is left for new agents? | as `GET agents/capacity` |
+
+## agent_workspace — Agent workspace
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| list_agent_files | existing | O | List workspace files | List the files of the agent «name» | IFileGateway |
+| read_agent_file | existing | O | Read a workspace file | Show «path» from the agent «name» | IFileGateway |
+| write_agent_file | existing | O | Write a workspace file | Write «path» in the agent «name» with: «content» | IFileGateway |
+| delete_agent_file | new | O ⚠ | Delete a workspace file | Delete «path» from the agent «name» | IFileGateway (`DELETE files/content`) |
+| sync_agent_files | new | O | Sync files from the pod | Sync the workspace files of the agent «name» from its pod | SyncGuardService + IFileGateway (`POST files/sync`) |
+| export_agent_files | new | O | Export the workspace | Export the workspace of the agent «name» | returns the console download path (`GET files/export`) |
+| list_agent_secrets | new | O | List secret names | Which secrets does the agent «name» have? | ISecretGateway (names only) |
+| set_agent_secret | new | O | Set a secret | Set the secret «KEY» of the agent «name» to «value» | ISecretGateway (`PUT`) |
+| delete_agent_secret | new | O ⚠ | Delete a secret | Delete the secret «KEY» of the agent «name» | ISecretGateway (`DELETE`) |
+| replace_agent_secrets | new | O ⚠ | Replace all secrets | Replace all secrets of the agent «name» with: «KEY=value, …» | ISecretGateway (`POST replace`) |
+| get_agent_channels | new | O | Show delivery channels | Which channels is the agent «name» connected to? | IAgentChannelGateway |
+| set_agent_channels | new | O | Set delivery channels | Connect the agent «name» to «channel list» | IAgentChannelGateway (`PUT :id/channels`) |
+| get_share_link | new | O | Show the share link | Does the agent «name» have a public share link? | ShareLinkService |
+| create_share_link | new | O | Create a share link | Create a public share link for the agent «name» | ShareLinkService |
+| regenerate_share_link | new | O ⚠ | Regenerate the share link | Regenerate the share link of the agent «name» | ShareLinkService |
+| revoke_share_link | new | O ⚠ | Revoke the share link | Revoke the share link of the agent «name» | ShareLinkService |
+
+## templates — Templates
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| list_templates | existing | O | List templates | List all agent templates | ITemplateGateway |
+| get_template | existing | O | Show a template | Show the template «name» | ITemplateGateway |
+| update_template | existing | O | Update a template | Change the template «name»: «what to change» | ITemplateGateway |
+| set_template_skills | existing | O | Set template skills | Give the template «name» the skills «skill list» | ITemplateGateway |
+| list_template_files | existing | O | List template files | List the files of the template «name» | ITemplateFileGateway |
+| read_template_file | existing | O | Read a template file | Show «path» of the template «name» | ITemplateFileGateway |
+| write_template_file | existing | O | Write a template file | Write «path» in the template «name» with: «content» | ITemplateFileGateway |
+| create_template | new | O | Create a template | Create a template «name» with image «image» described as «description» | ITemplateGateway |
+| delete_template | new | O ⚠ | Delete a template | Delete the template «name» | ITemplateGateway |
+| set_template_mcps | new | O | Attach MCP servers to a template | Attach the MCP servers «server list» to the template «name» | ITemplateGateway (`PUT :id/mcps`) |
+| restart_template_agents | new | O ⚠ | Restart every agent of a template | Restart all agents of the template «name» | AgentDeployService (`POST restart-by-template/:templateId`) |
+| preview_template_install_from_git | new | O | Preview a git template | What would installing the template from «git url» at «ref» bring? | TemplateInstallService |
+| install_template_from_git | new | O | Install a template from git | Install the template from «git url» at «ref» | TemplateInstallService |
+| export_template | new | O | Export a template | Export the template «name» | TemplateExportService → download path |
+
+Zip install and binary file upload stay console-only (spec Assumptions); `install_template_from_git` covers the same source without a browser.
+
+## skills — Skills
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| list_skills | existing | O | List skills | List all skills | ISkillGateway |
+| update_skill | existing | O | Update a skill | Change the skill «name»: «what to change» | ISkillGateway |
+| list_skill_agents | existing | O | Which agents use a skill | Which agents use the skill «name»? | ISkillGateway |
+| redeploy_skill_agents | existing | O ⚠ | Redeploy agents of a skill | Redeploy every agent that uses the skill «name» | AgentDeployService |
+| get_skill | new | O | Show a skill | Show the skill «name» | ISkillGateway |
+| create_skill | new | O | Create a skill | Create a skill «title» that «what it does» | ISkillGateway |
+| delete_skill | new | O ⚠ | Delete a skill | Delete the skill «name» | ISkillGateway |
+| import_skill_from_url | new | O | Import a skill from GitHub | Import the skill at «github url» | SkillController import-url path (GithubSearch + gateway) |
+| search_skills | new | O | Search public skills | Find public skills about «topic» | GithubSearch |
+| import_skill | new | O | Import a found skill | Import the skill «name» from «repo» | as `POST skills/import` |
+
+## llm — LLM credentials
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| list_llms | existing | O | List LLM credentials | List the LLM credentials | ILlmGateway (keys stripped) |
+| get_llm | new | O | Show a credential | Show the LLM credential «name» | ILlmGateway (key stripped) |
+| create_llm | new | O | Create a credential | Create an LLM credential «name» for «provider» with key «key» | ILlmGateway |
+| update_llm | new | O | Update a credential | Change the LLM credential «name»: «what to change» | ILlmGateway |
+| delete_llm | new | O ⚠ | Delete a credential | Delete the LLM credential «name» | ILlmGateway |
+| health_check_llm | new | O | Health-check a credential | Check that the LLM credential «name» works | ILlmHealthGateway |
+| list_llm_models | new | O | List known models | Which models can I use with «provider»? | as `GET llms/models` (llm slice providers catalogue) |
+| llm_usage | new | O | Usage of a credential | How much did the credential «name» cost in the last 30 days? | UsageController path (`GET llms/:id/usage`) |
+
+## mcp_servers — MCP servers
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| list_mcp_servers | new | O | List MCP servers | List the MCP servers registered in this Ranch | IMcpServerGateway (authValue stripped) |
+| get_mcp_server | new | O | Show an MCP server | Show the MCP server «name» | IMcpServerGateway |
+| register_mcp_server | new | O | Register an MCP server | Register the MCP server at «url» named «name» with «bearer|none» auth | IMcpServerGateway |
+| update_mcp_server | new | O | Update or enable/disable a server | Disable the MCP server «name» | IMcpServerGateway (built-in rows: enabled/description only, as the controller enforces) |
+| delete_mcp_server | new | O ⚠ | Delete an MCP server | Delete the MCP server «name» | IMcpServerGateway (built-ins refused with the controller's message) |
+| start_mcp_oauth | new | O | Start OAuth for a server | Connect the MCP server «name» with OAuth | McpOauthService → returns the URL the person must open |
+
+## knowledge — Knowledge
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| query_knowledge | existing | A/E | Ask the knowledge bases | What does our knowledge say about «question»? | KnowledgeService |
+| list_knowledges | new | O | List knowledge bases | List the knowledge bases | KnowledgeService |
+| get_knowledge | new | O | Show a knowledge base | Show the knowledge base «name» | KnowledgeService |
+| create_knowledge | new | O | Create a knowledge base | Create a knowledge base «name» described as «description» | KnowledgeService |
+| update_knowledge | new | O | Update a knowledge base | Change the knowledge base «name»: «what to change» | KnowledgeService |
+| delete_knowledge | new | O ⚠ | Delete a knowledge base | Delete the knowledge base «name» | KnowledgeService |
+| index_knowledge | new | O | Start indexing | Index the knowledge base «name» | KnowledgeService |
+| get_knowledge_overview | new | O | Source counts and size | How big is the knowledge base «name» and what is in it? | KnowledgeService (`:id/overview`) |
+| list_knowledge_graph_labels | new | O | Entity labels | Which entity labels does the knowledge base «name» have? | ILightragClient (`:id/graph/labels`) |
+| get_knowledge_status | new | O | Knowledge service status | Is the knowledge service ready? | IKnowledgeConfigGateway + ILightragClient (`status`) |
+| list_knowledge_sources | new | O | List sources | List the sources of the knowledge base «name» | SourceService |
+| add_knowledge_source | new | O | Add a URL or text source | Add «url or text» to the knowledge base «name» | SourceService (`POST`, kind url/text) |
+| add_knowledge_sources_from_sitemap | new | O | Add URLs from a sitemap | Add every page of «sitemap url» to the knowledge base «name» | SourceService (`from-sitemap`) |
+| reindex_knowledge_source | new | O | Retry one source | Reindex the source «name» in the knowledge base «base» | SourceService |
+| extract_knowledge_source | new | O | Re-extract a scanned PDF | Re-run text extraction for «source» in «base» | SourceService |
+| delete_knowledge_source | new | O ⚠ | Delete a source | Delete the source «name» from the knowledge base «base» | SourceService |
+| list_knowledge_imports | new | O | Imports in progress | Are any imports running for the knowledge base «name»? | SourceService (`imports`) |
+
+File and archive uploads from a person's machine stay console-only; `add_knowledge_source` covers text the agent can produce and URLs.
+
+## settings — Settings
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| list_settings | existing (+dynamic description) | O | List settings | Show the settings in «group» | ISettingGateway + SETTING_CATALOG |
+| upsert_setting | existing (+dynamic description) | O | Set a setting | Set «group».«name» to «value» | ISettingGateway |
+| get_setting | new | O | Show one setting | What is «group».«name» set to? | ISettingGateway |
+| delete_setting | new | O ⚠ | Delete a setting | Reset «group».«name» to its default | ISettingGateway |
+
+## peers — Peers (A2A)
+
+All 15 existing tools (`list_agent_peers`, `list_peer_candidates`, `preview_agent_card`, `list_agent_delegations`, `connect_agent_peer`, `import_external_agent`, `refresh_agent_peer`, `remove_agent_peer` — O; `list_my_peers`, `list_ranch_agents`, `preview_agent_card_by_address`, `connect_my_peer`, `import_my_peer_by_address`, `remove_my_peer` — A; `ask_agent` — A) gain metadata only. `remove_agent_peer` and `remove_my_peer` become ⚠.
+
+## paddock — Paddock
+
+Existing 12 (`list_paddock_scenarios`, `get_paddock_scenario`, `list_agent_paddock_scenarios`, `create_paddock_scenario`, `update_paddock_scenario`, `delete_paddock_scenario` ⚠, `run_paddock_evaluation`, `list_paddock_evaluations`, `get_paddock_evaluation`, `get_paddock_evaluation_report`, `abort_paddock_evaluation` ⚠, `rerun_paddock_evaluation`) gain metadata. New:
+
+| name | aud | title | template | backing |
+|---|---|---|---|---|
+| generate_paddock_scenarios | O | Generate scenarios from a description | Generate «3» paddock scenarios for the agent «name» about «topic» | IPaddockScenarioGeneratorGateway |
+| get_paddock_evaluation_logs | O | Evaluation logs | Show the logs of evaluation «id» | PaddockEvaluationService |
+| get_paddock_evaluation_scenario_result | O | One scenario's result | How did scenario «scenario» go in evaluation «id»? | PaddockEvaluationService |
+| get_paddock_evaluation_trace | O | Evaluation trace | Show the trace of evaluation «id» | PaddockEvaluationService |
+
+## users_keys — Users & API keys
+
+| name | aud | title | template | backing |
+|---|---|---|---|---|
+| list_users | O | List users | List the users of this Ranch | IUserGateway (no password hashes) |
+| get_user | O | Show a user | Show the user «email» | IUserGateway |
+| create_user | O | Create a user | Create a user «name» with email «email» and password «password» | IUserGateway |
+| update_user | O | Update a user | Change the user «email»: «what to change» | IUserGateway |
+| set_user_role | O ⚠ | Set a user's role | Make «email» an «admin|owner|user» | IUserGateway (`PUT :id/role`, Owner only as the controller) |
+| delete_user | O ⚠ | Remove a user | Remove the user «email» | IUserGateway |
+| list_api_keys | O | List API keys | List the API keys | IApiKeyGateway (prefix/metadata only) |
+| create_api_key | O | Create an API key | Create an API key named «name» | ApiKeyService (returns the key once — research R6) |
+| revoke_api_key | O ⚠ | Revoke an API key | Revoke the API key «name» | IApiKeyGateway |
+
+## chats_usage — Chats & usage
+
+| name | status | aud | title | template | backing |
+|---|---|---|---|---|---|
+| agent_usage | existing | O | Usage of an agent | How much did the agent «name» cost in the last «30» days? | IUsageGateway |
+| list_chats | new | O | List chats | List the recent chats «of agent name» | IChatGateway |
+| get_chat | new | O | Show a chat | Show the chat «id» | IChatGateway |
+| get_chat_messages | new | O | Read chat messages | Show the last «20» messages of chat «id» | TranscriptReaderService |
+| sync_chats | new | O | Sync chats from runtimes | Sync chats «of agent name» from their runtimes | ChatSyncService |
+| summarize_chat | new | O | Summarize a chat | Summarize the chat «id» | ChatInsightService |
+| export_chat | new | O | Export a chat | Export the chat «id» | download path (`GET chats/:id/export`) |
+| get_usage_overview | new | O | Usage across all agents | How much did all agents cost in the last 30 days? | IUsageGateway (`usage/overview`) |
+
+## browser — Browser & integrations
+
+Existing 6 `browser_session_*` (A, userId must match caller) gain metadata; `browser_session_close` and `browser_session_reset` become ⚠. New (same userId convention as the browser tools):
+
+| name | aud | title | template | backing |
+|---|---|---|---|---|
+| list_integration_catalogue | A | Available integrations | Which integrations can I connect? | IntegrationService |
+| list_integration_accounts | A | My integration accounts | Which integration accounts do I have? | IntegrationService (secrets stripped) |
+| create_integration_account | A | Connect an integration account | Connect my «service» account «label» | IntegrationService |
+| request_integration_login | A | Ask for a login | Ask me to log in to «service» | IntegrationService (`accounts/:id/login`) |
+| delete_integration_account | A ⚠ | Disconnect an account | Disconnect my «service» account | IntegrationService |
+
+## attachments — Attachments
+
+`query_attachment` (existing, E) gains metadata: title "Ask a question about an attached file", template "In the attached file, «question»".
+
+## platform — Platform
+
+| name | aud | title | template | backing |
+|---|---|---|---|---|
+| get_upgrade_status | O | Ranch upgrade status | Is a Ranch upgrade available? | UpgradeService |
+| run_upgrade | O ⚠ | Upgrade Ranch | Upgrade Ranch to the latest version | UpgradeService |
+| get_rancher_status | O | Rancher setup status | Is the Rancher setup complete? | RancherService |
+
+## Totals
+
+Existing tools annotated: 59. New tools: 93. Destructive (⚠): 30. Topics: 15 (attachments and platform included).
diff --git a/specs/016-agent-tool-parity/data-model.md b/specs/016-agent-tool-parity/data-model.md
new file mode 100644
index 00000000..b6e152fe
--- /dev/null
+++ b/specs/016-agent-tool-parity/data-model.md
@@ -0,0 +1,124 @@
+# Data model: Agent tool parity (CLEAN-109)
+
+## 1. ToolMetadata (in-process, from the `@Tool` decorator)
+
+```ts
+interface ToolMetadata {
+  name: string;          // technical name, snake_case, unchanged for existing tools
+  description: string;   // what the model reads; may be replaced per caller by describeForRequest
+  parameters: z.ZodTypeAny;
+  topic: ToolTopic;      // one of ToolTopics (see contracts/tool-metadata.md)
+  title: string;         // human title for the panel row, e.g. "Register an MCP server"
+  template: string;      // starter prompt with «…» placeholders, e.g. "Register the MCP server at «url» named «name»"
+  destructive?: boolean; // true ⇒ parameters must include confirm: z.boolean()
+}
+```
+
+Validation (at API bootstrap, `McpRegistryService`):
+- `topic` ∈ `ToolTopics`; `title` non-empty ≤ 60 chars; `template` non-empty ≤ 200 chars and contains at least one `«…»` unless the tool takes no parameters.
+- `destructive === true` ⇒ the JSON schema of `parameters` has a `confirm` property of type boolean.
+- `name` unique across the registry (already implied by `findTool`).
+
+## 2. AgentToolListing (PostgreSQL, new)
+
+```prisma
+// api/src/slices/agent/toolCatalog/toolCatalog.prisma
+import { Agent } from "../agent/agent"
+
+// The tool names the API last served to this agent's runtime on tools/list —
+// i.e. what the running pod believes it has. Written on every tools/list from
+// an agent token (once per pod boot in practice); read by GET /agents/:id/tools
+// to mark tools the pod does not yet know about (CLEAN-109).
+model AgentToolListing {
+  agentId   String   @id
+  agent     Agent    @relation(fields: [agentId], references: [id], onDelete: Cascade)
+  toolNames Json     // string[]
+  listedAt  DateTime @default(now())
+}
+```
+
+Migration: `api/prisma/migrations/20260922120000_agent_tool_listing/migration.sql` — additive `CREATE TABLE` + FK, safe on existing databases. `Agent` gets the back-relation `toolListing AgentToolListing?`.
+
+Lifecycle: upsert on each agent-token `tools/list`; deleted with the agent (cascade). Never read by the runtime.
+
+## 3. Agent tool catalogue (API response, `GET /agents/:id/tools`)
+
+```ts
+interface AgentToolCatalog {
+  agentId: string;
+  podStartedAt: string | null;   // ISO; null when no pod runs
+  listedAt: string | null;       // ISO of the snapshot; null when the pod never listed
+  groups: AgentToolGroup[];      // ordered by ToolTopics order, then external servers
+}
+
+interface AgentToolGroup {
+  key: string;                   // topic key, or `mcp:<serverId>` for an external server
+  title: string;                 // topic title or server name
+  kind: 'builtin' | 'external';
+  description?: string;          // external servers: the row's description; builtin: none
+  afterRestart: boolean;         // builtin: any tool with inPod === false; external: server drift from detectMcpConfigDrift
+  tools: AgentToolEntry[];       // external groups: [] (tools are provided by the server itself)
+}
+
+interface AgentToolEntry {
+  name: string;
+  title: string;
+  description: string;           // per-caller description (dynamic when the tool provides one)
+  template: string;
+  destructive: boolean;
+  inPod: boolean | null;         // null: no pod; false: pod lacks it; true: pod listed it
+}
+```
+
+Derivation:
+- `tools` = `ToolCatalogService.listFor(principal)` with `principal = { sub: 'agent:<id>', roles: agent.isAdmin ? [Owner] : [Agent] }`.
+- `inPod` = `podStartedAt === null ? null : (snapshot ? snapshot.toolNames.includes(name) : false)`.
+- External groups = `AgentMcpResolver.resolveForAgent(agent)` minus built-in ids (`mcp-ranch`, `mcp-knowledge`, `mcp-documents`, `mcp-cleanslice`); `authValue` and `url` are **not** returned.
+- Response is not cached; one DB read (snapshot) + resolver + pod list.
+
+Authorization: `@Roles(Owner, Admin)` — the same audience as `GET /agents/:id/mcp-status`. Agent tokens are refused (they get their list from `tools/list`).
+
+## 4. Admin store (`admin/slices/agent/toolCatalog/stores/toolCatalog.ts`)
+
+```ts
+interface IAgentToolCatalog { /* mirror of §3, mapped by ToolCatalogMapper */ }
+
+state: {
+  catalogs: Record<string, IAgentToolCatalog>;          // entity, keyed by agentId
+  ui: Record<string, { query: string; expanded: string[] }>; // per-agent sheet state, session only
+}
+getters: byAgent(agentId) → IAgentToolCatalog | undefined
+actions:
+  fetch(agentId): Promise<IAgentToolCatalog>   // gateway → upsert → return the stored record
+  upsert(catalog): IAgentToolCatalog
+  setQuery(agentId, q) / toggleGroup(agentId, key) / setExpanded(agentId, keys)
+```
+
+Rules: components render `computed(() => store.byAgent(agentId))`; `useAsyncData` supplies only `pending` / `error` / `refresh`. After a restart, the sheet calls `fetch(agentId)` again when the agent's status returns to running (watch on `agentStore.byId(agentId)?.status`).
+
+## 5. Composer insertion (pure util)
+
+```ts
+insertTemplate(draft: string, cursor: number, template: string):
+  { text: string; selectionStart: number; selectionEnd: number }
+```
+- Inserts `template` at `cursor`; prefixes a space when `draft.slice(0, cursor)` is non-empty and does not end with whitespace; suffixes a space when the remainder does not start with whitespace.
+- `selectionStart/End` bound the first `«…»` in the inserted text, or the end of the insertion when there is none.
+- `hasPlaceholder(text)`: `/«[^»]*»/.test(text)`.
+
+## 6. Setting catalogue (constant)
+
+```ts
+interface ISettingDefinition {
+  group: string; name: string; valueType: 'string' | 'json';
+  description: string; restartRequired: boolean;
+}
+export const SETTING_CATALOG: ISettingDefinition[]  // compiled from admin settings pages
+```
+Used by `list_settings`/`upsert_setting` dynamic descriptions and `get_setting` validation messages.
+
+## State transitions worth naming
+
+- **Tool present → after restart**: API deploys with a new tool; pod still lists the old snapshot ⇒ `inPod=false`, `afterRestart=true` for its group. Operator restarts ⇒ new pod calls `tools/list` ⇒ snapshot overwritten ⇒ `inPod=true`.
+- **Agent stopped**: `podStartedAt=null` ⇒ every `inPod=null`; the sheet shows the list without restart markers and the composer stays disabled as today.
+- **Tool removed from the caller's view** (e.g. self-service switched off): it disappears from the catalogue and `tools/call` refuses it with the existing "not available to this caller" text.
diff --git a/specs/016-agent-tool-parity/plan.md b/specs/016-agent-tool-parity/plan.md
new file mode 100644
index 00000000..6ac40391
--- /dev/null
+++ b/specs/016-agent-tool-parity/plan.md
@@ -0,0 +1,169 @@
+# Implementation Plan: Agent tool parity
+
+**Branch**: `feat/CLEAN-109-agent-tool-parity` | **Date**: 2026-09-22 | **Spec**: [spec.md](./spec.md)
+
+**Input**: Feature specification from `specs/016-agent-tool-parity/spec.md` (all clarifications settled; see its Decisions section)
+
+**Tracker**: [CLEAN-109](https://dreamvention.atlassian.net/browse/CLEAN-109)
+
+## Summary
+
+Restore the "chat is the hands" model: every admin-console capability gets an agent tool, the chat gets a **Tools** shelf that shows the live, per-agent tool list grouped by topic and drops a starter prompt into the composer, and the repo gets a standing rule that a module ships agent tools alongside tests.
+
+Technical approach, in one paragraph. Tools stay what they are today: `@Tool`-decorated methods on NestJS providers, discovered by `McpRegistryService` and served to runtimes from the API's own MCP endpoint (`/mcp/mcp`, `JwtAuthGuard`), filtered per caller through `IConditionallyListedTool` / `IDynamicallyDescribedTool`. Three additions make the feature: (1) the `@Tool` metadata grows `topic`, `title`, `template` and `destructive`, and the registry refuses to boot a tool without them, so the rule is enforced by the API, not by review alone; (2) ~90 new tools land in per-slice `*.tool.ts` files that call the same domain services the controllers call, gated with the existing `callerIsOperator` / `callerAgentId` helpers and a required `confirm: true` on anything destructive; (3) a new read surface, `GET /agents/:id/tools`, runs the same per-caller listing the runtime would get, groups it by topic, marks each tool "present in the running pod" from a per-agent snapshot recorded whenever a pod calls `tools/list`, and appends the agent's external MCP servers as opaque groups. The admin console gets a `toolCatalog` slice (gateway → store → sheet) and a Tools button in the bridle composer that inserts a template at the cursor and selects the first «…».
+
+## Technical Context
+
+**Language/Version**: TypeScript 5 on Bun (API: NestJS 11 + Prisma 6 + PostgreSQL; admin: Nuxt 3 / Vue 3 / Pinia / Tailwind / shadcn-vue on reka-ui 2)
+
+**Primary Dependencies**: `@modelcontextprotocol/sdk` (served by the in-repo `api/src/slices/mcp`), `zod` + `zod-to-json-schema` (tool parameters), `@hey-api/openapi-ts` (admin SDK from `api/swagger-spec.json`), `reka-ui` (accordion, sheet), `lucide-vue-next` (icons)
+
+**Storage**: PostgreSQL via Prisma; one new table `AgentToolListing` (per-agent snapshot of the last `tools/list` served). Schema lives per slice (`api/src/slices/**/*.prisma`, merged by `prisma-import` into `api/prisma/schema.prisma`); migrations under `api/prisma/migrations/<timestamp>_<name>/migration.sql`.
+
+**Testing**: API — jest, run directly (`cd api && NODE_OPTIONS=--experimental-vm-modules npx jest <path>`; **never** `bun run test`, it re-runs `prisma generate` and kills a running dev API on Windows). Admin — `bun test slices` for pure utils (`*.spec.ts` next to the util), `npx nuxt typecheck` for types (note: `bun run typecheck` regenerates the SDK; revert generated files after).
+
+**Target Platform**: Linux containers on k3s (API + admin), agent pods in the `agents` namespace reading tools once at boot.
+
+**Project Type**: Web application — `api/` (NestJS, CleanSlice slices) + `admin/` (Nuxt, CleanSlice slices). `app/` untouched.
+
+**Performance Goals**: Tools panel opens with data in < 500 ms on a warm API (one request, one DB read for the snapshot, one resolver call); `tools/list` for a runtime stays a single pass over the registry (snapshot write is fire-and-forget).
+
+**Constraints**: No agent runtime image change. Admin is English-only. Client state per `docs/state.md` (entity lives once in its Pinia store; components render by id). Secrets never leave the API through a tool result. Existing tool names unchanged (Decision 3). No commits without `CLEAN-109`.
+
+**Scale/Scope**: 59 existing tools gain metadata; ~90 new tools across 17 slices; 1 new API endpoint + 1 table; 1 new admin slice + 1 composer change; 1 canonical doc + rule in `CLAUDE.md` + graft pointers + PR template.
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+`.specify/memory/constitution.md` is the unfilled template, so there are no ratified principles to gate on. The project's standing rules act as the gate instead:
+
+| Gate (source) | Status | How the plan satisfies it |
+|---|---|---|
+| Jira first, branch from `origin/main`, `CLEAN-<n>` in every commit (`CLAUDE.md`) | PASS | CLEAN-109 in progress; branch `feat/CLEAN-109-agent-tool-parity` |
+| OpenAPI: never hand-write DTO types the generator emits (`CLAUDE.md`) | PASS | new endpoint → `bun run generate:swagger` → `bun run build:api` in admin; gateway maps DTO → domain type |
+| Client state: one entity, one store, render by id (`docs/state.md`) | PASS | `toolCatalog` store keyed by agent id; sheet renders `store.byAgent(id)`; `useAsyncData` only for pending/error |
+| Admin English-only, `app` i18n via `en.json` (`docs/i18n.md`) | PASS | admin only; no `app` strings |
+| Tools reuse domain services, never re-implement console rules (spec FR-008) | PASS | every tool constructor injects the same gateway/service the controller injects (see contracts/tools.md, "backing" column) |
+| Tests for every new tool (spec FR-007) | PASS | one `*.tool.spec.ts` per new tool file, three paths each; secret-leak scan test |
+| No secret in tool output (spec FR-004) | PASS with one documented exception | `create_api_key` returns the key once, exactly as the console does (research R6) |
+
+Post-design re-check (after Phase 1): no new violations. The one exception above is recorded in research.md and in the tool's description.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/016-agent-tool-parity/
+├── plan.md              # This file
+├── spec.md              # Feature spec with audit table and Decisions
+├── research.md          # Phase 0: decisions R1–R12
+├── data-model.md        # Phase 1: ToolMetadata, AgentToolListing, catalog DTO, admin store
+├── quickstart.md        # Phase 1: how to prove it works end-to-end
+├── contracts/
+│   ├── tool-metadata.md         # @Tool options, topics, startup validation, confirm convention
+│   ├── agent-tools.openapi.yaml # GET /agents/{id}/tools
+│   └── tools.md                 # the full tool inventory: topic · name · title · template · backing service
+├── checklists/requirements.md
+└── tasks.md             # Phase 2 (/speckit-tasks) — not created here
+```
+
+### Source Code (repository root)
+
+```text
+api/src/slices/
+├── mcp/
+│   ├── decorators/tool.decorator.ts      # + topic, title, template, destructive (ToolOptions)
+│   ├── decorators/topics.ts              # NEW: ToolTopics const + titles + order
+│   ├── services/mcp-registry.service.ts  # + validateToolMetadata() at bootstrap (FR-005)
+│   ├── services/handlers/mcp-tools.handler.ts  # listing logic extracted to ToolCatalogService; snapshot hook
+│   ├── services/tool-catalog.service.ts  # NEW: listFor(principal) — the per-caller list, reused by handler + endpoint
+│   ├── tooling.ts                        # NEW: ok/err/requireOperator/requireAgent/confirmed helpers (peer/toolSupport re-exports)
+│   └── interfaces/tool-listing-recorder.interface.ts  # NEW: optional IToolListingRecorder token
+├── agent/toolCatalog/                    # NEW slice
+│   ├── toolCatalog.prisma                # AgentToolListing
+│   ├── toolCatalog.controller.ts         # GET /agents/:id/tools
+│   ├── toolCatalog.module.ts
+│   ├── domain/toolCatalog.service.ts     # groups + inPod flags + external servers
+│   ├── domain/toolCatalog.types.ts
+│   ├── data/toolListing.gateway.ts       # Prisma upsert/read of the snapshot (implements IToolListingRecorder)
+│   └── dto/agentToolCatalog.dto.ts
+├── agent/agent/agentAdmin.tool.ts        # NEW: stop/start/delete/status/env/logs/mcps/capacity
+├── agent/file/file.tool.ts               # NEW: delete/sync/export
+├── agent/secret/secret.tool.ts           # NEW
+├── agent/agentChannel/agentChannel.tool.ts  # NEW
+├── agent/shareLink/shareLink.tool.ts     # NEW
+├── agent/template/templateAdmin.tool.ts  # NEW: create/delete/set_mcps/restart agents
+├── agent/templateInstall/templateInstall.tool.ts  # NEW: git preview/install, export path
+├── skill/skill.tool.ts                   # NEW: get/create/delete/import url/search/import
+├── llm/llm.tool.ts                       # NEW
+├── mcpServer/mcpServer.tool.ts           # NEW
+├── reins/knowledge/knowledgeAdmin.tool.ts  # NEW (operator set; query_knowledge stays)
+├── reins/source/source.tool.ts           # NEW
+├── setting/setting.tool.ts               # NEW: get/delete + SETTING_CATALOG; rancher list/upsert gain dynamic description
+├── user/user/user.tool.ts                # NEW
+├── user/apiKey/apiKey.tool.ts            # NEW
+├── chat/chat.tool.ts                     # NEW
+├── usage/usage.tool.ts                   # NEW: overview, per-llm
+├── log/log.tool.ts                       # NEW: get_agent_logs (or inside agentAdmin.tool.ts — tasks decide)
+├── upgrade/upgrade.tool.ts               # NEW
+├── integration/integration.tool.ts       # NEW
+├── paddock/scenario/scenario.tool.ts     # + generate
+├── paddock/evaluation/evaluation.tool.ts # + logs/scenario result/trace
+├── rancher/rancher.tool.ts               # metadata only (topics/titles/templates), no behaviour change
+├── agent/peer/*.tool.ts, bridle/attachment.tool.ts, browser/browser.tool.ts, reins/knowledge/knowledge.tool.ts  # metadata only
+└── **/*.tool.spec.ts                     # one per new tool file + registry validation spec + catalog spec
+
+admin/slices/
+├── agent/toolCatalog/                    # NEW slice
+│   ├── nuxt.config.ts, index.d.ts
+│   ├── domain/toolCatalog.types.ts, toolCatalog.gateway.ts, toolCatalog.service.ts
+│   ├── data/toolCatalog.gateway.ts, toolCatalog.mapper.ts
+│   ├── stores/toolCatalog.ts             # byAgent(id), fetch(id) upserts, filter/expanded state per agent
+│   ├── utils/insertTemplate.ts (+ .spec.ts), filterCatalog.ts (+ .spec.ts)
+│   └── components/toolCatalog/Sheet.vue, Group.vue, Row.vue, Empty.vue
+├── bridle/components/bridle/Input.vue    # + Tools button, template insertion, placeholder selection
+└── setup/theme/components/ui/accordion/  # NEW primitive (shadcn-vue on reka-ui)
+
+docs/agent-tools.md                       # NEW canonical rule + how-to
+CLAUDE.md                                 # + "Agent tools" section
+.claude/skills/graft/SKILL.md, .cursor/rules/graft.mdc  # + fenced project pointer block
+.github/PULL_REQUEST_TEMPLATE.md          # NEW with the parity check line
+```
+
+**Structure Decision**: Web application with the existing two CleanSlice projects. New tools live in the slice that owns the capability (this is also what the new rule prescribes), the shared MCP plumbing stays in `api/src/slices/mcp`, and the catalogue read surface is its own small slice under `agent/` because it joins agents, pods, the MCP resolver and the registry. The admin gets one new slice and a surgical change to the composer.
+
+## Phase 0 — Research
+
+Complete: see [research.md](./research.md). All Technical Context unknowns are resolved; no NEEDS CLARIFICATION remains.
+
+## Phase 1 — Design
+
+Complete: [data-model.md](./data-model.md), [contracts/](./contracts/), [quickstart.md](./quickstart.md).
+
+Design highlights the tasks phase must keep:
+
+1. **Metadata before tools.** The `ToolOptions` extension and registry validation land first; every existing tool file is annotated in the same commit so the API boots. Only then do new tool files start.
+2. **One helper module for gating.** `api/src/slices/mcp/tooling.ts` provides `ok`, `err`, `requireOperator(req)`, `requireAgent(req)`, `confirmed(args, what)`; `agent/peer/toolSupport.ts` re-exports the shared ones so nothing there changes behaviour.
+3. **Listing logic is shared, not duplicated.** `ToolCatalogService.listFor(principal)` in the mcp slice is the single implementation of "which tools does this caller see, with what description"; `McpToolsHandler` calls it for `tools/list`, the endpoint calls it with a synthetic principal built the same way `issueAgentServiceToken` builds an agent token payload (`sub: agent:<id>`, roles `Owner` for the admin agent, `Agent` otherwise).
+4. **Snapshot is a side effect of `tools/list`.** When the caller is an agent runtime, the handler upserts `AgentToolListing { agentId, toolNames, listedAt }` through the optional `IToolListingRecorder` (resolved with `strict: false`, so the mcp slice stays independent). Fire-and-forget; a failed write only logs.
+5. **`inPod` semantics** (data-model.md): no pod → `null`; pod and no snapshot → `false` (a pod that predates this feature needs a restart to get anything new); pod and snapshot → `toolNames.includes(name)`.
+6. **Admin composer owns insertion.** The Tools button and the sheet mount inside `Input.vue` so the sheet's `pick(template)` can write `input.value` and set the textarea selection on the first «…» without prop drilling. Restart reuses `agentStore.restart(id)` (optimistic patch + rollback already there).
+7. **Rule lives in three places, one canonical.** `docs/agent-tools.md` is canonical; `CLAUDE.md` states the rule and links it; graft skill and Cursor rule carry a fenced `<!-- ranch:agent-tools -->` pointer block re-applied by a tiny script if `graft init` overwrites them (research R11).
+
+## Phase 2 — Tasks (preview, not generated here)
+
+`/speckit-tasks` should produce roughly this order, each topic a checkpoint comment on CLEAN-109:
+
+1. Metadata + validation + shared helpers + annotate all 59 existing tools; API boots; registry spec.
+2. `AgentToolListing` + recorder hook + `ToolCatalogService` + `GET /agents/:id/tools` + swagger regen + tests.
+3. Admin: accordion primitive, `toolCatalog` slice, composer button + insertion + "after restart" + utils specs; typecheck.
+4. Tools by topic, one commit each with specs: agents · workspace · templates · skills · LLM · MCP servers · knowledge · sources · settings · users & keys · chats & usage · browser & integrations · paddock · platform.
+5. Secret-leak scan test across all tools; quickstart run-through.
+6. Docs: `docs/agent-tools.md`, `CLAUDE.md`, graft pointers, PR template; README one-liner.
+7. Final: full jest run, admin typecheck, PR into `main`, link on CLEAN-109, In Review.
+
+## Complexity Tracking
+
+No constitution violations to justify. Two deliberate choices that add surface, with the simpler alternative and why it was rejected, are recorded in research.md: the per-agent snapshot table (R4, vs. reusing MCP-server drift) and the synthetic-principal listing (R3, vs. a second static catalogue).
diff --git a/specs/016-agent-tool-parity/quickstart.md b/specs/016-agent-tool-parity/quickstart.md
new file mode 100644
index 00000000..906fddc3
--- /dev/null
+++ b/specs/016-agent-tool-parity/quickstart.md
@@ -0,0 +1,86 @@
+# Quickstart: proving CLEAN-109 works
+
+Validation guide for the implemented feature. Implementation details are in tasks.md; this file only says how to run and what to expect.
+
+## Prerequisites
+
+- Local stack running: `make dev` (api :3000, admin :3002) with a k3d cluster, or the CLI `ranch dev`.
+- An Owner login for the admin console and a Rancher admin agent deployed (Rancher page shows the chat).
+- `.env.project` keys are not needed for validation.
+
+## 1. The API refuses to boot a tool without metadata (FR-005)
+
+```bash
+cd api
+NODE_OPTIONS=--experimental-vm-modules npx jest src/slices/mcp/services/mcp-registry.service.spec.ts
+```
+Expected: the "validation" cases pass — a provider whose `@Tool` lacks `topic`, `title` or `template`, or is `destructive` without a `confirm` parameter, makes `onApplicationBootstrap` throw with the tool name in the message.
+
+## 2. Every tool file has tests; nothing leaks a secret (FR-004, FR-007)
+
+```bash
+cd api
+NODE_OPTIONS=--experimental-vm-modules npx jest "\.tool\.spec\.ts$" src/slices/mcp/tool-secrets.spec.ts
+```
+Expected: green. The secrets spec calls each secret-taking tool with a sentinel and asserts the sentinel is absent from the result, except `create_api_key`.
+
+Never run `bun run test` in `api/` while a dev API is up — it re-runs `prisma generate` and kills the running process.
+
+## 3. The catalogue endpoint returns the live per-agent list (FR-009)
+
+```bash
+# token: an Owner bearer from the admin login; AGENT: the Rancher admin agent id
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:3000/agents/$AGENT/tools | jq '.groups[] | {key, kind, afterRestart, n: (.tools|length)}'
+```
+Expected: builtin groups in topic order (agents, agent_workspace, templates, skills, llm, mcp_servers, knowledge, settings, peers, paddock, users_keys, chats_usage, browser, attachments, platform), each with `n > 0`; external MCP servers from the agent's template as `kind: external` with `n: 0`; no `url` or `authValue` anywhere in the body.
+
+Repeat with a non-admin agent id: operator-only groups are absent (only `knowledge`, `peers` self-service, `browser`, `attachments` remain).
+
+## 4. "After restart" is true, then clears (FR-014, SC-007)
+
+1. With the Rancher agent running, note `podStartedAt` and `listedAt` from step 3.
+2. Deploy an API build that adds a tool (or, for a quick check, temporarily rename one tool's `name`); restart only the API.
+3. `GET /agents/$AGENT/tools` → the new tool has `inPod: false` and its group `afterRestart: true`.
+4. Restart the agent from the console (or `restart_agent`). After the pod reconnects, step 3 shows `inPod: true`, `listedAt` newer than `podStartedAt`.
+
+## 5. The Tools panel (FR-010 … FR-016)
+
+Open the admin console → Rancher page. Beside the paperclip there is a wrench button with a tooltip "Tools".
+
+- Click it: a sheet opens, accordions in topic order, each row shows title, technical name in small type, description. Empty topics are absent.
+- Type `mcp` in the search: only MCP-related rows remain across topics, their topics expanded. Clear: previous expansion restored.
+- Click "Register an MCP server": the sheet closes, the composer contains the template, the first «…» is selected, nothing was sent. Edit the text and send.
+- With a draft already typed, pick a tool: the template is appended with a space, the draft is intact.
+- Stop the agent: the panel still opens (no restart markers), the composer is disabled as before.
+- After step 4.3: the affected group shows "after restart" with a restart button; clicking it runs the normal restart flow and the marker clears after the pod is back.
+- Narrow the window to phone width: the sheet is full-width and scrollable; Tab/Enter reach every row.
+
+Same checks on an agent's Chat tab (`/agents/<id>?tab=chat`).
+
+## 6. Parity through the chat alone (SC-002)
+
+In the Rancher chat, one prompt each, without opening another page:
+
+1. "Register the MCP server at https://example.com/mcp named Example with no auth and attach it to the researcher template" → MCP list shows it, template has it, researcher agents show "pending restart".
+2. "Add https://docs.example.com/sitemap.xml to the knowledge base Docs and index it" → sources appear, indexing starts.
+3. "Create an LLM credential Test-Anthropic for anthropic with key sk-test… and health-check it" → credential listed, key not in the reply, health result reported.
+4. "Create a user Jane with email jane@example.com and make her an admin" → user listed with role admin, after the agent asked for confirmation on the role change.
+5. "Create an API key named ci-deploy" → key shown once; "revoke it" → gone after confirmation.
+6. "Delete the agent test-bot" → the agent asks to confirm first; "yes" → deleted.
+
+Then, as a non-admin agent (any agent chat in the console): "List the users" → refused with a message naming the operator/console.
+
+## 7. Admin typecheck and util tests
+
+```bash
+cd admin
+bun test slices
+npx nuxt typecheck   # not `bun run typecheck` — it regenerates the SDK; revert generated files if it did
+```
+Expected: `insertTemplate` and `filterCatalog` specs green; typecheck clean.
+
+## 8. The rule is where people look (FR-018 … FR-020)
+
+- `CLAUDE.md` has an "Agent tools" section linking `docs/agent-tools.md`.
+- `.claude/skills/graft/SKILL.md` and `.cursor/rules/graft.mdc` contain the `ranch:agent-tools` block; run `graft init --yes --no-global` and then `node scripts/ensure-agent-tools-rule.mjs` → the block is back.
+- `.github/PULL_REQUEST_TEMPLATE.md` has the parity checklist line.
diff --git a/specs/016-agent-tool-parity/research.md b/specs/016-agent-tool-parity/research.md
new file mode 100644
index 00000000..3a7912c2
--- /dev/null
+++ b/specs/016-agent-tool-parity/research.md
@@ -0,0 +1,118 @@
+# Research: Agent tool parity (CLEAN-109)
+
+Date: 2026-09-22. Every item below resolves a question the plan depended on. Facts were read from the code on this branch (graft + source), not assumed.
+
+## R1 — Where tool metadata lives and how to make it mandatory
+
+**Decision**: Extend `ToolOptions` / `ToolMetadata` in `api/src/slices/mcp/decorators/tool.decorator.ts` with `topic: ToolTopic`, `title: string`, `template: string`, `destructive?: boolean`. Add `validateToolMetadata()` to `McpRegistryService.onApplicationBootstrap` (after `discoverTools`) that throws `Error('Tool "<name>" is missing <field>')` for any tool without `topic`, `title` or `template`, and for any `destructive` tool whose Zod parameters lack a required boolean `confirm`. A thrown error at bootstrap fails the API start, which is the enforcement FR-005 asks for.
+
+**Rationale**: The decorator is the single entry point for every tool (59 today, all in the API), and the registry already walks them at boot. Failing fast at startup is cheaper and more reliable than a lint rule or a review checklist.
+
+**Alternatives considered**: ESLint rule on `@Tool({` calls (misses dynamic construction, needs a plugin); a test that snapshots the registry (would pass locally and fail only when someone remembers to run it).
+
+## R2 — Topics: how many and which
+
+**Decision**: A `ToolTopics` const in `api/src/slices/mcp/decorators/topics.ts` with 14 topics, each with a stable key, a display title and a sort order (see contracts/tool-metadata.md). Topics mirror console sections; small sections merge as the spec allows: *Users & API keys*, *Chats & usage*, *Browser & integrations*. Agents split into *Agents* (lifecycle, config, status) and *Agent workspace* (files, secrets, channels, share link) so neither accordion exceeds ~15 rows.
+
+**Rationale**: The accordion is only useful when a topic fits on one screen. Fourteen topics × ≤ 16 tools is scannable; one "Agents" topic with 30 rows is not.
+
+**Alternatives considered**: derive topic from the tool name prefix (breaks for `agent_usage`, `browser_session_*`, `query_attachment`); one topic per slice (too many, and slices are an implementation detail the panel should not show).
+
+## R3 — How the console gets "the list this agent would see"
+
+**Decision**: Extract the per-tool resolution loop from `McpToolsHandler.registerHandlers` (resolve provider → `isListedForRequest` → `describeForRequest` → static fallback) into `ToolCatalogService.listFor(principal)` in the mcp slice, where `principal` is the `IAuthTokenPayload`-shaped object that `JwtAuthGuard` puts on `httpRequest.user`. The handler wraps the real request; the new endpoint builds a synthetic one: `{ sub: 'agent:<id>', roles: agent.isAdmin ? [Owner] : [Agent], email: '' }` — the same shape `issueAgentServiceToken` in `user/auth/domain/auth.service.ts` mints for runtimes (verify the exact role assignment there when implementing; `toolSupport.ts` documents "admin agents hold Owner, plain agents hold Agent").
+
+**Rationale**: The listing hooks take an `express.Request` today and read only `.user`; a synthetic request with the same `user` yields exactly what the pod would see, including dynamic descriptions (e.g. `query_knowledge` listing bound bases). One implementation, two callers, no drift.
+
+**Alternatives considered**: a static catalogue in the admin (rejected in the spec's Decision 2); calling the MCP endpoint from the API to itself with a minted token (needless HTTP hop, session-id dance).
+
+## R4 — Knowing whether the running pod already has a tool
+
+**Decision**: New Prisma model `AgentToolListing { agentId String @id, toolNames Json, listedAt DateTime }` in a new `agent/toolCatalog` slice. `McpToolsHandler` after computing the list calls an optional `IToolListingRecorder.record(agentId, names)` (token resolved with `moduleRef.get(TOKEN, { strict: false })`, no-op when absent) when `callerAgentId(httpRequest)` is set. The catalogue endpoint computes `inPod` per tool: no pod → `null`; pod but no snapshot → `false`; else `toolNames.includes(name)`. A restart makes the pod list again, which overwrites the snapshot and clears the flags.
+
+**Rationale**: Precise per-tool truth with one small table and one write per pod boot. The existing MCP-server drift (`detectMcpConfigDrift`, compares server row `updatedAt` to pod start) cannot see a change inside the built-in server's tool set, since tools are code, not rows. Persisting to the DB (not memory) survives API restarts, which are exactly when new tools appear.
+
+**Alternatives considered**: bump the built-in Ranch server row's `updatedAt` on boot when a hash of the tool catalogue changed, so the existing drift banner fires (rejected: whole-group marking only, and it would flag every agent after every API deploy even when nothing they can use changed); in-memory map (lost on API restart, the common case).
+
+## R5 — Destructive tools and confirmation
+
+**Decision**: Every tool that deletes, revokes, replaces wholesale, changes a role, or runs an upgrade declares `destructive: true` and a `confirm: z.boolean()` parameter described as "Set true only after the person confirmed in the chat." A shared `confirmed(args, what)` helper in `mcp/tooling.ts` returns `err('This will <what>. Ask the person to confirm, then call again with confirm: true.')` when `confirm !== true`. The tool description ends with the same sentence, so the model reads the rule before calling.
+
+**Rationale**: The API cannot see the chat; the argument is the only server-side proof that the model went through a confirmation step. The registry validation (R1) guarantees no destructive tool forgets the parameter.
+
+**Alternatives considered**: a chat-level confirmation UI (out of scope per spec); description-only (no server-side check; a model that skips the text deletes).
+
+## R6 — Secrets in and out
+
+**Decision**: Tools that accept a secret (`create_llm`, `update_llm`, `register_mcp_server`, `update_mcp_server`, `set_agent_secret`, `replace_agent_secrets`, `create_user` password, `create_integration_account` secret) take it as a parameter and return metadata only; listings return names/ids/metadata with secret fields stripped in the tool (never rely on the gateway to omit them). One exception, mirroring the console: `create_api_key` returns the plaintext key once in its result, because the key exists nowhere else afterwards; its description says so and tells the model to hand it to the person verbatim and not repeat it. A cross-cutting spec (`api/src/slices/mcp/tool-secrets.spec.ts`) calls every secret-taking tool with a sentinel string and asserts it does not appear in the result.
+
+**Rationale**: FR-004 with the one place where the product's own behaviour requires returning a secret.
+
+**Alternatives considered**: making `create_api_key` console-only (breaks parity for a common ask); returning a masked key (useless to the person).
+
+## R7 — Where the settings tool learns the keys
+
+**Decision**: A `SETTING_CATALOG` constant in `api/src/slices/setting/domain/settingCatalog.ts`: `{ group, name, valueType, description, restartRequired }[]` compiled from the admin settings pages (`admin/slices/setting/pages/settings/*.vue` and `components/setting/nav/Menu.vue`: organization, agents, auth, github, bridle, knowledge, rancher, mcp, storage, secrets). `list_settings` and `upsert_setting` implement `IDynamicallyDescribedTool` and append the catalogue (group · name · meaning) to their description; `get_setting` / `delete_setting` are added. Unknown group/name on upsert is still allowed (the console allows it), but the tool result names the nearest catalogued key.
+
+**Rationale**: FR-006. The catalogue is the smallest thing that makes "change the organisation name" work without the model guessing `organization.name`.
+
+**Alternatives considered**: reading the keys from the admin at runtime (wrong direction of dependency); a DB table of setting definitions (over-engineering for ~25 keys).
+
+## R8 — Admin UI primitives
+
+**Decision**: Use the theme's `Sheet` (side panel, works at phone width, focus-trapped, Esc closes) for the panel; add an `accordion` primitive under `admin/slices/setup/theme/components/ui/accordion/` generated the shadcn-vue way on `reka-ui` (already a dependency: `reka-ui ^2.9.6`); `Input` for search; `Tooltip` on the button; `Skeleton` while loading. Icon: `Wrench` from lucide.
+
+**Rationale**: The theme has sheet, tooltip, input, scroll-area and skeleton but no accordion or popover; reka-ui ships an accessible Accordion, so adding the shadcn wrapper is a 60-line file, not a dependency.
+
+**Alternatives considered**: `<details>` elements (no keyboard-consistent behaviour, no animation, inconsistent styling); dropdown-menu (not scrollable, no search).
+
+## R9 — Inserting the template at the cursor
+
+**Decision**: The Tools button and sheet live inside `admin/slices/bridle/components/bridle/Input.vue`, which already owns `input` (the draft) and `textareaRef`. `pick(template)`: read the native textarea (`textareaRef.value?.$el`), splice the template at `selectionStart` (prefix with a space if the draft is non-empty and does not end with whitespace), set `input.value`, then on `nextTick` focus and `setSelectionRange` on the first `«…»`. A pure `insertTemplate(draft, cursor, template)` util returns `{ text, selectionStart, selectionEnd }` and is unit-tested with `bun test`. Remaining placeholders are highlighted by a small `hasPlaceholder` computed that adds an outline class to the textarea (spec edge case).
+
+**Rationale**: No prop drilling through `Provider.vue`; the composer is the only component that should touch the draft.
+
+**Alternatives considered**: emitting `insert` from Provider down to Input (adds an event hop and a second owner of the draft); a contenteditable composer (out of scope).
+
+## R10 — Admin state and data flow
+
+**Decision**: New slice `admin/slices/agent/toolCatalog/` with the standard CleanSlice layout: `data/` gateway over the generated SDK (`AgentsService.getAgentTools` after regen) + mapper to `IAgentToolCatalog`; `domain/` types + gateway interface + service; `stores/toolCatalog.ts` holding `catalogs: Record<agentId, IAgentToolCatalog>`, `byAgent(id)`, `fetch(id)` (upserts), and UI state per agent (`query`, `expanded: string[]`) so reopening the sheet restores the accordion; `components/toolCatalog/Sheet.vue` renders `store.byAgent(agentId)` and uses `useAsyncData` for `pending`/`error`/`refresh` only. Restart goes through `useAgentStore().restart(id)`.
+
+**Rationale**: `docs/state.md` verbatim. The catalogue is an entity keyed by agent; two open chats must not share it (the bridle store learned this in CLEAN-102).
+
+**Alternatives considered**: fetching inside the sheet with `useFetch` and rendering `data` (forbidden by the state rules).
+
+## R11 — Where the rule lives so graft does not erase it
+
+**Decision**: `docs/agent-tools.md` is canonical (rule, definition of done, file layout, metadata, gating, confirm, secrets, tests, reference module = `agent/peer`). `CLAUDE.md` gets an "Agent tools" section (five lines + link). `.claude/skills/graft/SKILL.md` and `.cursor/rules/graft.mdc` get a fenced block:
+
+```
+<!-- ranch:agent-tools:start -->
+Project rule: a module is not done until the agent has tools for what it does — see docs/agent-tools.md.
+<!-- ranch:agent-tools:end -->
+```
+
+plus `scripts/ensure-agent-tools-rule.mjs` that re-inserts the block if missing (idempotent; run by `make init` / documented in the doc). `.github/PULL_REQUEST_TEMPLATE.md` is created with the checklist line "console capability added → agent tool added, with tests" (none exists today).
+
+**Rationale**: `graft init` rewrote the skill file on this very branch; a pointer that can be re-applied mechanically survives that. Keeping the rule short in graft files and long in `docs/` matches how the repo already treats `docs/state.md` and `docs/i18n.md`.
+
+**Alternatives considered**: editing only `CLAUDE.md` (the ticket asks for graft explicitly); a `graft` custom-section feature (none in `graft --help`).
+
+## R12 — Testing approach
+
+**Decision**: Follow `agent/peer/peerAdmin.tool.spec.ts`: construct the tool with `jest.Mocked` gateways, build requests with `{ user: { sub, roles } }`, assert (a) listed for operator / not for plain agent, (b) happy path calls the gateway with the mapped arguments and returns `ok(...)`, (c) not-found and refusal come back as `isError` text that names the next move, (d) destructive tools refuse without `confirm`. Registry validation gets its own spec with a fake provider missing each field. The catalogue service gets a spec for the `inPod` matrix and external-server grouping. Admin utils get `bun test` specs. Run jest directly, never `bun run test`.
+
+**Rationale**: The peer tools are the model the spec names; their tests are the most complete in the repo.
+
+**Alternatives considered**: e2e through the MCP endpoint (slower, and the handler already has its own spec).
+
+## Facts gathered (for tasks)
+
+- MCP endpoint: `McpModule.forRoot({ mcpEndpoint: 'mcp/mcp', guards: [JwtAuthGuard], streamableHttp: { statelessMode: false } })` in `api/src/app.module.ts`.
+- Caller helpers: `callerAgentId`, `callerIsOperator`, `ok`, `err`, `withRefusalAdvice` in `api/src/slices/agent/peer/toolSupport.ts`; `RancherTool.requireOwner` duplicates the operator check with a different message.
+- Built-in MCP servers and ids: `mcp-ranch`, `mcp-knowledge`, `mcp-documents`, `mcp-cleanslice` in `api/src/slices/mcpServer/domain/mcpServer.seeder.ts`; `AgentMcpResolver.resolveForAgent` returns template servers + built-ins; `GET /agents/:id/mcps` and `GET /agents/:id/mcp-status` already exist.
+- Pod start time comes from `IPodGateway.list()` (`startedAt`), as used in `getMcpStatus`.
+- Controllers' injected services (the "backing" column in contracts/tools.md) were read from each controller's constructor.
+- Admin restart: `admin/slices/agent/agent/stores/agent.ts` → `restart(id)`; pending-restart state lives in the same store (`isPendingRestart`, `markPendingRestart`).
+- Admin has no unit tests today (`bun test slices` finds none); `*.spec.ts` next to a util is the convention to start.
+- Prisma: per-slice `*.prisma` merged into `api/prisma/schema.prisma`; migrations are hand-written SQL under `api/prisma/migrations/<YYYYMMDDHHMMSS>_<name>/`.
diff --git a/specs/016-agent-tool-parity/spec.md b/specs/016-agent-tool-parity/spec.md
new file mode 100644
index 00000000..23521404
--- /dev/null
+++ b/specs/016-agent-tool-parity/spec.md
@@ -0,0 +1,204 @@
+# Feature Specification: Agent tool parity — the agent can do everything the console can
+
+**Feature Branch**: `feat/CLEAN-109-agent-tool-parity`
+
+**Created**: 2026-09-22
+
+**Status**: Draft — clarifications settled 2026-09-22; ready for `/speckit-plan`
+
+**Tracker**: [CLEAN-109](https://dreamvention.atlassian.net/browse/CLEAN-109) — `[ADMIN][API]`, labels `admin`, `api`
+
+**Input**: User description: "Я хочу обсудить и закрыть фундаментальную проблему философии нашего ранчера. Изначальная задумка была в полной автономности настройки платформы через чат с агентом, который имеет всевозможные тулзы и через чат делает всё что угодно в скоупе ранча — создаёт/редактирует/добавляет/управляет. Мы отошли от правильного паттерна: то, что настраивается через админку, не видно для агента, у которого нет нужных инструментов. Искоренить: (1) изучить текущий спектр возможностей админки и то, что покрывают тулзы, дописать недостающие; (2) кнопка Tools в чате — аккордеоны по топикам (например a2a), внутри название и описание каждого инструмента, клик вставляет лёгкий промт-шаблон в чат, максимальный UX; (3) правило в CLAUDE.md и в graft: любой новый модуль помимо тестов должен покрываться тулзами для агента."
+
+## Overview
+
+Ranch was designed around one idea: **the console is a window, the chat is the hands.** An operator should be able to open the Rancher chat, say "create a researcher agent on the Claude credential with the docs knowledge base, give it the A2A peer «billing» and restart it", and have it happen. Every screen in the admin console is, in that model, a convenience over something the agent could also do.
+
+That model has drifted. Feature by feature, the console gained screens whose actions have no counterpart in the agent's tool list. Today the console can manage **19 kinds of things**; the agent has tools for **7 of them in full, 5 in part, and 7 not at all** (the audit below has the detail). An operator who asks the Rancher agent to "register the GitHub MCP server" or "add this URL to the docs knowledge base" gets "I can't do that from here" — not because the platform can't, but because nobody handed the agent the tool.
+
+This feature closes the gap and makes sure it stays closed. Three parts:
+
+1. **Parity.** Every capability the admin console exposes is reachable by the agent through a tool, with the same permission model the console applies. The audit in this document is the checklist; the work is done when every row reads "covered".
+2. **A visible tool shelf.** A person in the chat should not have to guess what the agent can do. A **Tools** button beside the composer opens the agent's tool list grouped by topic; each tool shows its name and a plain-language description, and one click drops a ready-to-edit prompt into the composer. What the agent can do becomes something you can see and try, not something you discover by asking.
+3. **A standing rule.** The project's working instructions (for people and for coding agents) state that a module is not finished until the agent has tools for what it does, the same way it is not finished without tests. The rule names where tools live, how they are grouped and described, and what the reviewer checks.
+
+**In scope**: the audit and the tools that close it, on the API; the Tools panel in the admin console's two chat surfaces (the Rancher page and an agent's Chat tab); a read surface the console uses to learn an agent's current tool list; the rule in `CLAUDE.md` and the graft guidance; tests for every new tool.
+
+**Out of scope, deliberately**: any change to the agent runtime image (tools are served by the API, as today); a Tools panel in the user console (`app`) or the public share page; tools for things the console itself cannot do; changing the permission model (a tool never lets a caller do what the console would refuse that same person); natural-language "macros" that chain several tools.
+
+## The audit: what the console can do vs. what the agent can do
+
+Read this table as the definition of "parity". "Console" is what an operator can do from the admin UI today. "Agent today" is what the agent has a tool for. "Gap" is what this feature adds. Names in the Gap column are indicative; the plan decides exact names, but every action listed must exist.
+
+| # | Area (console section) | Console can | Agent today | Gap to close |
+|---|---|---|---|---|
+| 1 | **Agents** | list, view, create, edit (name, credential, knowledge, resources), promote/demote admin, restart, stop, start, delete, view live status and metrics, view pod env preview, view pod logs, view its MCP servers and "pending restart" state, capacity | list, get, create, update, set admin, restart, usage | stop, start, delete, status/metrics, env preview, logs (tail), MCP list + drift state, capacity |
+| 2 | **Agent → Secrets** | list keys, set, delete, replace all | — | list, set, delete, replace |
+| 3 | **Agent → Channels** | view and set delivery channels | — | get, set |
+| 4 | **Agent → Share link** | view, create, regenerate, revoke | — | get, create, regenerate, revoke |
+| 5 | **Agent → Workspace files** | list, read, write, delete, sync from pod, export | list, read, write | delete, sync, export |
+| 6 | **Agent → A2A peers** | card, peers, candidates, preview, connect, import external, refresh, remove, delegations | all of it (operator set + agent self-service set + `ask_agent`) | none — this is the model to copy |
+| 7 | **Agent → Paddock** | scenarios per agent, run evaluation, report | covered (see 15, 16) | none |
+| 8 | **Templates** | list, view, create, edit, delete, set skills, **set MCP servers**, files list/read/write/upload, install from zip, install from git, export | list, get, update, set skills, files list/read/write | create, delete, set MCP servers, upload file, install (zip/git, with preview), export |
+| 9 | **Skills** | list, view, create, edit, delete, import from URL, search curated repos and import, which agents use a skill, redeploy them | list, update, agents-of-skill, redeploy | get, create, delete, import from URL, search + import |
+| 10 | **LLM credentials** | list, view, create, edit, delete, health-check, models catalogue, usage per credential | list | get, create, update, delete, health-check, models, usage |
+| 11 | **MCP servers** | list, view, register, edit / enable / disable, delete, start OAuth | — | list, get, register, update, enable/disable, delete (OAuth start: expose the URL the person must open) |
+| 12 | **Knowledge bases** | list, view, create, edit, delete, index, overview, graph + labels, ask, service status | ask (`query_knowledge`, only bases bound to the caller) | list, get, create, update, delete, index, overview, graph labels, status |
+| 13 | **Knowledge → Sources** | list, add file/url/text, add many files, from sitemap, from archive, reindex one, re-extract, delete, imports in progress, export | — | list, add url/text, from sitemap, reindex, re-extract, delete, imports (file/archive upload: accept a path the agent can already read, see Assumptions) |
+| 14 | **Settings** (organization, agent defaults, authentication, GitHub, Bridle, Knowledge, Rancher, MCP, Storage, Secrets) | list group, view one, set, delete | list, upsert | get one, delete; and the tool must *tell* the agent which groups and keys exist (today it has to guess) |
+| 15 | **Paddock → Scenarios** | list, view, create, **generate from description**, edit, delete | list, get, per-agent, create, update, delete | generate |
+| 16 | **Paddock → Evaluations** | run, list, view, report, logs, per-scenario result, trace, abort, rerun | run, list, get, report, abort, rerun | logs, per-scenario result, trace |
+| 17 | **Users** | list, view, create, edit, set role, delete | — | list, get, create, update, set role, delete |
+| 18 | **API keys** | list, create, revoke | — | list, create, revoke |
+| 19 | **Chats** | list, view, messages, sync from runtime, summarize, feedback, export | — | list, get, messages, sync, summarize, export |
+| 20 | **Usage** | per agent, per credential, overview | per agent | overview, per credential |
+| 21 | **Browser sessions / Integrations** | sessions: list, open, reset, status, VNC URL, close; integrations: catalogue, accounts, login, import cookies, secret, delete | sessions: all | integrations: catalogue, accounts list/create/login/delete |
+| 22 | **Ranch upgrade** | status, run upgrade | — | status, run |
+| 23 | **Chat attachments** | — (chat only) | `query_attachment` | none |
+| 24 | **Setup wizard, login, sessions page** | one-time / per-person | — | none — not agent work |
+
+Two structural facts the plan must respect, because the audit found them and the panel depends on them:
+
+- **Every built-in tool is served from one place** (the Ranch MCP server the API hosts) and the list a caller sees is filtered per caller: some tools are only listed for operator-role callers, some only for agent runtimes, one only when the agent has knowledge bound. The Tools panel must show the list *this* agent sees, not the union.
+- **A pod reads its tool list once at boot.** A tool added after the agent started is not in its hands until restart. The console already knows this for MCP servers ("pending restart"); the Tools panel must say it too, or people will click a tool the agent cannot yet call.
+
+## User Scenarios & Testing *(mandatory)*
+
+### User Story 1 - The Rancher agent can do what the console can (Priority: P1)
+
+An operator opens the Rancher chat and asks for things they would otherwise click through: "register the MCP server at https://… with bearer auth and attach it to the researcher template", "add https://docs.example.com/sitemap.xml as sources of the docs knowledge base and index it", "create an API key named ci-deploy", "delete the test-bot agent". The agent does it, reports what it did, and the console shows the result on the next load. Where the console would ask for confirmation (deletes, revokes, role changes), the agent asks in the chat before acting.
+
+**Why this priority**: This is the philosophy the ticket restores. Without parity, the panel in Story 2 would only advertise how little the agent can do.
+
+**Independent Test**: For every row of the audit with a non-empty Gap, ask the Rancher agent to perform each listed action on a throwaway entity and verify in the console that it happened, then undo it through the agent. Ask a non-admin agent for an operator-only action and confirm it is refused with a message that names the console as the place to do it.
+
+**Acceptance Scenarios**:
+
+1. **Given** the audit table, **When** the feature ships, **Then** every action in the Gap column has a tool, and the agent's tool list for an operator-role caller includes each of them.
+2. **Given** an operator asks the Rancher agent to register an MCP server and attach it to a template, **When** the agent finishes, **Then** the server is in the console's MCP list, attached to that template, and agents of that template show "pending restart".
+3. **Given** an operator asks to delete an agent, revoke an API key, remove a user or change a role, **When** the agent has the tool, **Then** it states what will be removed and waits for a "yes" in the chat before calling the tool; the tool description carries that instruction so it holds for any runtime.
+4. **Given** a caller without the operator role (a regular agent runtime), **When** it lists tools, **Then** operator-only tools are absent, and a direct call to one is refused with a message that explains who may do it.
+5. **Given** an action the console performs with a secret (an LLM key, an integration secret, a bearer for an MCP server), **When** the agent performs it, **Then** the secret travels in the tool call and is never echoed back in the tool's result, the agent's reply, or the transcript.
+6. **Given** every new tool, **When** the test suite runs, **Then** each tool has tests for the happy path, the refused-caller path, and the not-found path, in the style of the existing peer and knowledge tool tests.
+
+---
+
+### User Story 2 - See what the agent can do, and try it in one click (Priority: P1)
+
+Beside the chat composer there is a **Tools** button. It opens a panel listing the agent's tools grouped by topic — *Agents, Templates, Skills, LLM credentials, MCP servers, Knowledge, Settings, Peers (A2A), Paddock, Users & keys, Chats & usage, Browser, Attachments* — as collapsible accordions. Expanding a topic shows each tool as a row: a short human title, the tool's technical name in smaller type, and a one-line description that says what it does in plain words. A search box filters across all topics as you type. Clicking a tool row inserts a **prompt template** into the composer — a short, natural sentence with obvious placeholders ("Restart the agent «…»", "Add the URL … to the knowledge base «…» and index it") — puts the cursor on the first placeholder, and closes the panel; the person edits and sends. Tools the running agent does not yet have (added since it booted) are shown greyed with "after restart" and a restart shortcut, so nobody sends a prompt the agent cannot act on.
+
+**Why this priority**: The ticket asks for "maximum UX": the value of parity is invisible if a person has to guess the vocabulary. The panel turns the tool list into a menu.
+
+**Independent Test**: Open the Rancher chat, press Tools, expand *MCP servers*, click "Register an MCP server"; confirm the composer holds the template with the cursor on the first placeholder and the panel is closed. Edit the template freely and send; confirm nothing constrained the edit. Type "knowledge" in the panel's search and confirm only knowledge tools remain. Attach a new MCP server to the agent's template without restarting, reopen Tools and confirm that group is marked "after restart" with a restart button that works.
+
+**Acceptance Scenarios**:
+
+1. **Given** the Rancher chat or an agent's Chat tab, **When** the person presses Tools, **Then** a panel opens listing exactly the tools that agent's runtime would receive (per-caller filtering applied), grouped by topic, each with title, technical name and description; topics with no tools are not shown.
+2. **Given** the panel is open, **When** the person clicks a tool, **Then** its prompt template is inserted at the composer's cursor (appended with a space if the composer already has text), the first placeholder is selected, the panel closes, and nothing is sent.
+3. **Given** the panel is open, **When** the person types in the search box, **Then** rows are filtered by title, technical name and description across all topics, with matching topics expanded; clearing the box restores the accordion state.
+4. **Given** a tool was added after the agent's pod started, **When** the panel is opened, **Then** the tool (or its whole topic) is visibly marked "after restart", its click still inserts the template but the row explains the agent will not act until restarted, and a restart control is offered that reuses the existing restart flow.
+5. **Given** the agent's tool list cannot be loaded (agent stopped, API error), **When** the panel is opened, **Then** it says so in one line and offers retry; the composer keeps working.
+6. **Given** the panel is open on a narrow window, **When** it renders, **Then** it is usable at phone width (a sheet or drawer, not a hover popover), and keyboard users can open it, move between rows and pick one without a mouse.
+7. **Given** the person has never used the panel, **When** they open the chat for the first time, **Then** the Tools button is discoverable next to the attach button, with a tooltip, and needs no onboarding.
+
+---
+
+### User Story 3 - The rule that keeps parity (Priority: P2)
+
+A developer (or a coding agent) adds a new capability to the console. The project instructions tell them, in the same place that tells them to write tests and to create a Jira issue, that **the module is not done until the agent has tools for what it does**: where tool files live, that each tool declares a topic and a prompt template, how permissions are expressed, that every tool ships with tests, and that the PR reviewer checks it. The graft guidance carries the same rule, so a coding agent that starts from graft reads it before it reads the code.
+
+**Why this priority**: Without this, the audit will be out of date in a month. It is P2 only because it depends on the vocabulary Story 1 and 2 establish (topics, templates, gating).
+
+**Independent Test**: Read `CLAUDE.md` and the graft guidance as a newcomer: both state the rule, name the tool location and the required metadata, and point at one existing module as the reference example. Start a fresh coding-agent session in the repo and ask "I added a new console feature, what else must I ship?" — the answer names agent tools and tests without further prompting.
+
+**Acceptance Scenarios**:
+
+1. **Given** `CLAUDE.md`, **When** read, **Then** it has a short section stating the parity rule, the definition of done for a module (tests + tools + topic + template + permission check), the reference module, and the one-line check for reviewers.
+2. **Given** the graft guidance the coding agents load, **When** read, **Then** it carries the same rule (or a pointer to the canonical doc), and it survives a `graft init` / `graft build` (see Assumptions for how).
+3. **Given** a new module is added without tools, **When** a reviewer follows the checklist, **Then** the omission is caught before merge.
+
+---
+
+### Edge Cases
+
+- **A tool the agent has but the console does not show** (e.g. `query_attachment`): the panel still lists it; parity is one-directional (console ⊆ agent), never a reason to hide a tool.
+- **Two chats open for two agents**: each panel shows its own agent's list; switching agents does not leak the previous list.
+- **The agent is the Rancher admin but the person is not an owner**: the panel shows what the *agent* can do; whether the person may ask for it is a chat-level question, not the panel's. Nothing in the panel reveals secret values (auth values of MCP servers, credential keys).
+- **A tool call that the console would have confirmed** (delete, revoke, role change) arrives without a prior "yes" in the chat: the tool executes (the API cannot see the chat); the safeguard is the tool description's instruction plus the agent's reply. The plan may add a `confirm: true` argument to destructive tools so a runtime cannot call them by accident.
+- **A file upload capability** (source file, template file upload, template zip install): the agent has no file picker. The tool accepts content it can already produce (text, a URL, a path inside its own workspace); binary upload from the person's machine stays a console action and the panel says so.
+- **Prompt template placeholders**: shown as «…» in the composer; sending with a placeholder left in is allowed (the agent will ask), but the composer highlights the remaining placeholder.
+- **A topic with one tool**: still an accordion, for consistency; no special case.
+- **Runtime pods that never reload their tool list** and an operator who never restarts: the "after restart" marker stays until the pod restarts; it does not time out.
+- **The tool list endpoint is called by a share-page visitor or a non-admin**: refused; the panel only exists in the admin console.
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+
+**Parity (API)**
+
+- **FR-001**: Every action listed in the Gap column of the audit MUST be available as an agent tool by the end of this feature; the audit table in this document is the acceptance checklist.
+- **FR-002**: A tool MUST apply the same authorization the console applies to that action: operator-only actions are listed only for operator-role callers and refuse others with a message naming who may perform them; agent-self actions are listed only for agent runtimes.
+- **FR-003**: Tools that remove or revoke (agents, templates, skills, credentials, MCP servers, knowledge bases, sources, users, API keys, share links, peers, files) MUST carry, in their description, the instruction to confirm with the person first, and MUST require an explicit confirmation argument so an accidental call cannot delete.
+- **FR-004**: No tool result, error, or listing MUST contain a secret value (LLM keys, MCP bearer tokens, integration secrets, agent secret values); listings show names and metadata only, and set-operations acknowledge without echoing the value.
+- **FR-005**: Each tool MUST declare a **topic** (the accordion it belongs to), a **human title**, a **description** written for a person reading the panel, and a **prompt template** with «…» placeholders; the system MUST reject registering a tool without these at startup, so the rule in Story 3 is enforced, not advised.
+- **FR-006**: The tool for reading settings MUST tell the agent which groups and keys exist and what each means, so the agent does not have to guess names to change a setting.
+- **FR-007**: Every new tool MUST have tests covering success, refused caller, and missing entity.
+- **FR-008**: Tools MUST reuse the same domain services the console's endpoints use, so a change to a capability reaches both surfaces at once; a tool MUST NOT reimplement a console rule.
+
+**Tool shelf (console)**
+
+- **FR-009**: The admin console MUST be able to read, for a given agent, the tool list that agent's runtime would receive: per tool its name, title, description, topic, prompt template, and whether the running pod already has it.
+- **FR-010**: Both admin chat surfaces (the Rancher page chat and the agent Chat tab) MUST show a **Tools** button beside the composer's attach button, with a tooltip.
+- **FR-011**: The Tools panel MUST group tools by topic as collapsible accordions, show title, technical name and description per tool, hide empty topics, and remember which accordions were open within the session.
+- **FR-012**: The panel MUST offer a search field that filters across all topics by title, technical name and description.
+- **FR-013**: Clicking a tool MUST insert its prompt template into the composer at the cursor, select the first placeholder, close the panel, and not send.
+- **FR-014**: Tools the running pod does not yet have MUST be visibly marked "after restart" with an explanation and a restart control that reuses the existing restart flow; the marker MUST clear once the pod restarts.
+- **FR-015**: The panel MUST handle "list unavailable" (agent stopped, request failed) with a one-line message and a retry, without disabling the composer.
+- **FR-016**: The panel MUST work at phone width and with a keyboard alone.
+- **FR-017**: The panel MUST NOT display secret values or connection credentials of any kind.
+
+**Rule (repo guidance)**
+
+- **FR-018**: `CLAUDE.md` MUST state the parity rule as part of the definition of done, name where tools live, the required metadata (topic, title, description, template, authorization, tests), a reference module, and a reviewer check.
+- **FR-019**: The graft guidance loaded by coding agents MUST carry the same rule or a pointer to the canonical document, in a form that survives `graft init` and `graft build`.
+- **FR-020**: The PR template or review checklist used in this repo MUST include the line "console capability added → agent tool added, with tests".
+
+### Key Entities
+
+- **Tool**: one action the agent can perform; has a technical name, a title, a description, a topic, a prompt template, an authorization rule (operator / agent-self / everyone), and tests. Served to runtimes by the API.
+- **Topic**: a named group of tools matching a console section (Agents, Templates, …); the accordion in the panel.
+- **Prompt template**: a short natural-language sentence with «…» placeholders that a newcomer can send to reach this tool; belongs to exactly one tool. It is a starter, not a form: it only helps a person come up with an example, the person reshapes it freely, and the agent still decides which tool to call.
+- **Agent tool list**: the set of tools a specific agent's runtime receives, after per-caller filtering, with a per-tool "present in running pod / after restart" flag.
+- **Parity audit**: the table in this spec; every console capability mapped to its tool; the checklist reviewers and future work use.
+
+## Success Criteria *(mandatory)*
+
+### Measurable Outcomes
+
+- **SC-001**: 100% of console capabilities in the audit (rows 1–22) have a corresponding agent tool; the table reads "covered" in every Gap cell at the end of the feature.
+- **SC-002**: An operator can complete each of these from the Rancher chat alone, without opening any other console page: register an MCP server and attach it to a template; add a URL source to a knowledge base and index it; create an LLM credential and health-check it; create a user and set their role; create and revoke an API key; delete a throwaway agent with confirmation.
+- **SC-003**: From opening the chat, a person can find a tool by name or description and have its template in the composer in under 10 seconds and at most 3 interactions (open, search or expand, click).
+- **SC-004**: Zero secret values appear in tool results, agent replies, or transcripts, verified by a test that scans every tool's output for the secret it was given.
+- **SC-005**: Every new tool has tests; the API test suite passes; the console typecheck passes.
+- **SC-006**: A newcomer reading `CLAUDE.md` or the graft guidance names "agent tools" as part of a module's definition of done without prompting.
+- **SC-007**: The "after restart" marker is correct in both directions: present when a tool was added after the pod started, absent after restart.
+
+## Assumptions
+
+- **Surfaces**: the Tools panel ships in the admin console only (Rancher page chat and agent Chat tab). The user console (`app`) chat and the share page are not in scope; their agents keep their tools, only the shelf is absent.
+- **Where the rule lives for graft**: graft rewrites its skill file and Cursor rule on `graft init`, so the canonical text lives in a project-owned document (`docs/agent-tools.md`), `CLAUDE.md` states the rule and links it, and the graft skill and Cursor rule get a short project-owned pointer block that is re-added if graft overwrites it. The plan may find graft supports a preserved section and use that instead.
+- **File uploads**: tools that add binary files (source files, template zip, template file upload) accept a path inside the agent's own workspace or a URL, never a browser upload; the console remains the place for uploading from a person's machine, and the panel says so in the tool description.
+- **Confirmation**: because the API cannot see the chat, "ask before deleting" is enforced by a required confirmation argument plus the description; the runtime's own judgement decides when to ask. No new chat-level confirmation UI is added.
+- **Topics** mirror console sections one-to-one; the plan may merge small sections (Users + API keys, Chats + Usage) when a topic would hold fewer than three tools.
+- **Prompt templates** are English, like the rest of the admin console (`admin/` is English-only per project rules).
+- **Existing tools** keep their names; they gain topic, title and template metadata but no behavioural change, so the runtimes' current prompts still work.
+- **Authorization vocabulary** already exists (operator-role gating, agent-self gating, per-caller listing); new tools reuse it rather than inventing another.
+- **Restart awareness** reuses the existing "MCP configuration drift" detection; a tool added to the built-in server after pod start counts as drift of that server.
+
+## Decisions (clarifications settled 2026-09-22)
+
+1. **Parity extent for sensitive areas — full.** Users, API keys, LLM credential creation with keys, storage/secrets settings and every delete/revoke/role change get tools, listed only for operator-role callers. Destructive tools require an explicit `confirm: true` argument: the description tells the agent to call only after the person said yes in the chat; a call without it does nothing and returns what would be removed and a request to confirm. Secret values travel in, never out (FR-004).
+2. **Tools panel source of truth — live per-agent list.** The console reads the list that this agent's runtime would receive: built-in tools after per-caller filtering, plus each external MCP server the agent is attached to as its own group, with the "after restart" flag per entry. A static catalogue is explicitly rejected.
+3. **Legacy tool names — unchanged.** Only seven of the fifty-nine names deviate from the verb-noun scheme (the six `browser_session_*` tools and `agent_usage`); the panel shows a human title first and the technical name in small type, so the deviation is invisible to people. Existing tools gain topic, title, description and template metadata and keep their names; no aliases, no runtime restarts forced by this feature.
+4. **Prompt templates are starters, not forms.** A template exists only to help a newcomer come up with an example message for that tool. It inserts a piece of text; the person reshapes it freely; nothing about it is binding for the person or the agent.
diff --git a/specs/016-agent-tool-parity/tasks.md b/specs/016-agent-tool-parity/tasks.md
new file mode 100644
index 00000000..b796b8ed
--- /dev/null
+++ b/specs/016-agent-tool-parity/tasks.md
@@ -0,0 +1,181 @@
+# Tasks: Agent tool parity (CLEAN-109)
+
+**Input**: Design documents from `specs/016-agent-tool-parity/` — plan.md, spec.md, research.md, data-model.md, contracts/{tool-metadata.md, agent-tools.openapi.yaml, tools.md}, quickstart.md
+
+**Tests**: Required by the spec (FR-007: every new tool has tests; FR-004: secret-leak scan). Test tasks are included and are part of each tool task, not optional.
+
+**Organization**: Foundational work first (metadata, validation, helpers), then the catalogue and Tools panel (US2) so every tool added afterwards is visible and testable from the chat, then the tools topic by topic (US1), then the rule (US3), then polish. This deviates from strict P1-first ordering on purpose (user request in the plan): US2 is small and turns US1 into something a person can verify by clicking.
+
+**Commands** (from plan.md):
+- API tests: `cd api && NODE_OPTIONS=--experimental-vm-modules npx jest <path>` — never `bun run test` (kills a running dev API).
+- Swagger + admin SDK: `cd api && bun run generate:swagger && cd ../admin && bun run build:api`.
+- Admin: `cd admin && bun test slices` and `npx nuxt typecheck` (not `bun run typecheck`; revert regenerated SDK files if it touched them).
+- Commit after each phase checkpoint with `CLEAN-109` in the subject; post a checkpoint comment on the Jira issue after phases 2, 3, each topic group of 4, 5 and 6.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: parallelizable (different files, no dependency on an unfinished task)
+- **[Story]**: US1 parity tools · US2 Tools panel · US3 the rule
+
+## Path Conventions
+
+Web app: `api/src/slices/<slice>/…` (NestJS, CleanSlice) and `admin/slices/<slice>/…` (Nuxt, CleanSlice). Specs beside the file they test (`*.spec.ts`).
+
+---
+
+## Phase 1: Setup
+
+**Purpose**: Nothing to scaffold; the branch and Jira issue exist. One check that the tree builds before touching it.
+
+- [X] T001 Confirm the API boots and the current tool set is intact: `cd api && NODE_OPTIONS=--experimental-vm-modules npx jest src/slices/mcp src/slices/agent/peer src/slices/reins/knowledge/knowledge.tool.spec.ts` is green; note the 59 tool names from `contracts/tools.md` as the baseline
+
+---
+
+## Phase 2: Foundational — metadata, validation, helpers, annotate existing tools
+
+**Purpose**: The `@Tool` contract every later task relies on. The API must boot at the end of this phase with all 59 existing tools annotated.
+
+**⚠️ CRITICAL**: No tool or panel work starts before T010 is green.
+
+- [X] T002 Add `ToolTopics` const (15 keys with `title` and `order` per contracts/tool-metadata.md) and the `ToolTopic` type in `api/src/slices/mcp/decorators/topics.ts`; export from `api/src/slices/mcp/decorators/index.ts`
+- [X] T003 Extend `ToolOptions`/`ToolMetadata` with `topic`, `title`, `template`, `destructive?` in `api/src/slices/mcp/decorators/tool.decorator.ts` (parameters default stays `z.object({})`)
+- [X] T004 Add `validateToolMetadata()` to `api/src/slices/mcp/services/mcp-registry.service.ts`, called at the end of `onApplicationBootstrap`: throws with the tool name for a missing/invalid `topic`, empty `title` (>60 chars), empty `template` (>200 chars, must contain `«` unless the JSON schema has no properties), or `destructive` without a boolean `confirm` property in `zodToJsonSchema(parameters)`
+- [X] T005 Add validation cases to `api/src/slices/mcp/services/mcp-registry.service.spec.ts`: one fake provider per missing field, one destructive-without-confirm, one valid; assert throw messages name the tool
+- [X] T006 [P] Create `api/src/slices/mcp/tooling.ts` exporting `ToolResult`, `ok`, `err`, `callerAgentId`, `callerIsOperator`, `requireOperator(req)` (ForbiddenException: "… requires the Ranch operator role. Ask the operator to do it in the console."), `requireAgent(req)`, `confirmed(args, what)` (returns `err('This will <what>. Ask the person to confirm, then call again with confirm: true.')` unless `args.confirm === true`), `stripSecrets(obj, keys)`; then make `api/src/slices/agent/peer/toolSupport.ts` re-export `ok/err/callerAgentId/callerIsOperator/ToolResult` from it (keep `withRefusalAdvice`, hints and peer helpers there)
+- [X] T007 [P] Spec for the helpers in `api/src/slices/mcp/tooling.spec.ts`: `confirmed` refuses without confirm, `requireOperator` accepts Owner and refuses Agent, `stripSecrets` removes nested keys
+- [X] T008 Annotate the 24 tools in `api/src/slices/rancher/rancher.tool.ts` with `topic/title/template` per contracts/tools.md (agents, agent_workspace, templates, skills, llm, settings, chats_usage), mark `redeploy_skill_agents` destructive with a `confirm` param + `confirmed()`, and replace `requireOwner` with `requireOperator` from `#/mcp/tooling` (keep behaviour; update `rancher.tool.spec.ts` if it exists, else add a minimal spec covering the operator refusal and the confirm refusal)
+- [X] T009 [P] Annotate the remaining existing tool files with `topic/title/template` (and `destructive` + `confirm` where contracts/tools.md marks ⚠): `api/src/slices/agent/peer/peerAdmin.tool.ts`, `peerSelf.tool.ts`, `askAgent.tool.ts` (peers); `api/src/slices/reins/knowledge/knowledge.tool.ts` (knowledge); `api/src/slices/bridle/attachment.tool.ts` (attachments); `api/src/slices/browser/browser.tool.ts` (browser; close/reset destructive); `api/src/slices/paddock/scenario/scenario.tool.ts` and `evaluation.tool.ts` (paddock; delete/abort destructive). Extend their specs for the new confirm refusals (`peerAdmin.tool.spec.ts`, `peerSelf.tool.spec.ts`; add minimal specs for browser and paddock tools if none exist)
+- [X] T010 Run `cd api && NODE_OPTIONS=--experimental-vm-modules npx jest src/slices/mcp src/slices/rancher src/slices/agent/peer src/slices/reins/knowledge src/slices/bridle/attachment.tool.spec.ts src/slices/browser src/slices/paddock` green, then boot the API once (`cd api && bun run start:dev` or the project's dev command) and confirm no validation error in the log; commit `feat(mcp): tool metadata, topics and startup validation (CLEAN-109)`
+
+**Checkpoint**: Jira comment — metadata contract in place, 59 tools annotated, API refuses unannotated tools.
+
+---
+
+## Phase 3: User Story 2 — See what the agent can do, and try it in one click (Priority: P1)
+
+**Goal**: `GET /agents/:id/tools` returns the live per-agent catalogue with `inPod` flags; the admin chat has a Tools button, sheet with accordions, search, one-click template insertion, and "after restart" markers.
+
+**Independent Test**: quickstart.md §3, §4, §5 — the endpoint returns topic groups for the Rancher agent and fewer for a plain agent; the sheet opens, filters, inserts a template with the first «…» selected, and marks a tool added after pod start.
+
+### API — snapshot and catalogue
+
+- [X] T011 [P] [US2] Create `api/src/slices/agent/toolCatalog/toolCatalog.prisma` with model `AgentToolListing { agentId @id, agent relation onDelete Cascade, toolNames Json, listedAt DateTime @default(now()) }`; add the back-relation `toolListing AgentToolListing?` to `api/src/slices/agent/agent/agent.prisma`
+- [X] T012 [P] [US2] Write `api/prisma/migrations/20260922120000_agent_tool_listing/migration.sql` (CREATE TABLE + FK + comment header like `20260914120000_agent_peer_delegation`); run `cd api && bunx prisma generate` (not `bun run test`) and confirm the client compiles
+- [X] T013 [P] [US2] Add `api/src/slices/mcp/interfaces/tool-listing-recorder.interface.ts`: `TOOL_LISTING_RECORDER` injection token and `IToolListingRecorder { record(agentId: string, toolNames: string[]): Promise<void> }`; export from `interfaces/index.ts`
+- [X] T014 [US2] Create `api/src/slices/mcp/services/tool-catalog.service.ts` with `listFor(principal: IAuthTokenPayload): Promise<IListedTool[]>` (`{ name, description, inputSchema, metadata }`) — move the per-tool resolve → `isListedForRequest` → `describeForRequest` → fallback loop out of `McpToolsHandler.registerHandlers` into it (build a request-like `{ user: principal }` for the hooks); register it as a provider in `api/src/slices/mcp/mcp.module.ts`
+- [X] T015 [US2] Refactor `api/src/slices/mcp/services/handlers/mcp-tools.handler.ts` to call `ToolCatalogService.listFor(httpRequest.user)` for `tools/list`, and after listing, when `callerAgentId(httpRequest)` is set, resolve `TOOL_LISTING_RECORDER` via `moduleRef.get(…, { strict: false })` in a try/catch and call `record(agentId, names)` without awaiting the result (log on failure); keep the `tools/call` path unchanged
+- [X] T016 [US2] Extend `api/src/slices/mcp/services/handlers/mcp-tools.handler.spec.ts`: listing still honours conditional/dynamic hooks; recorder is called with the agent id and names for an agent token and not for a person token; a throwing recorder does not break `tools/list`. Add `api/src/slices/mcp/services/tool-catalog.service.spec.ts` for `listFor` with operator vs agent principals
+- [X] T017 [US2] Create `api/src/slices/agent/toolCatalog/data/toolListing.gateway.ts` (Prisma upsert + `findByAgent`) implementing `IToolListingRecorder`, `domain/toolCatalog.types.ts` (mirror data-model.md §3), `domain/toolCatalog.service.ts` (`forAgent(agentId)`: agent → principal `{ sub: 'agent:<id>', roles: agent.isAdmin ? [Owner] : [Agent], email: '' }` matching `issueAgentServiceToken` in `api/src/slices/user/auth/domain/auth.service.ts` → `ToolCatalogService.listFor` → group by `ToolTopics` order → `inPod` per data-model.md → external groups from `AgentMcpResolver.resolveForAgent` minus built-in ids with `afterRestart` from `detectMcpConfigDrift`; never include `url`/`authValue`)
+- [X] T018 [US2] Create `api/src/slices/agent/toolCatalog/dto/agentToolCatalog.dto.ts` (Swagger-decorated per contracts/agent-tools.openapi.yaml), `toolCatalog.controller.ts` (`GET agents/:id/tools`, `@Roles(Owner, Admin)`, 404 on unknown agent, 403 for `sub` starting with `agent:`), `toolCatalog.module.ts` (provides the gateway under `TOOL_LISTING_RECORDER` and exports it; imports AgentModule, McpServerModule, McpModule pieces as needed); register the module in `api/src/app.module.ts`
+- [X] T019 [US2] Spec `api/src/slices/agent/toolCatalog/domain/toolCatalog.service.spec.ts`: `inPod` matrix (no pod → null; pod + no snapshot → false; pod + snapshot → includes), topic ordering, empty topics dropped, external group has no url/authValue, admin vs plain agent principal; controller spec for 403 on agent token
+- [X] T020 [US2] Regenerate: `cd api && bun run generate:swagger && cd ../admin && bun run build:api`; confirm `AgentsService.getAgentTools` (or the generated name) exists in `admin/slices/setup/api/data/repositories/api/`; commit `feat(api): per-agent tool catalogue endpoint and listing snapshot (CLEAN-109)`
+
+### Admin — slice, primitive, composer
+
+- [X] T021 [P] [US2] Add the accordion primitive from shadcn-vue on reka-ui in `admin/slices/setup/theme/components/ui/accordion/{Accordion,AccordionItem,AccordionTrigger,AccordionContent}.vue` + `index.ts`, styled like the existing `sheet/` files
+- [X] T022 [P] [US2] Create the slice skeleton `admin/slices/agent/toolCatalog/{nuxt.config.ts,index.d.ts}` following `admin/slices/agent/agent/` (auto-registered by `admin/registerSlices.ts`), plus `domain/toolCatalog.types.ts` (`IAgentToolCatalog`, `IAgentToolGroup`, `IAgentToolEntry`), `domain/toolCatalog.gateway.ts` (interface), `domain/toolCatalog.service.ts`
+- [X] T023 [US2] Create `admin/slices/agent/toolCatalog/data/toolCatalog.mapper.ts` (DTO → domain, defensive like `agent.mapper.ts`) and `data/toolCatalog.gateway.ts` extending `BaseGateway` and calling the generated SDK method (depends on T020, T022)
+- [X] T024 [US2] Create `admin/slices/agent/toolCatalog/stores/toolCatalog.ts` per data-model.md §4: `catalogs` by agent id, `byAgent`, `fetch` (upserts, returns the stored record), `upsert`, per-agent `ui { query, expanded }` with `setQuery`, `toggleGroup`, `setExpanded`
+- [X] T025 [P] [US2] Create pure utils `admin/slices/agent/toolCatalog/utils/insertTemplate.ts` (`insertTemplate`, `hasPlaceholder`, `firstPlaceholderRange`) and `utils/filterCatalog.ts` (`filterCatalog(catalog, query)` → groups with matching tools, match on title/name/description, case-insensitive) with specs `insertTemplate.spec.ts` and `filterCatalog.spec.ts` runnable by `bun test slices`
+- [X] T026 [US2] Create `admin/slices/agent/toolCatalog/components/toolCatalog/{Sheet.vue,Group.vue,Row.vue,Empty.vue}`: `Sheet` takes `agentId` + `open` v-model, emits `pick(template)`; renders `store.byAgent(agentId)` with `useAsyncData` only for pending/error/refresh; search `Input` bound to `store.ui[agentId].query`; accordions bound to `expanded` (all matching groups expanded while a query is set); `Row` shows title, `name` in `text-xs font-mono text-muted-foreground`, description, a `destructive` badge, and when `inPod === false` a muted "after restart" tag; `Group` header shows "after restart" with a Restart button calling `useAgentStore().restart(agentId)` (disabled while restarting) when `afterRestart`; external groups render name + description + "tools are provided by this server"; `Empty` covers no results / load error with Retry; keyboard: rows are `<button>`s; phone width: `SheetContent` `side="right"` full-width under `sm`
+- [X] T027 [US2] Change `admin/slices/bridle/components/bridle/Input.vue`: add a `Wrench` button (tooltip "Tools", `aria-label`) between the paperclip and the textarea, `toolsOpen` ref, mount `ToolCatalogSheet` with `agentId`, handle `pick` via `insertTemplate(input.value, selectionStart, template)` → set `input.value`, close the sheet, `nextTick` focus + `setSelectionRange` on the first «…»; add a `hasPlaceholder(input)` computed that adds `ring-1 ring-amber-500/50` to the textarea; do not change send behaviour
+- [X] T028 [US2] Re-fetch on restart: in `Sheet.vue` watch `useAgentStore().byId(agentId)?.status` and call `store.fetch(agentId)` when it returns to running after a restart; verify the marker clears (quickstart §4–5)
+- [X] T029 [US2] `cd admin && bun test slices && npx nuxt typecheck` clean (revert SDK files if typecheck regenerated them); walk quickstart §5 on the Rancher page and on `/agents/<id>?tab=chat`; commit `feat(admin): Tools panel in the chat composer (CLEAN-109)`
+
+**Checkpoint**: Jira comment — Tools panel live; every tool added from here on appears in it.
+
+---
+
+## Phase 4: User Story 1 — The Rancher agent can do what the console can (Priority: P1)
+
+**Goal**: The 93 new tools from contracts/tools.md, each in its slice, reusing the controller's services, gated per audience, destructive ones behind `confirm`, each with a spec (listed/not listed, happy path, not-found, confirm refusal).
+
+**Independent Test**: quickstart §2 green for every `*.tool.spec.ts`; quickstart §6 prompts succeed from the Rancher chat; a plain agent is refused operator tools.
+
+**Per-topic task shape** (applies to every task below unless it says otherwise): create the tool file with the tools named in contracts/tools.md for that topic, `isListedForRequest → callerIsOperator` for **O** tools, register the class in the slice module's `providers`, add module imports for the gateways the controller uses, write the spec beside it, run it, commit `feat(<slice>): <topic> agent tools (CLEAN-109)`, and post a Jira checkpoint after every fourth topic.
+
+- [X] T030 [P] [US1] Agents: `api/src/slices/agent/agent/agentAdmin.tool.ts` + `agentAdmin.tool.spec.ts` — `stop_agent` ⚠, `start_agent`, `delete_agent` ⚠ (`wipeS3?: boolean`), `get_agent_status`, `get_agent_env` (mask secret-looking values the way `GET :id/env` does), `list_agent_mcps` (strip `authValue`/`url`, include drift), `get_cluster_capacity`; backing `AgentDeployService`, `IAgentGateway`, `AgentStatusService`, `IPodGateway`, `AgentMcpResolver`, `detectMcpConfigDrift`; register in `agent.module.ts`
+- [X] T031 [P] [US1] Agent logs: `get_agent_logs` (tail `lines` default 100) in `api/src/slices/log/log.tool.ts` + spec, backing the same gateway `log.controller.ts` uses; register in `log.module.ts`
+- [X] T032 [P] [US1] Workspace files: `api/src/slices/agent/file/file.tool.ts` + spec — `delete_agent_file` ⚠, `sync_agent_files`, `export_agent_files` (returns the API path `/agents/<id>/files/export` and says the person downloads it from the console); backing `IFileGateway`, `SyncGuardService`, `IBridleGateway` as `file.controller.ts`; register in `file.module.ts`
+- [X] T033 [P] [US1] Secrets: `api/src/slices/agent/secret/secret.tool.ts` + spec — `list_agent_secrets` (names only), `set_agent_secret`, `delete_agent_secret` ⚠, `replace_agent_secrets` ⚠; results never contain values; backing `ISecretGateway` + `IAgentGateway`; register in `secret.module.ts`
+- [X] T034 [P] [US1] Channels + share link: `api/src/slices/agent/agentChannel/agentChannel.tool.ts` (`get_agent_channels`, `set_agent_channels`) and `api/src/slices/agent/shareLink/shareLink.tool.ts` (`get_share_link`, `create_share_link`, `regenerate_share_link` ⚠, `revoke_share_link` ⚠) + specs; backing `IAgentChannelGateway`, `ShareLinkService`; register in their modules
+- [X] T035 [P] [US1] Templates: `api/src/slices/agent/template/templateAdmin.tool.ts` + spec — `create_template`, `delete_template` ⚠, `set_template_mcps`, `restart_template_agents` ⚠; backing `ITemplateGateway`, `AgentDeployService` (as `restart-by-template`); register in `template.module.ts`
+- [X] T036 [P] [US1] Template install/export: `api/src/slices/agent/templateInstall/templateInstall.tool.ts` + spec — `preview_template_install_from_git`, `install_template_from_git`, `export_template` (download path); backing `TemplateInstallService`, `TemplateExportService`; register in `templateInstall.module.ts`
+- [X] T037 [P] [US1] Skills: `api/src/slices/skill/skill.tool.ts` + spec — `get_skill`, `create_skill`, `delete_skill` ⚠, `import_skill_from_url`, `search_skills`, `import_skill`; backing `ISkillGateway`, `GithubSearch` exactly as `skill.controller.ts`; register in `skill.module.ts`
+- [X] T038 [P] [US1] LLM credentials: `api/src/slices/llm/llm.tool.ts` + spec — `get_llm`, `create_llm`, `update_llm`, `delete_llm` ⚠, `health_check_llm`, `list_llm_models`, `llm_usage`; strip `apiKey`/key fields from every result; backing `ILlmGateway`, `ILlmHealthGateway`, the models catalogue used by `GET llms/models`, `IUsageGateway` for usage; register in `llm.module.ts` (import `UsageModule`)
+- [X] T039 [P] [US1] MCP servers: `api/src/slices/mcpServer/mcpServer.tool.ts` + spec — `list_mcp_servers`, `get_mcp_server`, `register_mcp_server`, `update_mcp_server` (built-in rows: only `enabled`/`description`, same rule as the controller), `delete_mcp_server` ⚠ (built-ins refused with the controller's message), `start_mcp_oauth` (returns the URL to open); strip `authValue`; backing `IMcpServerGateway`, `McpOauthService`; register in `mcpServer.module.ts`
+- [X] T040 [P] [US1] Knowledge bases: `api/src/slices/reins/knowledge/knowledgeAdmin.tool.ts` + spec — `list_knowledges`, `get_knowledge`, `create_knowledge`, `update_knowledge`, `delete_knowledge` ⚠, `index_knowledge`, `get_knowledge_overview`, `list_knowledge_graph_labels`, `get_knowledge_status`; backing `KnowledgeService`, `IKnowledgeConfigGateway`, `ILightragClient`, `ILlmGateway` as `knowledge.controller.ts`; register in `knowledge.module.ts` (leave `knowledge.tool.ts` untouched)
+- [X] T041 [P] [US1] Knowledge sources: `api/src/slices/reins/source/source.tool.ts` + spec — `list_knowledge_sources`, `add_knowledge_source` (kind url|text), `add_knowledge_sources_from_sitemap`, `reindex_knowledge_source`, `extract_knowledge_source`, `delete_knowledge_source` ⚠, `list_knowledge_imports`; backing `SourceService`; register in `source.module.ts`
+- [X] T042 [US1] Settings: add `api/src/slices/setting/domain/settingCatalog.ts` (`SETTING_CATALOG` compiled from `admin/slices/setting/pages/settings/*.vue` and `components/setting/nav/Menu.vue`, with `restartRequired` where the page says so), create `api/src/slices/setting/setting.tool.ts` + spec — `get_setting`, `delete_setting` ⚠ — and make `list_settings`/`upsert_setting` in `rancher.tool.ts` implement `IDynamicallyDescribedTool` appending the catalogue (group · name · meaning) to their descriptions; unknown key on `upsert_setting` still allowed but the result names the nearest catalogued key; register in `setting.module.ts`
+- [X] T043 [P] [US1] Paddock additions: `generate_paddock_scenarios` in `api/src/slices/paddock/scenario/scenario.tool.ts` (backing `IPaddockScenarioGeneratorGateway`) and `get_paddock_evaluation_logs`, `get_paddock_evaluation_scenario_result`, `get_paddock_evaluation_trace` in `api/src/slices/paddock/evaluation/evaluation.tool.ts` (backing `PaddockEvaluationService`); extend both specs
+- [X] T044 [P] [US1] Users: `api/src/slices/user/user/user.tool.ts` + spec — `list_users`, `get_user`, `create_user`, `update_user`, `set_user_role` ⚠ (Owner only, as the controller), `delete_user` ⚠; never return password hashes; backing `IUserGateway`; register in `user.module.ts`
+- [X] T045 [P] [US1] API keys: `api/src/slices/user/apiKey/apiKey.tool.ts` + spec — `list_api_keys` (prefix/metadata only), `create_api_key` (returns the key once; description says to hand it to the person verbatim and never repeat it — research R6), `revoke_api_key` ⚠; backing `IApiKeyGateway`, `ApiKeyService`; register in `apiKey.module.ts`
+- [X] T046 [P] [US1] Chats: `api/src/slices/chat/chat.tool.ts` + spec — `list_chats` (optional agent filter), `get_chat`, `get_chat_messages` (last N), `sync_chats`, `summarize_chat`, `export_chat` (download path); backing `IChatGateway`, `TranscriptReaderService`, `ChatSyncService`, `ChatInsightService`; register in `chat.module.ts`
+- [X] T047 [P] [US1] Usage: `api/src/slices/usage/usage.tool.ts` + spec — `get_usage_overview`; backing `IUsageGateway` as `GET usage/overview`; register in `usage.module.ts` (move nothing: `agent_usage` stays in `rancher.tool.ts` under `chats_usage`)
+- [X] T048 [P] [US1] Integrations: `api/src/slices/integration/integration.tool.ts` + spec — `list_integration_catalogue`, `list_integration_accounts` (secrets stripped), `create_integration_account`, `request_integration_login`, `delete_integration_account` ⚠; audience **A** with the same `userId`-must-match-caller convention as `browser.tool.ts`; backing `IntegrationService`; register in `integration.module.ts`
+- [X] T049 [P] [US1] Platform: `api/src/slices/upgrade/upgrade.tool.ts` (`get_upgrade_status`, `run_upgrade` ⚠; backing `UpgradeService`) and `get_rancher_status` added to `api/src/slices/rancher/rancher.tool.ts` (backing `RancherService`) + specs; register in `upgrade.module.ts`
+- [X] T050 [US1] Cross-cutting secrets scan `api/src/slices/mcp/tool-secrets.spec.ts`: for each secret-taking tool (`create_llm`, `update_llm`, `register_mcp_server`, `update_mcp_server`, `set_agent_secret`, `replace_agent_secrets`, `create_user`, `create_integration_account`) call it with a sentinel string through mocked gateways and assert the sentinel is absent from `content[].text`; assert `create_api_key` is the only tool whose result contains the sentinel key
+- [X] T051 [US1] Full API run `cd api && NODE_OPTIONS=--experimental-vm-modules npx jest` green; boot the API and check the log shows no metadata validation error; `GET /agents/<rancher>/tools` shows every topic from contracts/tools.md with the expected counts (quickstart §3); run quickstart §6 prompts; commit any fixes `fix(api): … (CLEAN-109)`
+
+**Checkpoint**: Jira comment — parity reached: 93 new tools, 152 total, all in the panel; secrets scan green.
+
+---
+
+## Phase 5: User Story 3 — The rule that keeps parity (Priority: P2)
+
+**Goal**: The rule is stated where people and coding agents read, survives `graft init`, and the PR template carries the check.
+
+**Independent Test**: quickstart §8; a fresh coding-agent session asked "I added a console feature, what else must I ship?" answers "agent tools with tests".
+
+- [X] T052 [P] [US3] Write `docs/agent-tools.md`: the rule, definition of done (tests + tools + topic/title/template + audience gating + confirm on destructive + no secrets out), file layout (`<slice>/<name>.tool.ts` + spec, provider in the slice module), how to pick a topic, template conventions, the reference module `api/src/slices/agent/peer/` and `contracts/tool-metadata.md` summary, how to see a tool in the panel and why "after restart" appears, the reviewer's one-line check
+- [X] T053 [P] [US3] Add an "Agent tools" section to `CLAUDE.md` after the client-state paragraph: five lines stating the rule and linking `docs/agent-tools.md`, in the same voice as the i18n and state paragraphs
+- [X] T054 [P] [US3] Create `scripts/ensure-agent-tools-rule.mjs` (idempotent: inserts the fenced `<!-- ranch:agent-tools:start/end -->` pointer block into `.claude/skills/graft/SKILL.md` and `.cursor/rules/graft.mdc` if missing) and run it; add the invocation to `make init` (or the `Makefile` target that runs after clone) and mention it in `docs/agent-tools.md`
+- [X] T055 [P] [US3] Create `.github/PULL_REQUEST_TEMPLATE.md` with the standard sections used in recent PRs (summary, ticket link, test plan) plus the checklist line "console capability added → agent tool added, with tests (docs/agent-tools.md)"
+- [X] T056 [US3] Add one paragraph to `README.md` after "Peers and A2A" pointing at the Tools panel and `docs/agent-tools.md`; commit `docs: agent tools rule, graft pointers and PR template (CLEAN-109)`
+
+**Checkpoint**: Jira comment — rule documented in CLAUDE.md, docs, graft pointers, PR template.
+
+---
+
+## Phase 6: Polish & Cross-Cutting
+
+- [X] T057 [P] Review every new tool description for the confirm sentence on ⚠ tools and for "next move" wording in refusals; fix wording inconsistencies across `api/src/slices/**/*.tool.ts`
+- [X] T058 [P] Review templates in the panel for readability (no ids, «…» placeholders only, ≤ 200 chars) by opening the sheet and reading every topic; fix in the tool files
+- [X] T059 Run `cd admin && npx nuxt typecheck` and `bun test slices`; run `cd api && NODE_OPTIONS=--experimental-vm-modules npx jest`; run `cd api && bun run lint` if defined
+- [ ] T060 (needs a running stack — left for review) Walk quickstart.md §1–§8 end to end on the local stack; record any deviation in `specs/016-agent-tool-parity/quickstart.md` notes
+- [X] T061 Open the GitHub PR into `main` (`gh pr create`) titled `feat: agent tool parity, Tools panel and the tools-per-module rule (CLEAN-109)` with the PR template filled, link it on CLEAN-109, move the issue to In Review (transition "In Testing" if that is the board's review column)
+
+---
+
+## Dependencies & Execution Order
+
+- **Phase 2 blocks everything**: T002 → T003 → T004 → T005; T006/T007 parallel with T004; T008/T009 after T003+T006; T010 gates Phase 3+.
+- **Phase 3 (US2)**: API tasks T011–T020 first (T011/T012/T013 parallel; T014 → T015 → T016; T017 after T012+T014; T018 after T017; T019 after T018; T020 last). Admin T021/T022/T025 parallel and may start during the API work; T023 needs T020+T022; T024 after T022; T026 after T021+T023+T024+T025; T027 after T025+T026; T028 after T026; T029 last.
+- **Phase 4 (US1)**: every topic task T030–T049 is independent of the others (different slices/files) and depends only on Phase 2. T042 touches `rancher.tool.ts` and T049 touches it too — run those two sequentially. T050 after all topic tasks; T051 last.
+- **Phase 5 (US3)**: independent of Phase 4 in code; ordered after it so the doc describes what exists. T052–T055 parallel; T056 last.
+- **Phase 6**: after Phases 4 and 5.
+
+## Parallel Example: Phase 4
+
+```text
+# After T010, launch up to four topic tasks at once (different slices, no shared files):
+Task: T030 agents (api/src/slices/agent/agent/agentAdmin.tool.ts)
+Task: T037 skills (api/src/slices/skill/skill.tool.ts)
+Task: T039 MCP servers (api/src/slices/mcpServer/mcpServer.tool.ts)
+Task: T040 knowledge bases (api/src/slices/reins/knowledge/knowledgeAdmin.tool.ts)
+# Then the next four, and so on; T042 and T049 not together.
+```
+
+## Implementation Strategy
+
+1. **Foundation** (Phase 2): the contract and validation; API boots with annotated tools. Commit.
+2. **Visible first** (Phase 3): the catalogue endpoint and the Tools panel. From here every new tool is verifiable by eye. Commit, Jira checkpoint.
+3. **Parity in topic batches** (Phase 4): four topics per checkpoint; each topic is one commit with its spec. The MVP for US1 is the first batch (agents, skills, MCP servers, knowledge bases), which already unlocks quickstart §6 prompts 1 and 2.
+4. **Rule** (Phase 5), then **polish and PR** (Phase 6).
+
+## Notes
+
+- Never rename an existing tool (spec Decision 3).
+- Never run `bun run test` in `api/` with a dev API running.
+- Every commit subject carries `CLEAN-109`; no push to `main`.
+- Jira comments: after T010, T029, every fourth topic in Phase 4, T051, T056, and T061 (PR link).