Write tools

Write tools are registered only when the configured key has write scope (and, for create_project, is authorised for a workspace). They are annotated readOnlyHint=false, destructiveHint=false and idempotentHint=true; their descriptions begin with MUTATION. None of them deletes or overwrites anything. Every create, replay and rejected duplicate is audited.

create_project

Creates a project (brand) in the key's workspace. Counts against the plan's project limit. Needs a write credential authorised for a workspace; a credential limited to specific brands is refused.

{ "domain": "acme.com", "name": "Acme", "target_languages": ["en"], "target_countries": ["US"] }

{
  "id": 12,
  "name": "Acme",
  "domain": "acme.com",
  "replayed": false,
  "idempotency_key": "mcp-create_project-3f2a..."
}

Repeating the same call returns the same project with replayed: true. A project that already exists for the domain is a "duplicate" error, and a reached plan limit is a "project limit" error.

add_prompt

Adds a tracked question to a project. Counts against the plan's prompt limit. Needs write scope and admin access to the project.

{ "brand_id": 12, "content": "Best CRM for startups?", "language": "en", "target_country": "US", "providers": ["openai"] }

{
  "id": 101,
  "brand_id": 12,
  "content": "Best CRM for startups?",
  "language": "en",
  "target_country": "US",
  "status": "paused",
  "cadence": "daily",
  "providers": ["openai"],
  "replayed": false,
  "idempotency_key": "mcp-add_prompt-9c1e..."
}

A question is created paused, so nothing runs until you set it active (in the dashboard) or start a run with trigger_run. A question that is already tracked is a "duplicate" error; a reached prompt limit is a "prompt limit" error.

trigger_run

Starts a measurement run for explicit questions. This may consume quota and makes paid provider calls. Only call it when a run is wanted: no read tool ever starts one, and the tool description tells the model to run only when you asked.

Needs write scope, admin access to the project, and active paid access.

{ "brand_id": 12, "question_ids": [101, 102], "providers": ["openai"] }

{
  "status": "queued",
  "run_id": 57,
  "brand_id": 12,
  "run_status": "pending",
  "dispatch_state": "queued",
  "replayed": false,
  "idempotency_key": "mcp-trigger_run-de97...",
  "question_ids": [101, 102],
  "providers": ["openai"],
  "max_provider_calls": 2
}

Cost and quota

• Each dispatch uses one of the plan's daily manual-run allowance and makes up to questions × providers paid provider calls. max_provider_calls reports that bound only when you narrowed providers; otherwise it is null because each question's own provider list applies.
• The quota is checked and reserved before anything is queued. If it is used up, the result is status: "rejected" with reason: "report_quota_reached" and daily_run_limit when known.
• If a run for the project is already in progress, the result is status: "rejected" with reason: "run_in_flight" and the in-flight run_id when reported. Nothing is reserved.
• The tool does not wait. It returns queued with a run_id; poll get_run_status.
• Execution is at-most-once per dispatch, not exactly-once: a provider call that timed out may still have been processed and billed.

Retrying safely

If you omit idempotency_key, one is derived from the brand, the questions, the providers and today's UTC date. A retry of the same call that day returns the existing run (replayed: true) without using more quota. To run the same questions again on the same day, pass a new idempotency_key. If the queue refused a run (dispatch_failed), retrying with the same key queues that same run again without using more quota.

Idempotency keys (all write tools)

Keys are scoped to the credential and the operation. When the server derives a key, it is returned as idempotency_key so you can reuse it.