HUMMBL MCP Server

Start Guided Workflow

start_workflow

Begin a guided multi-turn workflow to systematically solve problems using validated mental models for root cause analysis, strategy design, or decision making.

Instructions

Begin a guided multi-turn workflow for systematic problem-solving using Base120 mental models.

Input Schema

TableJSON Schema

Name	Required	Description
`workflow_name`	Yes	Which workflow to start
`problem_description`	Yes	Brief description of your problem or goal
`session_id`	No	Optional session ID for state persistence

Output Schema

TableJSON Schema

Name	Required	Description	Default
`workflow`	Yes
`displayName`	Yes
`problemDescription`	Yes
`currentStep`	Yes
`totalSteps`	Yes
`transformation`	Yes
`guidance`	Yes
`suggestedModels`	Yes
`questions`	Yes
`nextAction`	Yes

Implementation Reference

src/tools/workflows.ts:70-158 (handler)

The 'start_workflow' tool handler implementation. It uses getWorkflowTemplate to fetch the template, initializes a WorkflowState, returns the first step's transformation, guidance, suggested models, and questions as structured content.

// Tool: Start a workflow
server.registerTool(
  "start_workflow",
  {
    title: "Start Guided Workflow",
    description:
      "Begin a guided multi-turn workflow for systematic problem-solving using Base120 mental models.",
    inputSchema: z.object({
      workflow_name: z
        .enum(["root_cause_analysis", "strategy_design", "decision_making"])
        .describe("Which workflow to start"),
      problem_description: z
        .string()
        .min(10)
        .describe("Brief description of your problem or goal"),
      session_id: z
        .string()
        .uuid()
        .optional()
        .describe("Optional session ID for state persistence"),
    }),
    outputSchema: z.object({
      workflow: z.string(),
      displayName: z.string(),
      problemDescription: z.string(),
      currentStep: z.number(),
      totalSteps: z.number(),
      transformation: z.string(),
      guidance: z.string(),
      suggestedModels: z.array(z.string()),
      questions: z.array(z.string()),
      nextAction: z.string(),
    }),
  },
  async ({ workflow_name, problem_description, session_id }) => {
    const template = getWorkflowTemplate(workflow_name);

    if (!template) {
      return {
        content: [
          {
            type: "text",
            text: `Workflow '${workflow_name}' not found. Valid workflows: root_cause_analysis, strategy_design, decision_making`,
          },
        ],
        isError: true,
      } as const;
    }

    // Initialize workflow state
    const workflowState: WorkflowState = {
      workflowName: workflow_name as WorkflowType,
      currentStep: 1,
      totalSteps: template.steps.length,
      startedAt: new Date().toISOString(),
      lastUpdatedAt: new Date().toISOString(),
      completed: false,
      stepResults: {},
    };

    // Get first step
    const firstStep = template.steps[0];

    const payload = {
      workflow: template.name,
      displayName: template.displayName,
      problemDescription: problem_description,
      currentStep: 1,
      totalSteps: template.steps.length,
      transformation: firstStep.transformation,
      guidance: firstStep.guidance,
      suggestedModels: firstStep.models,
      questions: firstStep.questions,
      nextAction: `Apply these ${firstStep.models.length} models from the ${firstStep.transformation} transformation and share your insights. Use 'continue_workflow' when ready to proceed.`,
      sessionId: session_id || "stateless",
      workflowState,
    };

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(payload, null, 2),
        },
      ],
      structuredContent: payload,
    } as const;
  }
);

src/tools/workflows.ts:71-103 (schema)

Input and output Zod schemas for start_workflow. Input requires workflow_name (enum: root_cause_analysis, strategy_design, decision_making), problem_description (min 10 chars), and optional session_id (uuid). Output includes workflow, displayName, currentStep, totalSteps, transformation, guidance, suggestedModels, questions, nextAction, and workflowState.

server.registerTool(
  "start_workflow",
  {
    title: "Start Guided Workflow",
    description:
      "Begin a guided multi-turn workflow for systematic problem-solving using Base120 mental models.",
    inputSchema: z.object({
      workflow_name: z
        .enum(["root_cause_analysis", "strategy_design", "decision_making"])
        .describe("Which workflow to start"),
      problem_description: z
        .string()
        .min(10)
        .describe("Brief description of your problem or goal"),
      session_id: z
        .string()
        .uuid()
        .optional()
        .describe("Optional session ID for state persistence"),
    }),
    outputSchema: z.object({
      workflow: z.string(),
      displayName: z.string(),
      problemDescription: z.string(),
      currentStep: z.number(),
      totalSteps: z.number(),
      transformation: z.string(),
      guidance: z.string(),
      suggestedModels: z.array(z.string()),
      questions: z.array(z.string()),
      nextAction: z.string(),
    }),
  },

src/tools/workflows.ts:20-332 (registration)

The registerWorkflowTools function is called from src/server.ts line 28 to register all workflow tools including start_workflow with the MCP server.

export function registerWorkflowTools(server: McpServer): void {
  // Tool: List available workflows
  server.registerTool(
    "list_workflows",
    {
      title: "List Available Workflows",
      description:
        "Get all available guided workflows for problem-solving with Base120 mental models.",
      inputSchema: z.object({}),
      outputSchema: z.object({
        count: z.number(),
        workflows: z.array(
          z.object({
            name: z.string(),
            displayName: z.string(),
            description: z.string(),
            problemTypes: z.array(z.string()),
            stepCount: z.number(),
            estimatedDuration: z.string(),
          })
        ),
      }),
    },
    async () => {
      const workflows = listWorkflows();

      const payload = {
        count: workflows.length,
        workflows: workflows.map((wf) => ({
          name: wf.name,
          displayName: wf.displayName,
          description: wf.description,
          problemTypes: wf.problemTypes,
          stepCount: wf.steps.length,
          estimatedDuration: wf.estimatedDuration,
        })),
      };

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(payload, null, 2),
          },
        ],
        structuredContent: payload,
      } as const;
    }
  );

  // Tool: Start a workflow
  server.registerTool(
    "start_workflow",
    {
      title: "Start Guided Workflow",
      description:
        "Begin a guided multi-turn workflow for systematic problem-solving using Base120 mental models.",
      inputSchema: z.object({
        workflow_name: z
          .enum(["root_cause_analysis", "strategy_design", "decision_making"])
          .describe("Which workflow to start"),
        problem_description: z
          .string()
          .min(10)
          .describe("Brief description of your problem or goal"),
        session_id: z
          .string()
          .uuid()
          .optional()
          .describe("Optional session ID for state persistence"),
      }),
      outputSchema: z.object({
        workflow: z.string(),
        displayName: z.string(),
        problemDescription: z.string(),
        currentStep: z.number(),
        totalSteps: z.number(),
        transformation: z.string(),
        guidance: z.string(),
        suggestedModels: z.array(z.string()),
        questions: z.array(z.string()),
        nextAction: z.string(),
      }),
    },
    async ({ workflow_name, problem_description, session_id }) => {
      const template = getWorkflowTemplate(workflow_name);

      if (!template) {
        return {
          content: [
            {
              type: "text",
              text: `Workflow '${workflow_name}' not found. Valid workflows: root_cause_analysis, strategy_design, decision_making`,
            },
          ],
          isError: true,
        } as const;
      }

      // Initialize workflow state
      const workflowState: WorkflowState = {
        workflowName: workflow_name as WorkflowType,
        currentStep: 1,
        totalSteps: template.steps.length,
        startedAt: new Date().toISOString(),
        lastUpdatedAt: new Date().toISOString(),
        completed: false,
        stepResults: {},
      };

      // Get first step
      const firstStep = template.steps[0];

      const payload = {
        workflow: template.name,
        displayName: template.displayName,
        problemDescription: problem_description,
        currentStep: 1,
        totalSteps: template.steps.length,
        transformation: firstStep.transformation,
        guidance: firstStep.guidance,
        suggestedModels: firstStep.models,
        questions: firstStep.questions,
        nextAction: `Apply these ${firstStep.models.length} models from the ${firstStep.transformation} transformation and share your insights. Use 'continue_workflow' when ready to proceed.`,
        sessionId: session_id || "stateless",
        workflowState,
      };

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(payload, null, 2),
          },
        ],
        structuredContent: payload,
      } as const;
    }
  );

  // Tool: Continue workflow to next step
  server.registerTool(
    "continue_workflow",
    {
      title: "Continue Workflow",
      description:
        "Proceed to the next step of your guided workflow after completing the current step.",
      inputSchema: z.object({
        workflow_name: z
          .enum(["root_cause_analysis", "strategy_design", "decision_making"])
          .describe("Which workflow you're working on"),
        current_step: z.number().int().min(1).describe("Current step number"),
        step_insights: z
          .string()
          .min(10)
          .describe("Your insights or outputs from completing the current step"),
        session_id: z.string().uuid().optional().describe("Session ID if using state persistence"),
      }),
      outputSchema: z.object({
        workflow: z.string(),
        displayName: z.string(),
        currentStep: z.number(),
        totalSteps: z.number(),
        transformation: z.string(),
        guidance: z.string(),
        suggestedModels: z.array(z.string()),
        questions: z.array(z.string()),
        nextAction: z.string(),
        completed: z.boolean(),
      }),
    },
    async ({ workflow_name, current_step, step_insights, session_id }) => {
      const template = getWorkflowTemplate(workflow_name);

      if (!template) {
        return {
          content: [
            {
              type: "text",
              text: `Workflow '${workflow_name}' not found.`,
            },
          ],
          isError: true,
        } as const;
      }

      // Calculate next step
      const nextStepNumber = current_step + 1;
      const isCompleted = nextStepNumber > template.steps.length;

      if (isCompleted) {
        // Workflow completed
        const payload = {
          workflow: template.name,
          displayName: template.displayName,
          currentStep: template.steps.length,
          totalSteps: template.steps.length,
          transformation: "COMPLETE",
          guidance:
            "Workflow completed! Review your insights from all steps to synthesize your solution.",
          suggestedModels: [],
          questions: [
            "What are the key insights across all steps?",
            "What's your final conclusion or recommendation?",
            "What actions will you take based on this analysis?",
          ],
          nextAction: "Synthesize insights and determine next actions. Workflow complete.",
          completed: true,
          sessionId: session_id || "stateless",
        };

        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(payload, null, 2),
            },
          ],
          structuredContent: payload,
        } as const;
      }

      // Get next step
      const nextStep = template.steps[nextStepNumber - 1];

      const payload = {
        workflow: template.name,
        displayName: template.displayName,
        previousStepInsights: step_insights,
        currentStep: nextStepNumber,
        totalSteps: template.steps.length,
        transformation: nextStep.transformation,
        guidance: nextStep.guidance,
        suggestedModels: nextStep.models,
        questions: nextStep.questions,
        nextAction: `Apply these ${nextStep.models.length} models from the ${nextStep.transformation} transformation. When ready, use 'continue_workflow' to proceed.`,
        completed: false,
        sessionId: session_id || "stateless",
      };

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(payload, null, 2),
          },
        ],
        structuredContent: payload,
      } as const;
    }
  );

  // Tool: Find workflows by problem type
  server.registerTool(
    "find_workflow_for_problem",
    {
      title: "Find Workflow for Problem",
      description: "Discover which workflow best fits your problem type or situation.",
      inputSchema: z.object({
        problem_keywords: z
          .string()
          .min(3)
          .describe("Keywords describing your problem (e.g., 'failure', 'strategy', 'decision')"),
      }),
      outputSchema: z.object({
        query: z.string(),
        matchCount: z.number(),
        recommendations: z.array(
          z.object({
            workflow: z.string(),
            displayName: z.string(),
            description: z.string(),
            matchedProblemTypes: z.array(z.string()),
            estimatedDuration: z.string(),
          })
        ),
      }),
    },
    async ({ problem_keywords }) => {
      const matches = findWorkflowsByProblem(problem_keywords);

      const recommendations = matches.map((wf) => {
        const matchedTypes = wf.problemTypes.filter((pt) =>
          pt.toLowerCase().includes(problem_keywords.toLowerCase())
        );

        return {
          workflow: wf.name,
          displayName: wf.displayName,
          description: wf.description,
          matchedProblemTypes: matchedTypes.length > 0 ? matchedTypes : wf.problemTypes.slice(0, 2),
          estimatedDuration: wf.estimatedDuration,
        };
      });

      const payload = {
        query: problem_keywords,
        matchCount: recommendations.length,
        recommendations,
      };

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(payload, null, 2),
          },
        ],
        structuredContent: payload,
      } as const;
    }
  );
}

src/framework/workflows.ts:267-269 (helper)
The getWorkflowTemplate helper function used by start_workflow to look up a workflow template by name from the WORKFLOW_TEMPLATES record.
```
export function getWorkflowTemplate(name: string): WorkflowTemplate | null {
  return WORKFLOW_TEMPLATES[name] || null;
}
```

src/types/domain.ts:187-215 (helper)

Type definitions for WorkflowType, WorkflowStep, WorkflowTemplate, and WorkflowState used by the start_workflow tool.

export type WorkflowType = "root_cause_analysis" | "strategy_design" | "decision_making";

export interface WorkflowStep {
  stepNumber: number;
  transformation: TransformationType;
  models: string[]; // Model codes to apply
  guidance: string; // What to do in this step
  questions: string[]; // Prompts to guide thinking
  expectedOutput: string; // What should result from this step
}

export interface WorkflowTemplate {
  name: WorkflowType;
  displayName: string;
  description: string;
  problemTypes: string[]; // When to use this workflow
  steps: WorkflowStep[];
  estimatedDuration: string; // e.g., "15-30 minutes"
}

export interface WorkflowState {
  workflowName: WorkflowType;
  currentStep: number;
  totalSteps: number;
  startedAt: string;
  lastUpdatedAt: string;
  completed: boolean;
  stepResults: Record<number, string>; // User's insights from each step
}

Tool Definition Quality

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It mentions 'multi-turn' but fails to explain that the tool returns a session_id for continuation, the expected follow-up calls, or any side effects. A guided workflow initiation requires more behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is front-loaded with the key action and purpose. No unnecessary words, making it concise and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a guided multi-turn workflow, the description is incomplete. It does not explain the return value (despite an output schema existing), how to continue the workflow, or what to expect after starting. The presence of sibling tools like continue_workflow implies a sequence, but the description does not connect them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds no additional meaning to the parameters beyond what the schema provides, such as elaborating on the enum values or the format of problem_description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Begin', the resource 'workflow', and specifies it is a guided multi-turn process using Base120 mental models. It distinguishes from sibling tools like continue_workflow and list_workflows.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for starting a workflow but does not explicitly state when to use versus alternatives like continue_workflow or list_workflows. No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hummbl-dev/mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server