`run_agent`

WRITE

Run an AI agent on a project. Automatically resolves dependencies and shows cost breakdown.

The run_agent tool queues an AI agent to run on a project. It is the primary way to trigger startup analyses on CoFounder.im.

Dependency resolution: Many agents depend on earlier agents completing first. For example, mvp_planner requires idea_validator, market_research, and business_model to be complete. If those prerequisites have not run yet, run_agent automatically queues them first. You only need to specify the agent you ultimately want.

Cost transparency: Before queueing, the tool returns a full cost breakdown listing every agent that will run and its credit cost. The total is deducted from your balance. Already-completed agents are listed as skipped and cost nothing.

Idempotency: If the requested agent is already completed, the tool returns immediately with a zero-cost response and does not requeue anything.

Supported agent types (24 total): idea_validator, problem_validation, market_research, competitor_analysis, customer_development_validator, customer_persona, business_model, go_to_market, monetization_strategy, tech_stack, mvp_planner, ui_ux_assistant, implementation_plan_generator, openclaw_builder, regulatory_compliance, team_architect, funding_advisor, investor_discovery, accelerator_recommendation, startup_program, pitch_deck_generator, report_generator, launch_submission, social_launch_assistant.

Agents run asynchronously. After calling run_agent, use get_agent_output to poll for completion. Agent processing typically takes 30 to 120 seconds depending on the type.

Parameters

Name	Type	Required	Description
`project_id`	`string`	Required	The UUID of the project to run the agent on. Example: `550e8400-e29b-41d4-a716-446655440000`
`agent_type`	`string` enum	Required	The type of agent to run. Example: `market_research`

Response Example

{
  "agents_to_run": [
    {"agent_type": "idea_validator", "title": "Idea Validator", "cost": 50, "status": "queued"},
    {"agent_type": "market_research", "title": "Market Research", "cost": 120, "status": "queued"}
  ],
  "agents_skipped": [
    {"agent_type": "problem_validation", "title": "Problem Validation", "status": "completed"}
  ],
  "total_cost": 170,
  "credits_remaining_after": 2280
}

Errors

Scenario	Error Message
agent_type value is not in the supported enum	`Error: Invalid agent type: unknown_agent`
Project does not exist or belongs to another user	`Error: Project not found`
Agent is already completed (returns success, not error)	`{"message": "Agent 'market_research' is already completed.", "agents_to_run": [], "total_cost": 0, "credits_remaining_after": 2450}`
Not enough credits to cover the full pipeline cost	`Error: Insufficient credits. Need 170, have 50. Top up your credits: - Starter Pack: 500 credits for $9.00`
One or more agents failed to enqueue	`Error: Failed to queue 1 agent(s). Please try again.`

Code Examples

curl -X POST https://mcp.cofounder.im/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "run_agent",
      "arguments": {"project_id": "550e8400-e29b-41d4-a716-446655440000", "agent_type": "market_research"}
    }
  }'

{:ok, response} =
  Req.post("https://mcp.cofounder.im/mcp",
    json: %{
      "jsonrpc" => "2.0",
      "id" => 1,
      "method" => "tools/call",
      "params" => %{
        "name" => "run_agent",
        "arguments" => %{"project_id" => "550e8400-e29b-41d4-a716-446655440000", "agent_type" => "market_research"}
      }
    },
    headers: [
      {"content-type", "application/json"},
      {"authorization", "Bearer YOUR_API_KEY"}
    ]
  )

response.body["result"]["content"]
|> hd()
|> Map.get("text")
|> IO.puts()

import requests

response = requests.post(
    "https://mcp.cofounder.im/mcp",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "run_agent",
            "arguments": {"project_id": "550e8400-e29b-41d4-a716-446655440000", "agent_type": "market_research"},
        },
    },
)
data = response.json()
print(data["result"]["content"][0]["text"])

const response = await fetch("https://mcp.cofounder.im/mcp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "run_agent",
      arguments: { project_id: "550e8400-e29b-41d4-a716-446655440000", agent_type: "market_research" },
    },
  }),
});

const data = await response.json();
console.log(data.result.content[0].text);

Try It

This sends a real request to your account.

API Token Get your token in Settings

project_id (required)

agent_type (required)

Related Tools

rerun_agent WRITE

Re-run a completed agent with optional feedback. Returns stale downstream agents.

get_agent_output READ

Get a single agent output for a project. More context-efficient than get_build_spec.

account_status READ

Get account information: credits, project count, subscription plan, and active runs.

buy_credits READ

Get links to purchase additional credits. Returns available packages with checkout URLs.