Prompts Tools — Rankahead MCP Reference

Create, manage, and execute Rankahead prompts via MCP. List runs, inspect results, and schedule recurring LLM visibility checks for your brand.

Prompts are the core unit of measurement in Rankahead. Each prompt represents a question that AI systems are likely to answer in your category — for example, “What is the best project management tool for remote teams?” The prompt tools let you create and manage prompts, schedule recurring runs, fetch run results including raw LLM outputs, and trigger on-demand checks.

---

list_prompts

Lists all prompts associated with your account, including their current status, schedule configuration, and the timestamp of their last run.

domainId · string

Optional domain ID to filter prompts to a specific tracked domain.

Request — all prompts

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_prompts",
    "arguments": {}
  },
  "id": 1
}

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_prompts",
    "arguments": {
      "domainId": "dom_01j9z3k8p4c2x"
    }
  },
  "id": 2
}

---

get_prompt

Returns full details for a single prompt, including its text, brand configuration, schedule, and active status.

promptId · string · required

The ID of the prompt to retrieve.

Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_prompt",
    "arguments": {
      "promptId": "prm_02kxw9a1m7d3y"
    }
  },
  "id": 3
}

---

list_runs

Lists execution runs for a given prompt, sorted most recent first. Each run represents one round of querying across all configured LLM providers.

promptId · string · required

The ID of the prompt whose runs you want to list.

limit · number · default: "20"

Maximum number of runs to return. Accepted range: 1–100.

offset · number · default: "0"

Number of runs to skip for pagination.

Request — first page

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_runs",
    "arguments": {
      "promptId": "prm_02kxw9a1m7d3y",
      "limit": 20,
      "offset": 0
    }
  },
  "id": 4
}

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_runs",
    "arguments": {
      "promptId": "prm_02kxw9a1m7d3y",
      "limit": 20,
      "offset": 20
    }
  },
  "id": 5
}

---

get_run

Returns full details for a single prompt run, including raw LLM responses from each provider and brand mention analyses.

runId · string · required

The ID of the run to retrieve.

Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_run",
    "arguments": {
      "runId": "run_07hbm3r2n1vy"
    }
  },
  "id": 6
}

runId · string

Unique identifier for this run.

llmResults · object[]

Array of responses from each LLM provider, including the raw text and provider name.

brandAnalyses · object[]

Parsed brand mention analysis for each LLM result, including mention type, position, and sentiment.

completedAt · string

ISO 8601 timestamp when the run finished.

---

create_prompt

Creates a new prompt and associates it with a domain. You can optionally configure a cron schedule for recurring runs and specify a locale for geographic targeting.

domainId · string · required

The ID of the domain this prompt belongs to.

name · string · required

A short, human-readable label for the prompt (e.g. “Best CRM for startups”).

promptText · string · required

The full question text that will be sent to LLMs (e.g. “What is the best CRM software for early-stage startups?”).

brandName · string · required

The brand name to detect in LLM responses (e.g. “Acme CRM”).

brandDomain · string

Optional brand domain used to detect citations (e.g. acmecrm.com).

cronExpression · string

Optional cron expression for recurring runs (e.g. 0 9 * * 1 for every Monday at 9am UTC).

locale · string

Optional locale code for geographic targeting (e.g. en-GB).

Request — minimal

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_prompt",
    "arguments": {
      "domainId": "dom_01j9z3k8p4c2x",
      "name": "Best CRM for startups",
      "promptText": "What is the best CRM software for early-stage startups?",
      "brandName": "Acme CRM"
    }
  },
  "id": 7
}

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "create_prompt",
    "arguments": {
      "domainId": "dom_01j9z3k8p4c2x",
      "name": "Best CRM for startups",
      "promptText": "What is the best CRM software for early-stage startups?",
      "brandName": "Acme CRM",
      "brandDomain": "acmecrm.com",
      "cronExpression": "0 9 * * 1",
      "locale": "en-US"
    }
  },
  "id": 8
}

---

update_prompt

Updates one or more fields on an existing prompt. All fields except promptId are optional — only the fields you provide will be changed.

promptId · string · required

The ID of the prompt to update.

name · string

New display name for the prompt.

promptText · string

Updated question text sent to LLMs.

brandName · string

Updated brand name to detect in responses.

brandDomain · string

Updated brand domain for citation detection.

cronExpression · string

Updated cron schedule. Pass an empty string ("") to remove the existing schedule.

isActive · boolean

Set to false to pause the prompt without deleting it.

Request — pause a prompt

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "update_prompt",
    "arguments": {
      "promptId": "prm_02kxw9a1m7d3y",
      "isActive": false
    }
  },
  "id": 9
}

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "update_prompt",
    "arguments": {
      "promptId": "prm_02kxw9a1m7d3y",
      "cronExpression": ""
    }
  },
  "id": 10
}

---

delete_prompt

Soft-deletes a prompt. The prompt is removed from active scheduling and no longer appears in listings, but all historical runs and analytics data are preserved.

promptId · string · required

The ID of the prompt to delete.

This action removes the prompt from your workspace. Historical run data is retained, but you will not be able to trigger new runs for this prompt after deletion.

Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "delete_prompt",
    "arguments": {
      "promptId": "prm_02kxw9a1m7d3y"
    }
  },
  "id": 11
}

---

trigger_prompt_run

Manually triggers an immediate run for a prompt outside of its scheduled cadence. The run executes asynchronously across all configured LLM providers. Use list_runs or get_run to check the result once it completes.

promptId · string · required

The ID of the prompt to run immediately.

Request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "trigger_prompt_run",
    "arguments": {
      "promptId": "prm_02kxw9a1m7d3y"
    }
  },
  "id": 12
}

runId · string

The ID of the newly created run. Use this with get_run to retrieve results once the run completes.