MCP tool reference

Call tools/list after initialization for the current JSON input schemas and tool annotations. The examples below show the arguments passed to tools/call; the tool name is sent separately.

Successful dictionary results are returned in MCP structuredContent and as a JSON text content block. Failed calls have isError: true; inspect that before consuming a result.

Tool	Purpose	Project access	Can start work
list_projects	Find accessible businesses	Account	No
check_credits	Read balance and plan	Account	No
create_project	Create a business and start research	Own account	Yes
ask_holyshift	Ask the project's agent	Ownership	Yes
get_answer	Read a conversation's progress and answer	View	No
list_experiments	Read experiment status	View	No
start_experiment	Start a plan or prepare the first	Ownership	Yes
skip_failed_step	Continue past a failed step	Ownership	Yes

list_projects

Arguments: {}

Returns projects, with own projects first and shared projects after them. Each entry includes:

Field	Description
project_id	UUID used in project tool calls
name, description	Business name and description
access	The account's access level
status	Project setup status; preparing means setup is in progress
research_status	Progress of market and competitor research
url	Link to the project in HolyShift

Use project_id, not the console URL's short identifier, in later calls.

check_credits

Arguments: {}

Returns the account's credits, debt, plan, plan_renews_at, plan_ends_at, cancels_at_period_end, expiring and more_credits.

expiring shows up to the first three credit lots considered by the account view, retaining those with an expiry date; it is not a complete ledger. Each item has credits and expires_at.

When the server counts credits without enforcing them, an additional note explains that. Do not refuse work solely because the balance is zero when that note is present.

create_project

Give exactly one of website_url and idea.

Argument	Required	Description
website_url	One of two	Website for an existing business
idea	One of two	A new business idea, at least 3 words and at most 2,000 characters
description	No	Additional context, at most 2,000 characters
role	No	founder, product, marketing, sales, consultant, other; defaults to marketing
stage	No	idea, validating, building, launched, scaling, mature; defaults to launched for a website and idea for an idea

{
  "website_url": "https://example.com",
  "role": "founder",
  "stage": "launched"
}

Returns project_id, name, status, url and next. Research starts in the background and takes a few minutes. Use list_projects to see progress before asking from that research.

ask_holyshift

Argument	Required	Description
project_id	Yes	UUID from list_projects
question	Yes	What to find out or do, 1–20,000 characters
conversation_id	No	Continue an earlier conversation; omit to start a new one

{
  "project_id": "00000000-0000-4000-8000-000000000001",
  "question": "What have we learned about our customers' objections?"
}

The UUIDs here and below are illustrative; replace them with IDs returned by the server.

Returns immediately:

{
  "conversation_id": "00000000-0000-4000-8000-000000000002",
  "status": "working",
  "url": "https://v3.holyshift.ai/c/example",
  "next": "Call get_answer with this conversation_id in about 30 seconds, and again until the status is answered. A run takes one to several minutes."
}

Asking starts an agent run, spends credits and may request project actions. It requires project ownership. The plan and credit checks run before the question is accepted.

get_answer

Arguments: project_id and conversation_id (both required UUIDs).

{
  "project_id": "00000000-0000-4000-8000-000000000001",
  "conversation_id": "00000000-0000-4000-8000-000000000002"
}

All results include conversation_id, url and status:

Status	Additional fields
working	next — poll again in about 30 seconds
answered	answer — completed response text
waiting_for_you	waiting_for, partial answer, next — the person must respond in HolyShift
failed	reason — why the run did not finish

See conversations and polling for client behavior.

list_experiments

Arguments: project_id (required UUID).

Returns up to 20 entries in experiments, newest first, and a project url. Each entry has number, status, phase and waiting_for.

waiting_for is null when no user move is reported. Otherwise it contains on and a human-readable detail:

on	Meaning
start	A drafted experiment waits for Start.
failed_step	A running experiment has a failed step.
the_person	The person must respond in HolyShift.

If no experiments exist, first_experiment gives guidance on preparation when applicable. Ask ask_holyshift for the plan, hypothesis and learnings; this tool reports status rather than experiment content.

start_experiment

Argument	Required	Description
project_id	Yes	Project UUID
experiment	No	Experiment number, integer ≥ 1

Omit experiment to start the drafted experiment waiting at its gate. If no experiments exist, omission requests preparation of the first one. Preparing it does not bypass its Start gate: list experiments after preparation, let the person review the plan and then start it.

Starting a specific experiment returns number, status, url and next. First-experiment preparation returns status, url and next.

An existing experiment must be drafted or running. Starting work requires ownership and an unlocked account. The action spends credits and can lead to real-world work over days; call it only when the person asked.

skip_failed_step

Arguments: project_id (UUID) and experiment (integer ≥ 1), both required.

Continues a running experiment past a failed step. Returns number, status, phase, left_behind, url and next.

This does not retry the step. The learning records that it did not finish. It requires ownership and an unlocked account and should only be called when the person asked to skip. Retrying is available in HolyShift.