Tool reference
Overview of the seven Doclight MCP tools, their permissions, and the conventions they share for pagination, idempotency and errors.
Doclight's MCP server ships seven tools. Four read data; three can change data or start paid work and are only offered to a
write-scope key.
| Tool | Kind | Maps to | Needs |
|---|---|---|---|
list_brands | Read | GET /api/v1/brands | read |
list_questions | Read | GET /api/v1/brands/{id}/questions | read |
get_visibility_summary | Read | GET /api/v1/brands/{id}/report-summary | read |
get_run_status | Read | GET /api/v1/brands/{id}/runs[/{run_id}] | read |
create_project | Write | POST /api/v1/brands | write key authorised for a workspace |
add_prompt | Write | POST /api/v1/brands/{id}/questions | write, brand admin access |
trigger_run | Write, may consume quota | POST /api/v1/brands/{id}/runs | write, brand admin access, paid access |
"Project" and "brand" are the same thing; "prompt" and "question" are the same thing. Tool results are structured JSON.
Shared conventions
Pagination
list_brands and list_questions return next_cursor. Pass it back as cursor to get the next page; null means the last
page. limit is 1–100 (default 50). Cursors are opaque and stable under concurrent writes. A malformed or expired cursor is
reported as invalid request parameters.
Idempotency
Every write tool accepts an optional idempotency_key (printable ASCII, 1–255 characters). If you omit it, the server derives a
stable key from the tool name and arguments, so a retried identical call returns the original object with replayed: true
instead of creating a duplicate. The same key with different arguments is a conflict. A refused create (validation, plan
limit, duplicate) stores nothing, so its key can be reused. See each tool for the exact derivation.
Errors
Failures return a short, fixed message that never contains the API key or upstream response text, usually with a request_id
to quote to support. See Troubleshooting for the full list.
API-model measurements
Visibility numbers come from provider APIs, not consumer chat or search interfaces. See Metrics and methodology.