> ## Documentation Index
> Fetch the complete documentation index at: https://rankahead.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="domainId" type="string">
  Optional domain ID to filter prompts to a specific tracked domain.
</ParamField>

<CodeGroup>
  ```json Request — all prompts theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_prompts",
      "arguments": {}
    },
    "id": 1
  }
  ```

  ```json Request — by domain theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_prompts",
      "arguments": {
        "domainId": "dom_01j9z3k8p4c2x"
      }
    },
    "id": 2
  }
  ```
</CodeGroup>

***

## get\_prompt

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

<ParamField path="promptId" type="string" required>
  The ID of the prompt to retrieve.
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_prompt",
      "arguments": {
        "promptId": "prm_02kxw9a1m7d3y"
      }
    },
    "id": 3
  }
  ```
</CodeGroup>

***

## 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.

<ParamField path="promptId" type="string" required>
  The ID of the prompt whose runs you want to list.
</ParamField>

<ParamField path="limit" type="number" default="20">
  Maximum number of runs to return. Accepted range: 1–100.
</ParamField>

<ParamField path="offset" type="number" default="0">
  Number of runs to skip for pagination.
</ParamField>

<CodeGroup>
  ```json Request — first page theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_runs",
      "arguments": {
        "promptId": "prm_02kxw9a1m7d3y",
        "limit": 20,
        "offset": 0
      }
    },
    "id": 4
  }
  ```

  ```json Request — second page theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_runs",
      "arguments": {
        "promptId": "prm_02kxw9a1m7d3y",
        "limit": 20,
        "offset": 20
      }
    },
    "id": 5
  }
  ```
</CodeGroup>

***

## get\_run

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

<ParamField path="runId" type="string" required>
  The ID of the run to retrieve.
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_run",
      "arguments": {
        "runId": "run_07hbm3r2n1vy"
      }
    },
    "id": 6
  }
  ```
</CodeGroup>

<ResponseField name="runId" type="string">
  Unique identifier for this run.
</ResponseField>

<ResponseField name="llmResults" type="object[]">
  Array of responses from each LLM provider, including the raw text and provider name.
</ResponseField>

<ResponseField name="brandAnalyses" type="object[]">
  Parsed brand mention analysis for each LLM result, including mention type, position, and sentiment.
</ResponseField>

<ResponseField name="completedAt" type="string">
  ISO 8601 timestamp when the run finished.
</ResponseField>

***

## 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.

<ParamField path="domainId" type="string" required>
  The ID of the domain this prompt belongs to.
</ParamField>

<ParamField path="name" type="string" required>
  A short, human-readable label for the prompt (e.g. "Best CRM for startups").
</ParamField>

<ParamField path="promptText" type="string" required>
  The full question text that will be sent to LLMs (e.g. "What is the best CRM software for early-stage startups?").
</ParamField>

<ParamField path="brandName" type="string" required>
  The brand name to detect in LLM responses (e.g. "Acme CRM").
</ParamField>

<ParamField path="brandDomain" type="string">
  Optional brand domain used to detect citations (e.g. `acmecrm.com`).
</ParamField>

<ParamField path="cronExpression" type="string">
  Optional cron expression for recurring runs (e.g. `0 9 * * 1` for every Monday at 9am UTC).
</ParamField>

<ParamField path="locale" type="string">
  Optional locale code for geographic targeting (e.g. `en-GB`).
</ParamField>

<CodeGroup>
  ```json Request — minimal theme={null}
  {
    "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
  }
  ```

  ```json Request — with schedule and locale theme={null}
  {
    "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
  }
  ```
</CodeGroup>

***

## 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.

<ParamField path="promptId" type="string" required>
  The ID of the prompt to update.
</ParamField>

<ParamField path="name" type="string">
  New display name for the prompt.
</ParamField>

<ParamField path="promptText" type="string">
  Updated question text sent to LLMs.
</ParamField>

<ParamField path="brandName" type="string">
  Updated brand name to detect in responses.
</ParamField>

<ParamField path="brandDomain" type="string">
  Updated brand domain for citation detection.
</ParamField>

<ParamField path="cronExpression" type="string">
  Updated cron schedule. Pass an empty string (`""`) to remove the existing schedule.
</ParamField>

<ParamField path="isActive" type="boolean">
  Set to `false` to pause the prompt without deleting it.
</ParamField>

<CodeGroup>
  ```json Request — pause a prompt theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "update_prompt",
      "arguments": {
        "promptId": "prm_02kxw9a1m7d3y",
        "isActive": false
      }
    },
    "id": 9
  }
  ```

  ```json Request — clear schedule theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "update_prompt",
      "arguments": {
        "promptId": "prm_02kxw9a1m7d3y",
        "cronExpression": ""
      }
    },
    "id": 10
  }
  ```
</CodeGroup>

***

## 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.

<ParamField path="promptId" type="string" required>
  The ID of the prompt to delete.
</ParamField>

<Warning>
  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.
</Warning>

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "delete_prompt",
      "arguments": {
        "promptId": "prm_02kxw9a1m7d3y"
      }
    },
    "id": 11
  }
  ```
</CodeGroup>

***

## 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.

<ParamField path="promptId" type="string" required>
  The ID of the prompt to run immediately.
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "trigger_prompt_run",
      "arguments": {
        "promptId": "prm_02kxw9a1m7d3y"
      }
    },
    "id": 12
  }
  ```
</CodeGroup>

<ResponseField name="runId" type="string">
  The ID of the newly created run. Use this with `get_run` to retrieve results once the run completes.
</ResponseField>