tachibot-mcp 2.8.0 → 2.9.0

package/dist/src/config/model-constants.js

@@ -125,6 +125,7 @@ export const CURRENT_MODELS = {
         brainstorm: OPENAI_MODELS.DEFAULT, // Creative ideation (gpt-5.2 + effort=medium)
         code: OPENAI_MODELS.DEFAULT, // Code tasks (gpt-5.2 + effort=medium)
         explain: OPENAI_MODELS.DEFAULT, // Explanations (gpt-5.2 + effort=low)
+        search: OPENAI_MODELS.DEFAULT, // Web search (gpt-5.2 + web_search tool)
         // Premium option for opt-in (use sparingly - 12x more expensive)
         premium: OPENAI_MODELS.PRO, // Expert mode (gpt-5.2-pro - 88.4% GPQA, $21/$168)
     },
@@ -175,6 +176,12 @@ export const TOOL_DEFAULTS = {
         maxTokens: 1500,
         temperature: 0.7,
     },
+    openai_search: {
+        model: CURRENT_MODELS.openai.search,
+        reasoning_effort: OPENAI_REASONING.LOW,
+        maxTokens: 6000,
+        temperature: 0.3,
+    },
     // Gemini tools
     gemini_brainstorm: {
         model: CURRENT_MODELS.gemini.default,

package/dist/src/profiles/balanced.js

@@ -19,6 +19,7 @@ export const balancedProfile = {
         openai_brainstorm: true,
         openai_code_review: false,
         openai_explain: false,
+        openai_search: true,
         gemini_brainstorm: true,
         gemini_analyze_code: true,
         gemini_analyze_text: true,
@@ -36,5 +37,8 @@ export const balancedProfile = {
         workflow_status: false,
         validate_workflow: false,
         validate_workflow_file: false,
+        list_prompt_techniques: true,
+        preview_prompt_technique: true,
+        execute_prompt_technique: true,
     }
 };

package/dist/src/profiles/code_focus.js

@@ -19,6 +19,7 @@ export const codeFocusProfile = {
         openai_brainstorm: false,
         openai_code_review: true,
         openai_explain: false,
+        openai_search: false,
         gemini_brainstorm: true,
         gemini_analyze_code: true,
         gemini_analyze_text: false,
@@ -36,5 +37,8 @@ export const codeFocusProfile = {
         workflow_status: false,
         validate_workflow: true,
         validate_workflow_file: false,
+        list_prompt_techniques: true,
+        preview_prompt_technique: true,
+        execute_prompt_technique: true,
     }
 };

package/dist/src/profiles/full.js

@@ -19,6 +19,7 @@ export const fullProfile = {
         openai_brainstorm: true,
         openai_code_review: true,
         openai_explain: true,
+        openai_search: true,
         gemini_brainstorm: true,
         gemini_analyze_code: true,
         gemini_analyze_text: true,
@@ -36,5 +37,8 @@ export const fullProfile = {
         workflow_status: true,
         validate_workflow: true,
         validate_workflow_file: true,
+        list_prompt_techniques: true,
+        preview_prompt_technique: true,
+        execute_prompt_technique: true,
     }
 };

package/dist/src/profiles/heavy_coding.js

@@ -18,11 +18,12 @@ export const heavyCodingProfile = {
         grok_architect: true,
         grok_brainstorm: true,
         grok_search: true,
-        // OpenAI - reason & brainstorm only
+        // OpenAI - reason, brainstorm, search
         openai_reason: true,
         openai_brainstorm: true,
         openai_code_review: false,
         openai_explain: false,
+        openai_search: true,
         // Gemini - all enabled
         gemini_brainstorm: true,
         gemini_analyze_code: true,
@@ -43,5 +44,8 @@ export const heavyCodingProfile = {
         workflow_status: false,
         validate_workflow: false,
         validate_workflow_file: false,
+        list_prompt_techniques: true,
+        preview_prompt_technique: true,
+        execute_prompt_technique: true,
     }
 };

package/dist/src/profiles/minimal.js

@@ -19,6 +19,7 @@ export const minimalProfile = {
         openai_brainstorm: false,
         openai_code_review: false,
         openai_explain: false,
+        openai_search: false,
         gemini_brainstorm: true,
         gemini_analyze_code: false,
         gemini_analyze_text: false,
@@ -36,5 +37,8 @@ export const minimalProfile = {
         workflow_status: false,
         validate_workflow: false,
         validate_workflow_file: false,
+        list_prompt_techniques: true,
+        preview_prompt_technique: false,
+        execute_prompt_technique: false,
     }
 };

package/dist/src/profiles/research_power.js

@@ -19,6 +19,7 @@ export const researchPowerProfile = {
         openai_brainstorm: true,
         openai_code_review: false,
         openai_explain: false,
+        openai_search: true,
         gemini_brainstorm: true,
         gemini_analyze_code: false,
         gemini_analyze_text: false,
@@ -36,5 +37,8 @@ export const researchPowerProfile = {
         workflow_status: false,
         validate_workflow: false,
         validate_workflow_file: false,
+        list_prompt_techniques: true,
+        preview_prompt_technique: true,
+        execute_prompt_technique: true,
     }
 };

package/dist/src/prompt-engineer-lite.js

@@ -6,34 +6,66 @@ export class PromptEngineerLite {
             ['alt_view', (q) => `"${q}" from 5 angles: child, scientist, artist, strategist, futurist.`],
             ['creative_use', (q, c) => `Creative applications of "${q}"${c ? ' findings' : ''} across domains.`],
             ['innovate', (q) => `Generate creative, unconventional solutions for "${q}". Consider multiple approaches: rethinking existing processes, drawing inspiration from other domains, removing constraints, and combining different methods. Provide 3+ novel, practical approaches.`],
-            // Research  
+            // Research
             ['investigate', (q) => `5W1H analysis of "${q}": Who/What/When/Where/Why/How + recent developments.`],
-            ['evidence', (q, c) => `Evidence for "${q}": support, contradict, cases, stats, experts.`],
+            ['evidence', (q, _c) => `Evidence for "${q}": support, contradict, cases, stats, experts.`],
             // Analytical
-            ['analyze', (q, c) => `"${q}" systematic: components→relationships→patterns→strengths/risks→conclusions.`],
+            ['analyze', (q, _c) => `"${q}" systematic: components→relationships→patterns→strengths/risks→conclusions.`],
             ['first_prin', (q) => `"${q}" first principles: truths→assumptions→atomic units→rebuild.`],
-            ['feasible', (q, c) => `"${q}" feasibility: technical/economic/time/resources/risks/metrics.`],
+            ['feasible', (q, _c) => `"${q}" feasibility: technical/economic/time/resources/risks/metrics.`],
             // Reflective
-            ['reflect', (q, c) => `"${q}" reflection: patterns, surprises, key insight, gaps, next steps.`],
-            ['patterns', (q, c) => `"${q}" patterns: themes, causality, cycles, anomalies, system insights.`],
+            ['reflect', (q, _c) => `"${q}" reflection: patterns, surprises, key insight, gaps, next steps.`],
+            ['patterns', (q, _c) => `"${q}" patterns: themes, causality, cycles, anomalies, system insights.`],
             ['decompose', (q) => `"${q}" breakdown: core→sub-problems→dependencies→constraints→steps.`],
-            ['integrate', (q) => `"${q}" synthesis: convergent themes, complements, contradictions, meta-pattern.`]
+            ['integrate', (q) => `"${q}" synthesis: convergent themes, complements, contradictions, meta-pattern.`],
+            // Reasoning (2025-2026 patterns)
+            ['chain_of_thought', (q) => `Think step-by-step about "${q}": 1) Identify the core question, 2) Break into sub-problems, 3) Apply logical reasoning to each, 4) Synthesize conclusion.`],
+            ['tree_of_thoughts', (q) => `For "${q}": Branch into 3 distinct solution paths, explore each path's implications, evaluate pros/cons, prune weak branches, synthesize best elements.`],
+            ['graph_of_thoughts', (q) => `Map "${q}" as an idea graph: identify key concept nodes, draw connection edges (supports/contradicts/depends), find feedback loops and central hubs.`],
+            // Verification
+            ['self_consistency', (q) => `For "${q}": Generate 3 independent solutions, compare approaches, identify consensus points, vote on best answer, explain confidence level.`],
+            ['constitutional', (q) => `Solve "${q}", then critique your answer against: accuracy (is it factually correct?), safety (any risks?), helpfulness (does it address the need?). Revise based on critique.`],
+            // Meta
+            ['meta_prompting', (q) => `First, write a better prompt for "${q}" that would get a more useful response. Then, answer using that improved prompt.`],
+            // Debate
+            ['adversarial', (q) => `For "${q}": First argue strongly FOR this position with best evidence. Then argue strongly AGAINST with counterarguments. Finally, synthesize a balanced view.`],
+            ['persona_simulation', (q) => `Simulate expert debate on "${q}": Have a skeptic raise concerns, an optimist highlight benefits, a pragmatist focus on implementation, and a visionary explore possibilities. Synthesize insights.`]
         ]);
-        // Compact technique mapping
+        // Compact technique mapping (aliases to canonical names)
         this.techniqueMap = {
+            // Existing aliases
             'what_if_speculation': 'what_if',
             'alternative_perspectives': 'alt_view',
+            'perspectives': 'alt_view',
             'creative_applications': 'creative_use',
+            'applications': 'creative_use',
             'innovative_solutions': 'innovate',
+            'solutions': 'innovate',
             'comprehensive_investigation': 'investigate',
+            '5w1h': 'investigate',
             'evidence_gathering': 'evidence',
+            'facts': 'evidence',
             'systematic_analysis': 'analyze',
+            'systematic': 'analyze',
             'first_principles': 'first_prin',
             'feasibility_analysis': 'feasible',
+            'feasibility': 'feasible',
             'quick_reflection': 'reflect',
             'pattern_recognition': 'patterns',
+            'connections': 'patterns',
             'problem_decomposition': 'decompose',
-            'integration_reflection': 'integrate'
+            'breakdown': 'decompose',
+            'integration_reflection': 'integrate',
+            'synthesize': 'integrate',
+            // New technique aliases (2025-2026)
+            'step_by_step': 'chain_of_thought',
+            'explore_paths': 'tree_of_thoughts',
+            'idea_map': 'graph_of_thoughts',
+            'consensus': 'self_consistency',
+            'principles': 'constitutional',
+            'improve_prompt': 'meta_prompting',
+            'critic': 'adversarial',
+            'debate': 'persona_simulation'
         };
     }
     applyTechnique(tool, technique, query, prev) {
@@ -58,19 +90,35 @@ export class PromptEngineerLite {
     }
     getTechniqueDescription(technique) {
         const desc = {
+            // Creative
             'what_if': 'What if...',
             'alt_view': 'Multi-angle',
             'creative_use': 'Applications',
             'innovate': 'Innovation',
+            // Research
             'investigate': '5W1H',
             'evidence': 'Evidence',
+            // Analytical
             'analyze': 'Analysis',
             'first_prin': 'First principles',
             'feasible': 'Feasibility',
+            // Reflective
             'reflect': 'Reflection',
             'patterns': 'Patterns',
             'decompose': 'Breakdown',
-            'integrate': 'Synthesis'
+            'integrate': 'Synthesis',
+            // Reasoning (2025-2026)
+            'chain_of_thought': 'Step-by-step',
+            'tree_of_thoughts': 'Explore paths',
+            'graph_of_thoughts': 'Idea map',
+            // Verification
+            'self_consistency': 'Consensus',
+            'constitutional': 'Principles check',
+            // Meta
+            'meta_prompting': 'Improve prompt',
+            // Debate
+            'adversarial': 'Pro/Con',
+            'persona_simulation': 'Expert debate'
         };
         const key = this.techniqueMap[technique] || technique;
         return desc[key] || technique;

package/dist/src/server.js

@@ -72,6 +72,7 @@ import { isOpenAIAvailable, getAllOpenAITools } from "./tools/openai-tools.js";
 import { isGeminiAvailable, geminiBrainstormTool, geminiAnalyzeCodeTool } 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 { registerGPT5Tools, isGPT5Available } from "./tools/openai-gpt5-fixed.js"; // DISABLED - using regular openai-tools.ts
 import { initializeOptimizations } from "./optimization/index.js";
 import { FocusModeRegistry } from "./application/services/focus/FocusModeRegistry.js";
@@ -609,6 +610,12 @@ async function initializeServer() {
             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/advanced-modes.js

@@ -15,10 +15,10 @@ const testArchitect = new TestArchitect();
 // Auditor Tool
 export const auditorTool = {
     name: "auditor",
-    description: `Evidence-based audit`,
+    description: "Evidence-based audit. Put the CONTEXT in the 'context' parameter.",
     parameters: z.object({
-        context: z.string(),
-        evidenceRequired: z.boolean().optional()
+        context: z.string().describe("What to audit (REQUIRED - put your audit request here)"),
+        evidenceRequired: z.boolean().optional().describe("Require evidence for claims")
     }),
     execute: async (args, { log }) => {
         log.info("Starting audit");
@@ -35,13 +35,13 @@ export const auditorTool = {
 // Commit Guardian Tool
 export const commitGuardianTool = {
     name: "commit_guardian",
-    description: `Pre-commit validation`,
+    description: "Pre-commit validation. Put the CONTEXT in the 'context' parameter.",
     parameters: z.object({
-        context: z.string(),
-        strict: z.boolean().optional(),
-        checkSecurity: z.boolean().optional(),
-        checkQuality: z.boolean().optional(),
-        checkTests: z.boolean().optional()
+        context: z.string().describe("Code changes to validate (REQUIRED - put your diff/changes here)"),
+        strict: z.boolean().optional().describe("Use strict validation rules"),
+        checkSecurity: z.boolean().optional().describe("Check for security issues"),
+        checkQuality: z.boolean().optional().describe("Check code quality"),
+        checkTests: z.boolean().optional().describe("Check test coverage")
     }),
     execute: async (args, { log }) => {
         log.info("Validating commit");
@@ -62,18 +62,14 @@ export const commitGuardianTool = {
 // Architect Tool
 export const architectTool = {
     name: "architect",
-    description: `Full codebase analysis with Gemini 2.5 Pro (1M tokens) and specialized verification.
-
-Parameters:
-- query (required): What to analyze in the codebase
-- path (optional): Path to codebase
-- depth (optional, default: normal): shallow|normal|deep
-- focusAreas (optional): Specific areas to focus on`,
+    description: "Full codebase analysis. Put your QUERY in the 'query' parameter.",
     parameters: z.object({
-        query: z.string(),
-        path: z.string().optional(),
-        depth: z.enum(["shallow", "normal", "deep"]).optional(),
-        focusAreas: z.array(z.string()).optional()
+        query: z.string().describe("What to analyze in the codebase (REQUIRED - put your question here)"),
+        path: z.string().optional().describe("Path to the codebase to analyze"),
+        depth: z.enum(["shallow", "normal", "deep"])
+            .optional()
+            .describe("Analysis depth - must be one of: shallow, normal, deep"),
+        focusAreas: z.array(z.string()).optional().describe("Specific areas to focus on")
     }),
     execute: async (args, { log }) => {
         log.info("Starting architecture analysis", {
@@ -98,13 +94,17 @@ Parameters:
 // Code Reviewer Tool
 export const codeReviewerTool = {
     name: "code_reviewer",
-    description: `Code review`,
+    description: "Code review. Put the CODE in the 'code' parameter, NOT in 'focusAreas' or 'severity'.",
     parameters: z.object({
-        code: z.string(),
-        language: z.string().optional(),
-        focusAreas: z.array(z.enum(['security', 'performance', 'readability', 'bugs', 'best-practices'])).optional(),
-        severity: z.enum(['low', 'medium', 'high']).optional(),
-        model: z.string().optional()
+        code: z.string().describe("The actual source code to review (REQUIRED - put your code here)"),
+        language: z.string().optional().describe("Programming language (e.g., 'typescript', 'python')"),
+        focusAreas: z.array(z.enum(['security', 'performance', 'readability', 'bugs', 'best-practices']))
+            .optional()
+            .describe("Focus areas - array of: security, performance, readability, bugs, best-practices"),
+        severity: z.enum(['low', 'medium', 'high'])
+            .optional()
+            .describe("Minimum severity to report - must be one of: low, medium, high"),
+        model: z.string().optional().describe("Model to use for review")
     }),
     execute: async (args, { log }) => {
         log.info("Starting code review", {
@@ -128,13 +128,17 @@ export const codeReviewerTool = {
 // Documentation Writer Tool
 export const documentationWriterTool = {
     name: "documentation_writer",
-    description: `Documentation generation`,
+    description: "Documentation generation. Put the CODE in the 'code' parameter.",
     parameters: z.object({
-        code: z.string(),
-        style: z.enum(['narrative', 'technical', 'beginner-friendly', 'api-reference']).optional(),
-        includeExamples: z.boolean().optional(),
-        generateToc: z.boolean().optional(),
-        format: z.enum(['markdown', 'html', 'plain']).optional()
+        code: z.string().describe("The source code to document (REQUIRED - put your code here)"),
+        style: z.enum(['narrative', 'technical', 'beginner-friendly', 'api-reference'])
+            .optional()
+            .describe("Documentation style - must be one of: narrative, technical, beginner-friendly, api-reference"),
+        includeExamples: z.boolean().optional().describe("Include usage examples"),
+        generateToc: z.boolean().optional().describe("Generate table of contents"),
+        format: z.enum(['markdown', 'html', 'plain'])
+            .optional()
+            .describe("Output format - must be one of: markdown, html, plain")
     }),
     execute: async (args, { log }) => {
         log.info("Generating documentation", {
@@ -159,13 +163,19 @@ export const documentationWriterTool = {
 // Test Architect Tool
 export const testArchitectTool = {
     name: "test_architect",
-    description: `Test suite design`,
+    description: "Test suite design. Put the CODE in the 'code' parameter.",
     parameters: z.object({
-        code: z.string(),
-        testFramework: z.enum(['jest', 'mocha', 'vitest', 'cypress', 'playwright']).optional(),
-        testTypes: z.array(z.enum(['unit', 'integration', 'e2e', 'performance', 'security'])).optional(),
-        coverage: z.enum(['basic', 'thorough', 'comprehensive']).optional(),
-        generateMocks: z.boolean().optional()
+        code: z.string().describe("The source code to create tests for (REQUIRED - put your code here)"),
+        testFramework: z.enum(['jest', 'mocha', 'vitest', 'cypress', 'playwright'])
+            .optional()
+            .describe("Test framework - must be one of: jest, mocha, vitest, cypress, playwright"),
+        testTypes: z.array(z.enum(['unit', 'integration', 'e2e', 'performance', 'security']))
+            .optional()
+            .describe("Types of tests - array of: unit, integration, e2e, performance, security"),
+        coverage: z.enum(['basic', 'thorough', 'comprehensive'])
+            .optional()
+            .describe("Coverage level - must be one of: basic, thorough, comprehensive"),
+        generateMocks: z.boolean().optional().describe("Generate mock implementations")
     }),
     execute: async (args, { log }) => {
         log.info("Architecting test suite", {

package/dist/src/tools/claude-integration.js

@@ -342,13 +342,15 @@ export class ClaudeCodeIntegration {
 // Export the tool for MCP registration
 export const claudeIntegrationTool = {
     name: 'think',
-    description: 'Log reasoning',
+    description: 'Log reasoning. Put your THOUGHT in the thought/prompt/content parameter.',
     inputSchema: z.object({
-        thought: z.string().optional(),
-        prompt: z.string().optional(),
-        content: z.string().optional(),
-        context: z.any().optional(),
-        mode: z.enum(['analyze', 'plan', 'synthesize', 'reflect']).optional()
+        thought: z.string().optional().describe("The thought or reasoning to log (put your reasoning here)"),
+        prompt: z.string().optional().describe("Alternative: the prompt to process"),
+        content: z.string().optional().describe("Alternative: the content to process"),
+        context: z.any().optional().describe("Additional context for the reasoning"),
+        mode: z.enum(['analyze', 'plan', 'synthesize', 'reflect'])
+            .optional()
+            .describe("Reasoning mode - must be one of: analyze, plan, synthesize, reflect")
     }),
     execute: async (args, context) => {
         const integration = new ClaudeCodeIntegration();

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

@@ -155,10 +155,13 @@ export async function callGemini(prompt, model = GEMINI_MODELS.GEMINI_3_PRO, sys
  */
 export const geminiQueryTool = {
     name: "gemini_query",
-    description: "Query Gemini",
+    description: "Query Gemini. Put your PROMPT in the 'prompt' parameter.",
     parameters: z.object({
-        prompt: z.string(),
-        model: z.enum(["gemini-3", "pro", "flash"]).optional().default("gemini-3")
+        prompt: z.string().describe("Your question or request (REQUIRED - put your question here)"),
+        model: z.enum(["gemini-3", "pro", "flash"])
+            .optional()
+            .default("gemini-3")
+            .describe("Model variant - must be one of: gemini-3 (default), pro, flash")
     }),
     execute: async (args, { log }) => {
         let model = GEMINI_MODELS.GEMINI_3_PRO; // Default to Gemini 3
@@ -181,11 +184,11 @@ export const geminiQueryTool = {
  */
 export const geminiBrainstormTool = {
     name: "gemini_brainstorm",
-    description: "Brainstorming",
+    description: "Brainstorming. Put your PROMPT in the 'prompt' parameter.",
     parameters: z.object({
-        prompt: z.string(),
-        claudeThoughts: z.string().optional(),
-        maxRounds: z.number().optional().default(1)
+        prompt: z.string().describe("The topic or problem to brainstorm about (REQUIRED - put your topic here)"),
+        claudeThoughts: z.string().optional().describe("Claude's initial thoughts to build upon"),
+        maxRounds: z.number().optional().default(1).describe("Number of brainstorming rounds (default: 1)")
     }),
     execute: async (args, { log }) => {
         const systemPrompt = `Creative brainstorming partner.
@@ -205,11 +208,11 @@ ${FORMAT_INSTRUCTION}`;
  */
 export const geminiAnalyzeCodeTool = {
     name: "gemini_analyze_code",
-    description: "Code analysis",
+    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(),
-        language: z.string().optional(),
-        focus: z.enum(["quality", "security", "performance", "bugs", "general"]).optional().default("general")
+        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')"),
+        focus: z.enum(["quality", "security", "performance", "bugs", "general"]).optional().default("general").describe("Analysis focus area - must be one of: quality, security, performance, bugs, general")
     }),
     execute: async (args, { log }) => {
         const focusPrompts = {
@@ -233,10 +236,13 @@ ${FORMAT_INSTRUCTION}`;
  */
 export const geminiAnalyzeTextTool = {
     name: "gemini_analyze_text",
-    description: "Text analysis",
+    description: "Text analysis. Put the TEXT in the 'text' parameter, NOT in 'type'.",
     parameters: z.object({
-        text: z.string(),
-        type: z.enum(["sentiment", "summary", "entities", "key-points", "general"]).optional().default("general")
+        text: z.string().describe("The text to analyze (REQUIRED - put your text here)"),
+        type: z.enum(["sentiment", "summary", "entities", "key-points", "general"])
+            .optional()
+            .default("general")
+            .describe("Analysis type - must be one of: sentiment, summary, entities, key-points, general")
     }),
     execute: async (args, { log }) => {
         const analysisPrompts = {
@@ -259,11 +265,17 @@ ${FORMAT_INSTRUCTION}`;
  */
 export const geminiSummarizeTool = {
     name: "gemini_summarize",
-    description: "Summarization",
+    description: "Summarization. Put the CONTENT in the 'content' parameter.",
     parameters: z.object({
-        content: z.string(),
-        length: z.enum(["brief", "moderate", "detailed"]).optional().default("moderate"),
-        format: z.enum(["paragraph", "bullet-points", "outline"]).optional().default("paragraph")
+        content: z.string().describe("The content to summarize (REQUIRED - put your text here)"),
+        length: z.enum(["brief", "moderate", "detailed"])
+            .optional()
+            .default("moderate")
+            .describe("Summary length - must be one of: brief, moderate, detailed"),
+        format: z.enum(["paragraph", "bullet-points", "outline"])
+            .optional()
+            .default("paragraph")
+            .describe("Output format - must be one of: paragraph, bullet-points, outline")
     }),
     execute: async (args, { log }) => {
         const lengthGuides = {
@@ -295,12 +307,12 @@ ${FORMAT_INSTRUCTION}`;
  */
 export const geminiImagePromptTool = {
     name: "gemini_image_prompt",
-    description: "Image prompt generation",
+    description: "Image prompt generation. Put the DESCRIPTION in the 'description' parameter.",
     parameters: z.object({
-        description: z.string(),
-        style: z.string().optional(),
-        mood: z.string().optional(),
-        details: z.string().optional()
+        description: z.string().describe("What you want in the image (REQUIRED - describe the image)"),
+        style: z.string().optional().describe("Artistic style (e.g., 'watercolor', 'photorealistic')"),
+        mood: z.string().optional().describe("Mood or atmosphere (e.g., 'serene', 'dramatic')"),
+        details: z.string().optional().describe("Additional details to include")
     }),
     execute: async (args, { log }) => {
         const systemPrompt = `You are an expert at creating detailed image generation prompts.

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

@@ -122,12 +122,14 @@ forceVisibleOutput = true, validationContext = 'llm-orchestration') {
  */
 export const grokReasonTool = {
     name: "grok_reason",
-    description: "Deep reasoning",
+    description: "Deep reasoning. Put your PROBLEM or QUESTION in the 'problem' parameter.",
     parameters: z.object({
-        problem: z.string(),
-        approach: z.enum(["analytical", "creative", "systematic", "first-principles"]).optional(),
-        context: z.string().optional(),
-        useHeavy: z.boolean().optional()
+        problem: z.string().describe("The problem or question to reason about (REQUIRED - put your question here)"),
+        approach: z.enum(["analytical", "creative", "systematic", "first-principles"])
+            .optional()
+            .describe("Reasoning approach - must be one of: analytical, creative, systematic, first-principles"),
+        context: z.string().optional().describe("Additional context for the problem"),
+        useHeavy: z.boolean().optional().describe("Use expensive Grok 4 Heavy model ($3/$15) for complex tasks")
     }),
     execute: async (args, { log }) => {
         const { problem, approach = "first-principles", context, useHeavy } = args;
@@ -164,12 +166,13 @@ ${FORMAT_INSTRUCTION}`
  */
 export const grokCodeTool = {
     name: "grok_code",
-    description: "Code analysis",
+    description: "Code analysis. Put the CODE in the 'code' parameter, NOT in 'task'.",
     parameters: z.object({
-        task: z.enum(["analyze", "optimize", "debug", "review", "refactor"]),
-        code: z.string(),
-        language: z.string().optional(),
-        requirements: z.string().optional()
+        task: z.enum(["analyze", "optimize", "debug", "review", "refactor"])
+            .describe("Code task - must be one of: 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')"),
+        requirements: z.string().optional().describe("Specific requirements or focus areas")
     }),
     execute: async (args, { log }) => {
         const { task, code, language, requirements } = args;
@@ -205,12 +208,12 @@ ${FORMAT_INSTRUCTION}`
  */
 export const grokDebugTool = {
     name: "grok_debug",
-    description: "Debug assistance",
+    description: "Debug assistance. Describe the ISSUE in the 'issue' parameter.",
     parameters: z.object({
-        issue: z.string(),
-        code: z.string().optional(),
-        error: z.string().optional(),
-        context: z.string().optional()
+        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"),
+        context: z.string().optional().describe("Additional context about the environment or conditions")
     }),
     execute: async (args, { log }) => {
         const { issue, code, error, context } = args;
@@ -251,11 +254,13 @@ ${FORMAT_INSTRUCTION}`
  */
 export const grokArchitectTool = {
     name: "grok_architect",
-    description: "Architecture design",
+    description: "Architecture design. Put your REQUIREMENTS in the 'requirements' parameter.",
     parameters: z.object({
-        requirements: z.string(),
-        constraints: z.string().optional(),
-        scale: z.enum(["small", "medium", "large", "enterprise"]).optional()
+        requirements: z.string().describe("The architecture requirements or design question (REQUIRED - put your question here)"),
+        constraints: z.string().optional().describe("Technical or business constraints to consider"),
+        scale: z.enum(["small", "medium", "large", "enterprise"])
+            .optional()
+            .describe("Expected scale - must be one of: small, medium, large, enterprise")
     }),
     execute: async (args, { log }) => {
         const { requirements, constraints, scale } = args;
@@ -284,12 +289,12 @@ ${FORMAT_INSTRUCTION}`
  */
 export const grokBrainstormTool = {
     name: "grok_brainstorm",
-    description: "Creative brainstorming",
+    description: "Creative brainstorming. Put your TOPIC in the 'topic' parameter.",
     parameters: z.object({
-        topic: z.string(),
-        constraints: z.string().optional(),
-        numIdeas: z.number().optional(),
-        forceHeavy: z.boolean().optional()
+        topic: z.string().describe("The topic to brainstorm about (REQUIRED - put your idea/topic here)"),
+        constraints: z.string().optional().describe("Any constraints or requirements to consider"),
+        numIdeas: z.number().optional().describe("Number of ideas to generate (default: 5)"),
+        forceHeavy: z.boolean().optional().describe("Use expensive Grok 4 Heavy model ($3/$15) for deeper creativity")
     }),
     execute: async (args, { log }) => {
         const { topic, constraints, numIdeas = 5, forceHeavy = false } = args; // Changed: Default to cheap model