tachibot-mcp 2.22.0 → 2.23.0

package/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to TachiBot MCP will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.23.0] - 2026-06-11
+
+### Changed
+- **Tool registration via central scan registry** — merged the tool-standardization refactor (PR #5): all provider tools register through `src/tools/registry.ts` + `defineModelTool` factory, with golden wire-contract tests (57 tool schemas snapshot-locked) and a plop `add-tool` generator. No behavior change; the registered tool surface is byte-identical.
+- **Jury: removed the `hermes` juror** — it was a persona variant of `local` calling the same `LOCAL_LLM_MODEL` weights while claiming "You are Hermes" (a false-role prompt). Council-reviewed rationale: jury independence comes from different model weights, not different system prompts on the same backend. `hermes` is kept as a **legacy alias** of `local`; panels are deduped after alias mapping, so `jurors: "hermes,local"` now yields one local vote instead of two correlated ones. 12 jurors total.
+- Docs now describe the Hermes connection honestly (verified via grok_search against Nous docs/GitHub): the local juror runs whatever `LOCAL_LLM_MODEL` points at, e.g. a Nous Hermes build via Ollama. The Hermes *agent* is model-agnostic — it consumes 300+ backends (GPT, Claude, Gemini, self-hosted Ollama/vLLM); it is not an OpenAI-compatible endpoint to point `LOCAL_LLM_BASE_URL` at.
+
 ## [2.22.0] - 2026-06-10
 
 ### Added

package/CONTRIBUTING.md

@@ -47,6 +47,10 @@ Use the issue templates and include:
 - Open a [Discussion](https://github.com/pavveu/tachibot-mcp/discussions)
 - Create an issue
 
+## Adding a tool
+
+Run `npm run add-tool` and answer the prompts (provider, wire name, description). It scaffolds a `defineModelTool(...)` in the provider file at the `// plop:tools`/`// plop:register` anchors and a test stub. Fill in the `parameters` and `execute` TODOs. The emitted-schema golden test (`npm run test:golden`) guards the tool-name/schema wire contract.
+
 ## License
 
 By submitting code to this project, you agree that your contributions will be licensed under the AGPL-3.0 license and you grant Pawel Pawlowski the right to relicense your contributions under alternative licenses (including commercial licenses).

package/README.md

@@ -202,7 +202,7 @@ See [Installation Guide](docs/INSTALLATION_BOTH.md) for detailed instructions.
 `list_prompt_techniques` · `preview_prompt_technique` · `execute_prompt_technique`
 
 ### Local Models (1)
-`local_query` — any OpenAI-compatible local server (Ollama / LM Studio / llama.cpp / vLLM). Zero-cost, offline, private; also available as `hermes`/`local` jury jurors.
+`local_query` — any OpenAI-compatible local server (Ollama / LM Studio / llama.cpp / vLLM). Zero-cost, offline, private; also available as the `local` jury juror (`hermes` is accepted as a legacy alias). Runs whatever `LOCAL_LLM_MODEL` points at — e.g. a Nous Hermes build (`ollama pull hermes3`). Note the [Hermes agent](https://hermes-agent.nousresearch.com) itself is model-agnostic — it runs on 300+ backends (GPT, Claude, Gemini, DeepSeek, or self-hosted Ollama/vLLM) — so "Hermes" was never a guarantee of distinct weights.
 
 ### Advanced Modes (bonus)
 - **Challenger** — Critical analysis with multi-model fact-checking

package/dist/src/server.js

@@ -65,16 +65,14 @@ import { getProviderInfo } from "./tools/unified-ai-provider.js";
 import { getAllPerplexityTools, isPerplexityAvailable } from "./tools/perplexity-tools.js";
 import { getAllGrokTools, isGrokAvailable } from "./tools/grok-tools.js";
 import { registerWorkflowTools } from "./tools/workflow-runner.js";
-import { validateWorkflowTool, validateWorkflowFileTool } from "./tools/workflow-validator-tool.js";
+import { getAllTools } from "./tools/registry.js";
 import { canRunFocusDeep } from "./focus-deep.js";
 import { loadConfig } from "./config.js";
 // import { registerSessionTools } from "./session/session-tools.js"; // Removed - not needed for minimal tool set
 import { getAllAdvancedTools, areAdvancedModesAvailable } from "./tools/advanced-modes.js";
 import { isOpenAIAvailable, getAllOpenAITools } from "./tools/openai-tools.js";
-import { isGeminiAvailable, geminiBrainstormTool, geminiAnalyzeCodeTool } from "./tools/gemini-tools.js";
+import { isGeminiAvailable } from "./tools/gemini-tools.js";
 import { isOpenRouterAvailable } from "./tools/openrouter-tools.js";
-import { getTachiTools } from "./tools/tachi-tool.js";
-import { getPromptTechniqueTools } from "./tools/prompt-technique-tools.js";
 import { withParamAliases } from "./utils/param-aliases.js";
 // import { registerGPT5Tools, isGPT5Available } from "./tools/openai-gpt5-fixed.js"; // DISABLED - using regular openai-tools.ts
 import { initializeOptimizations } from "./optimization/index.js";
@@ -553,114 +551,27 @@ const availableProviders = Object.entries(providerInfo)
     .filter(([_, info]) => info.available)
     .map(([name]) => name);
 console.error(`✅ Available AI providers: ${availableProviders.join(', ')}`);
-// Register Perplexity tools separately (custom API, not OpenAI-compatible)
-if (isPerplexityAvailable()) {
-    const perplexityTools = getAllPerplexityTools();
-    perplexityTools.forEach(tool => {
-        safeAddTool(tool);
-    });
-    console.error(`✅ Registered ${perplexityTools.length} Perplexity tools (custom API)`);
-}
-// Register Grok tools separately (custom API, not OpenAI-compatible)
-if (isGrokAvailable()) {
-    const grokTools = getAllGrokTools();
-    grokTools.forEach(tool => {
-        safeAddTool(tool);
-    });
-    console.error(`✅ Registered ${grokTools.length} Grok tools (custom API)`);
-}
-// Register all OpenAI tools (includes openai_reason, openai_brainstorm, etc.)
-if (isOpenAIAvailable()) {
-    const openaiTools = getAllOpenAITools();
-    openaiTools.forEach(tool => {
-        safeAddTool(tool);
-    });
-    console.error(`✅ Registered ${openaiTools.length} OpenAI tools (GPT-5 suite)`);
-}
 // Async initialization function to handle dynamic imports and startup
 async function initializeServer() {
     try {
-        // Register select Gemini tools (brainstorm, analyze, search)
-        if (isGeminiAvailable()) {
-            const { geminiAnalyzeTextTool, geminiJudgeTool, geminiSearchTool } = await import("./tools/gemini-tools.js");
-            const geminiTools = [
-                geminiBrainstormTool, // Creative brainstorming
-                geminiAnalyzeCodeTool, // Code analysis
-                geminiAnalyzeTextTool, // Text analysis (sentiment, summary, etc.)
-                geminiJudgeTool, // Multi-perspective evaluation & synthesis
-                geminiSearchTool // Web search with Google Search grounding
-            ];
-            geminiTools.forEach(tool => {
-                safeAddTool(tool);
-            });
-            console.error(`✅ Registered ${geminiTools.length} Gemini tools (brainstorm, code, text, judge, search)`);
-            // Register Jury tool (multi-model panel with Gemini judge)
-            const { juryTool } = await import("./tools/jury-tool.js");
-            safeAddTool(juryTool);
-            console.error(`✅ Registered jury tool (multi-model panel)`);
-        }
-        // Register OpenRouter tools (Qwen, Kimi, MiniMax - filtered by profile via safeAddTool)
-        if (isOpenRouterAvailable()) {
-            const { qwenCoderTool, qwenAlgoTool, qwqReasoningTool, qwenCompetitiveTool, kimiThinkingTool, kimiCodeTool, kimiDecomposeTool, kimiLongContextTool, qwenReasonTool, minimaxCodeTool, minimaxAgentTool, deepseekReasonTool, deepseekAlgoTool, glmReasonTool, stepfunReasonTool, ernieReasonTool } = await import("./tools/openrouter-tools.js");
-            // safeAddTool checks isToolEnabled internally
-            safeAddTool(qwenCoderTool);
-            safeAddTool(qwenAlgoTool);
-            safeAddTool(qwqReasoningTool); // QwQ-32B - multi-perspective deliberation (free tier)
-            safeAddTool(qwenCompetitiveTool);
-            safeAddTool(kimiThinkingTool);
-            safeAddTool(kimiCodeTool); // SWE-focused code (Kimi K2.5 - 76.8% SWE-Bench)
-            safeAddTool(kimiDecomposeTool); // Task decomposition (Kimi K2.5 Agent Swarm)
-            safeAddTool(kimiLongContextTool); // Long-context analysis (Kimi K2.5 - 256K)
-            safeAddTool(qwenReasonTool); // Heavy reasoning (Qwen3-Max-Thinking >1T params)
-            safeAddTool(minimaxCodeTool); // MiniMax M2.7 - SWE-Pro 56.22%, #1 AI Intelligence Index
-            safeAddTool(minimaxAgentTool); // MiniMax M2.7 - agentic workflows, self-evolving
-            safeAddTool(deepseekReasonTool); // DeepSeek V4 Pro - frontier reasoning/math (open-weight)
-            safeAddTool(deepseekAlgoTool); // DeepSeek V4 Pro - algorithmic code review (top AIME/CodeElo)
-            safeAddTool(glmReasonTool); // Zhipu GLM-5.1 - agentic reasoning (SWE-Bench Pro leader)
-            safeAddTool(stepfunReasonTool); // StepFun Step 3.7 Flash - efficient reasoning
-            safeAddTool(ernieReasonTool); // Baidu ERNIE 4.5 VL - broad-knowledge reasoning
-            console.error(`✅ Registered OpenRouter tools (Qwen, QwQ, Kimi x4, MiniMax, DeepSeek x2, GLM, StepFun, ERNIE)`);
-            // Register planner tools (multi-model council for plan creation/execution)
-            const { plannerMakerTool, plannerRunnerTool, listPlansTool } = await import("./tools/planner-tools.js");
-            safeAddTool(plannerMakerTool); // Council-based plan creation
-            safeAddTool(plannerRunnerTool); // Plan execution with checkpoints
-            safeAddTool(listPlansTool); // List recent plans
-            console.error(`✅ Registered planner tools (planner_maker, planner_runner, list_plans)`);
+        // Register ALL provider tools via the central scan registry. getAllTools()
+        // evaluates the SAME is*Available() guards, in the SAME order, with the SAME
+        // async dynamic-import timing the per-provider blocks used to use inline here
+        // — so the registered set is byte-identical across every API-key scenario.
+        // This single loop replaces the former Perplexity/Grok/OpenAI sync blocks and
+        // the Gemini+jury / OpenRouter+planner / local / workflow-validator /
+        // advanced / tachi / prompt-technique async blocks. The 5 inline tools
+        // (think/focus/nextThought/usage_stats/continue_focus) are registered above
+        // and are intentionally NOT returned by the registry, so there is no overlap.
+        for (const t of await getAllTools()) {
+            safeAddTool(t);
         }
-        // Register local-model tools (Ollama / LM Studio / llama.cpp / vLLM - zero-cost,
-        // offline, no API key). Registered unconditionally; profile membership is
-        // enforced by safeAddTool/isToolEnabled.
-        const { localQueryTool } = await import("./tools/local-tools.js");
-        safeAddTool(localQueryTool);
-        console.error(`✅ Registered local-model tools (local_query)`);
-        // Register workflow tools
+        console.error(`✅ Registered provider tools via central registry`);
+        // Register workflow tools (registers directly onto FastMCP, not via
+        // safeAddTool — intentionally OUT of the registry, kept in its original spot).
         registerWorkflowTools(server);
         console.error(`✅ Registered workflow tools (execute, list, create, visualize)`);
-        // Register workflow validator tools
-        safeAddTool(validateWorkflowTool);
-        safeAddTool(validateWorkflowFileTool);
-        console.error(`✅ Registered workflow validator tools`);
         // Session management tools removed - not needed for minimal TachiBot
-        // Register advanced mode tools (Verifier, Challenger, Scout, etc.)
-        if (areAdvancedModesAvailable()) {
-            const advancedTools = getAllAdvancedTools();
-            advancedTools.forEach(tool => {
-                safeAddTool(tool);
-            });
-            console.error(`✅ Registered ${advancedTools.length} advanced mode tools`);
-        }
-        // Register tachi tools (smart auto-routing AI assistant)
-        const tachiTools = getTachiTools();
-        tachiTools.forEach(tool => {
-            safeAddTool(tool);
-        });
-        console.error(`✅ Registered tachi tools (tachi, focus alias)`);
-        // Register prompt technique tools (transparent prompt engineering)
-        const promptTechniqueTools = getPromptTechniqueTools();
-        promptTechniqueTools.forEach(tool => {
-            safeAddTool(tool);
-        });
-        console.error(`✅ Registered ${promptTechniqueTools.length} prompt technique tools`);
         // Log startup information
         const perplexityCount = isPerplexityAvailable() ? getAllPerplexityTools().length : 0;
         const grokCount = isGrokAvailable() ? getAllGrokTools().length : 0;

package/dist/src/tools/factory/base-schemas.js

@@ -0,0 +1,61 @@
+/**
+ * Shared Zod base schema partials — Task 0.3.
+ *
+ * Each export is a plain object meant to be SPREAD into a `z.object({...})`.
+ * Spreading creates a fresh `ZodObject` whose shape owns a copy of each
+ * field reference; two tools that spread the same partial do NOT alias a
+ * single mutable ZodObject — they each get an independent schema instance.
+ *
+ * SELECTION CRITERIA (grep-verified across all src/tools/*-tools.ts):
+ *   A field is factored HERE only if its FULL definition
+ *   (type + .describe() text + optionality) is **byte-identical** across
+ *   every use site (outliers with different describe text stay inline).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * filesField
+ *   30 of 31 occurrences across gemini/grok/openai/openrouter/perplexity/
+ *   planner tools share this exact definition. The one outlier
+ *   (openrouter-tools.ts line ~758) has a different describe text and stays
+ *   inline in its tool.
+ *
+ * reasoningContextField
+ *   7 occurrences across openai/openrouter/perplexity tools share this exact
+ *   definition. The remaining ~7 context fields have different describe text
+ *   (e.g. "Additional context for the problem", "Additional context about the
+ *   environment or conditions", "Additional context") and stay inline.
+ *
+ * REJECTED CANDIDATES (non-identical definitions — do NOT factor here):
+ *   temperature  — 3 defs, all differ (defaults 0.4 vs 0.7, z.coerce.number
+ *                  vs z.number, different describe text).
+ *   query        — many defs with varying describe text across tools.
+ *   problem      — varying describe text.
+ *   prompt       — varying describe text.
+ * ─────────────────────────────────────────────────────────────────────────
+ */
+import { z } from "zod";
+/**
+ * `files` — file-paths-as-code-context field.
+ *
+ * Identical across 30 tool definitions (verified by grep, Task 0.3 recon).
+ * Spread into z.object({...filesField, ...}) to include this field.
+ */
+export const filesField = {
+    files: z
+        .array(z.string())
+        .optional()
+        .describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+};
+/**
+ * `context` — additional reasoning context field.
+ *
+ * Identical across 7 tool definitions in openai/openrouter/perplexity tools
+ * (verified by grep, Task 0.3 recon). Context fields with different describe
+ * text stay inline in their respective tools.
+ * Spread into z.object({...reasoningContextField, ...}) to include this field.
+ */
+export const reasoningContextField = {
+    context: z
+        .string()
+        .optional()
+        .describe("Additional context for the reasoning task"),
+};

package/dist/src/tools/factory/define-model-tool.js

@@ -0,0 +1,37 @@
+/**
+ * PURE pass-through. Adds types + a single definition site — NO schema
+ * transformation, NO added .describe()/defaults. The emitted JSON schema MUST
+ * be unchanged. The body is exactly `return tool;` and must stay that way.
+ *
+ * IDENTITY-PRESERVING: the RETURN type is the concrete tool type `T`, not
+ * `ModelTool<S>`. Wrapping a tool is therefore type-transparent — the wrapped
+ * const keeps the *exact* concrete type it would have unwrapped (e.g.
+ * `execute`'s real `Promise<string>` return and its concrete input where
+ * `.default()` fields are still optional at the call site). Returning
+ * `ModelTool<S>` instead would widen `execute` to
+ * `(input: z.infer<S>, ctx) => Promise<unknown>` and break direct callers such
+ * as `src/tools/prompt-technique-tools.ts` that invoke `.execute(...)` outside
+ * FastMCP's parse step.
+ *
+ * Two type params are required for BOTH goals at once:
+ *   - `S` is inferred from `tool.parameters` so the shape constraint's
+ *     `execute` input is `z.infer<S>` — i.e. the tool's OWN output type, which
+ *     its concrete `execute` is assignable to (contravariantly). Constraining
+ *     to the generic `ModelTool<z.ZodObject<z.ZodRawShape>>` instead resolves
+ *     the input to `{ [x: string]: any }` (an index signature with no required
+ *     keys), to which a concrete `execute(input: { prompt: string })` is NOT
+ *     assignable — so a single `T extends ModelTool<…>` param wrongly rejects
+ *     every real tool.
+ *   - `T extends ModelTool<S>` captures and returns the concrete tool type.
+ * The `ModelTool<S>` bound still validates the shape (rejects a missing
+ * `name`/`description`/`execute` or a non-`ZodObject` `parameters`).
+ *
+ * C3: a future tool whose top-level `parameters` uses `.refine()` /
+ * `.superRefine()` / `.transform()` would produce a `ZodEffects` (not a
+ * `ZodObject`) and would require widening the `S` constraint here. No such
+ * tool exists today (grep-confirmed), so the `z.ZodObject` constraint is
+ * correct for now.
+ */
+export function defineModelTool(tool) {
+    return tool;
+}

package/dist/src/tools/gemini-tools.js

@@ -12,6 +12,8 @@ import { FORMAT_INSTRUCTION } from "../utils/format-constants.js";
 import { withHeartbeat } from "../utils/streaming-helper.js";
 import { getTimeoutConfig } from "../config/timeout-config.js";
 import { readFilesIntoContext } from "../utils/file-reader.js";
+import { defineModelTool } from "./factory/define-model-tool.js";
+import { filesField } from "./factory/base-schemas.js";
 // Note: renderOutput is applied centrally in server.ts safeAddTool() - no need to import here
 // NOTE: dotenv is loaded in server.ts before any imports
 // No need to reload here - just read from process.env
@@ -164,7 +166,7 @@ export async function callGemini(prompt, model = GEMINI_MODELS.GEMINI_3_PRO, sys
  * Gemini Query Tool
  * Direct querying of Gemini models for general information
  */
-export const geminiQueryTool = {
+export const geminiQueryTool = defineModelTool({
     name: "gemini_query",
     description: "Query Gemini. Put your PROMPT in the 'prompt' parameter.",
     parameters: z.object({
@@ -173,7 +175,7 @@ export const geminiQueryTool = {
             .optional()
             .default("gemini-3")
             .describe("Model variant - must be one of: gemini-3 (default), pro, flash"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         let model = GEMINI_MODELS.GEMINI_3_PRO; // Default to Gemini 3
@@ -189,7 +191,7 @@ export const geminiQueryTool = {
         const result = await withHeartbeat(() => callGemini(args.prompt + fileContext, model, undefined, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Brainstorm Tool
  * Collaborative problem-solving and ideation
@@ -197,14 +199,14 @@ export const geminiQueryTool = {
  * Note: skipValidation is used for internal LLM-to-LLM calls where input
  * has already been validated at the MCP entry point (server.ts).
  */
-export const geminiBrainstormTool = {
+export const geminiBrainstormTool = defineModelTool({
     name: "gemini_brainstorm",
     description: "Convergent synthesis: cluster, refine, and prioritize raw ideas into structured hierarchies. Use AFTER divergent ideation to organize and rank ideas by impact/feasibility. Put your PROMPT in the 'prompt' parameter.",
     parameters: z.object({
         prompt: z.string().describe("The ideas or topic to organize and refine (REQUIRED - put raw ideas or topic here)"),
         claudeThoughts: z.string().optional().describe("Claude's initial thoughts or raw ideas to cluster and refine"),
         maxClusters: z.number().optional().default(5).describe("Number of idea clusters to create (default: 5)"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         const systemPrompt = `Convergent synthesis engine. Output consumed by automated toolchain.
@@ -237,18 +239,18 @@ ${FORMAT_INSTRUCTION}`;
         const response = await withHeartbeat(() => callGemini(args.prompt + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(response);
     }
-};
+});
 /**
  * Gemini Analyze Code Tool
  * Code quality and performance analysis
  */
-export const geminiAnalyzeCodeTool = {
+export const geminiAnalyzeCodeTool = defineModelTool({
     name: "gemini_analyze_code",
     description: "Analyze code for bugs, quality, security, or performance issues. Put the CODE in the 'code' parameter, NOT in 'focus'.",
     parameters: z.object({
         code: z.string().describe("The actual source code to analyze (REQUIRED - put your code here)"),
         language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
         focus: z.string().optional().default("general").describe("Analysis focus (e.g., quality, security, performance, bugs, general)")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -271,17 +273,17 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(`Analyze this code:\n\n\`\`\`${args.language || ''}\n${args.code}\n\`\`\`${fileContext}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Analyze Text Tool
  * Text analysis and sentiment detection
  */
-export const geminiAnalyzeTextTool = {
+export const geminiAnalyzeTextTool = defineModelTool({
     name: "gemini_analyze_text",
     description: "Rhetorical analysis: dissect arguments for bias, logical fallacies, and persuasion tactics. Use for evaluating claims, detecting manipulation, or understanding argument structure. Put the TEXT in the 'text' parameter.",
     parameters: z.object({
         text: z.string().describe("The text to analyze (REQUIRED - put your text here)"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
         type: z.string()
             .optional()
             .default("rhetoric")
@@ -325,12 +327,12 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(`Analyze this text:\n\n${args.text}${fileContext}`, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Summarize Tool
  * Content summarization at different levels
  */
-export const geminiSummarizeTool = {
+export const geminiSummarizeTool = defineModelTool({
     name: "gemini_summarize",
     description: "Summarization. Put the CONTENT in the 'content' parameter.",
     parameters: z.object({
@@ -343,7 +345,7 @@ export const geminiSummarizeTool = {
             .optional()
             .default("paragraph")
             .describe("Output format - must be one of: paragraph, bullet-points, outline"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         const lengthGuides = {
@@ -370,12 +372,12 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(`Summarize this content:\n\n${args.content}` + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Image Prompt Tool
  * Create detailed prompts for image generation
  */
-export const geminiImagePromptTool = {
+export const geminiImagePromptTool = defineModelTool({
     name: "gemini_image_prompt",
     description: "Image prompt generation. Put the DESCRIPTION in the 'description' parameter.",
     parameters: z.object({
@@ -407,7 +409,7 @@ ${args.details ? `Additional details: ${args.details}` : ''}`;
         const result = await withHeartbeat(() => callGemini(userPrompt, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.7, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Judge Tool
  * Multi-perspective evaluation and synthesis (LLM-as-a-Judge)
@@ -417,7 +419,7 @@ ${args.details ? `Additional details: ${args.details}` : ''}`;
  * - Position bias mitigation (don't favor first/last)
  * - Extract-then-synthesize (not pick-a-winner)
  */
-export const geminiJudgeTool = {
+export const geminiJudgeTool = defineModelTool({
     name: "gemini_judge",
     description: "Evaluate and synthesize multiple AI perspectives into a unified verdict. Put CONTENT in the 'perspectives' parameter.",
     parameters: z.object({
@@ -429,7 +431,7 @@ export const geminiJudgeTool = {
             .optional()
             .default("synthesize")
             .describe("Judge mode: synthesize (merge best), evaluate (score each), rank (order by quality), resolve (settle conflicts)"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE.")
+        ...filesField
     }),
     execute: async (args, { log, reportProgress }) => {
         // Resolve perspectives from fallback params (AI clients sometimes use wrong param name)
@@ -500,13 +502,13 @@ ${FORMAT_INSTRUCTION}`;
         const result = await withHeartbeat(() => callGemini(userPrompt + fileContext, GEMINI_MODELS.GEMINI_3_PRO, systemPrompt, 0.3, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Gemini Search Tool
  * Web search using Google Search grounding
  * Uses google_search_retrieval with dynamic retrieval config
  */
-export const geminiSearchTool = {
+export const geminiSearchTool = defineModelTool({
     name: "gemini_search",
     description: "Web search via Gemini with Google Search grounding",
     parameters: z.object({
@@ -634,7 +636,7 @@ IMPORTANT:
             return `[Gemini Search error: ${error instanceof Error ? error.message : String(error)}]`;
         }
     }
-};
+});
 /**
  * Check if Gemini is available
  */

package/dist/src/tools/grok-tools.js

@@ -7,6 +7,8 @@ import { config } from "dotenv";
 import * as path from 'path';
 import { fileURLToPath } from 'url';
 import { grokSearchTool } from './grok-enhanced.js';
+import { defineModelTool } from './factory/define-model-tool.js';
+import { filesField } from './factory/base-schemas.js';
 import { validateToolInput } from "../utils/input-validator.js";
 import { getGrokApiKey, hasGrokApiKey } from "../utils/api-keys.js";
 import { stripFormatting } from "../utils/format-stripper.js";
@@ -143,7 +145,7 @@ forceVisibleOutput = true, validationContext = 'llm-orchestration', reasoningEff
  * Grok Reasoning Tool
  * Deep logical reasoning with first principles thinking
  */
-export const grokReasonTool = {
+export const grokReasonTool = defineModelTool({
     name: "grok_reason",
     description: "Deep reasoning. Put your PROBLEM or QUESTION in the 'problem' parameter.",
     parameters: z.object({
@@ -152,7 +154,7 @@ export const grokReasonTool = {
             .optional()
             .describe("Reasoning approach (e.g., analytical, creative, systematic, first-principles)"),
         context: z.string().optional().describe("Additional context for the problem"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
         useHeavy: z.boolean().optional().describe("Use expensive Grok 4 Heavy model ($3/$15) for complex tasks")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -188,12 +190,12 @@ ${FORMAT_INSTRUCTION}`
         const result = await withHeartbeat(() => callGrok(messages, model, 0.7, maxTokens, true, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Grok Code Tool
  * Code analysis, optimization, and debugging
  */
-export const grokCodeTool = {
+export const grokCodeTool = defineModelTool({
     name: "grok_code",
     description: "Code analysis. Put the CODE in the 'code' parameter, NOT in 'task'.",
     parameters: z.object({
@@ -201,7 +203,7 @@ export const grokCodeTool = {
             .describe("Code task (e.g., analyze, optimize, debug, review, refactor)"),
         code: z.string().describe("The actual source code to analyze (REQUIRED - put your code here)"),
         language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
         requirements: z.string().optional().describe("Specific requirements or focus areas")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -236,19 +238,19 @@ ${FORMAT_INSTRUCTION}`
         const result = await withHeartbeat(() => callGrok(messages, GrokModel.GROK_4_20_NON_REASONING, 0.2, 4000, true, 'code-analysis'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Grok Debug Tool
  * Specialized debugging assistance
  */
-export const grokDebugTool = {
+export const grokDebugTool = defineModelTool({
     name: "grok_debug",
     description: "Debug assistance. Describe the ISSUE in the 'issue' parameter.",
     parameters: z.object({
         issue: z.string().describe("Description of the issue or bug (REQUIRED - put your problem here)"),
         code: z.string().optional().describe("Relevant code that has the issue"),
         error: z.string().optional().describe("Error message or stack trace"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
         context: z.string().optional().describe("Additional context about the environment or conditions")
     }),
     execute: async (args, { log, reportProgress }) => {
@@ -288,12 +290,12 @@ ${FORMAT_INSTRUCTION}`
         const result = await withHeartbeat(() => callGrok(messages, GrokModel.GROK_4_20_NON_REASONING, 0.3, 3000, true, 'code-analysis'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Grok Architect Tool
  * System architecture and design
  */
-export const grokArchitectTool = {
+export const grokArchitectTool = defineModelTool({
     name: "grok_architect",
     description: "Architecture design. Put your REQUIREMENTS in the 'requirements' parameter.",
     parameters: z.object({
@@ -302,7 +304,7 @@ export const grokArchitectTool = {
         scale: z.string()
             .optional()
             .describe("Expected scale (e.g., small, medium, large, enterprise)"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
     }),
     execute: async (args, { log, reportProgress }) => {
         const { requirements, constraints, scale } = args;
@@ -329,12 +331,12 @@ ${FORMAT_INSTRUCTION}`
         const result = await withHeartbeat(() => callGrok(messages, GrokModel.GROK_4_20_MULTI_AGENT, 0.6, 4000, true, 'llm-orchestration', 'high'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Grok Brainstorm Tool
  * Creative brainstorming with Grok 4 Heavy
  */
-export const grokBrainstormTool = {
+export const grokBrainstormTool = defineModelTool({
     name: "grok_brainstorm",
     description: "Contrarian first-principles brainstorming: deconstruct a topic to atomic truths, challenge every assumption, then rebuild radical alternatives. Use when conventional thinking has stalled. Put your TOPIC in the 'topic' parameter.",
     parameters: z.object({
@@ -342,7 +344,7 @@ export const grokBrainstormTool = {
         constraints: z.string().optional().describe("Any constraints or requirements to consider"),
         numIdeas: z.number().optional().describe("Number of radical rebuilds to generate (default: 5)"),
         forceHeavy: z.boolean().optional().describe("Use expensive Grok 4 Heavy model ($3/$15) for deeper creativity"),
-        files: z.array(z.string()).optional().describe("File paths to read as code context. Supports line ranges: 'src/foo.ts:100-200'. Model sees ACTUAL CODE."),
+        ...filesField,
     }),
     execute: async (args, { log, reportProgress }) => {
         const { topic, constraints, numIdeas = 5, forceHeavy = false } = args;
@@ -383,7 +385,7 @@ ${FORMAT_INSTRUCTION}`
         const result = await withHeartbeat(() => callGrok(messages, model, 0.95, 4000, true, 'llm-orchestration'), reportFn);
         return stripFormatting(result);
     }
-};
+});
 /**
  * Check if Grok is available
  */