MCP triggers
Overview
Section titled “Overview”Connect Claude Code, Cursor, Claude, or another MCP client to Promptless. From the conversation you already have open, start a documentation task and get back its outcome and docs pull request link. You can also send a running task more instructions, ask Promptless to revise a suggestion, and label, assign, retitle, open, or close a suggestion. You authorize once in a browser, with no API key to manage.
MCP is an open protocol that editors use to connect to external tools. Any editor with an “MCP servers” setting can connect to Promptless. The Promptless MCP server is built in and always available, with no promptless.yaml triggers: entry and no setup on the Configuration page.
To use Promptless from the Claude.ai or ChatGPT web app, follow Use Promptless from Claude.ai or ChatGPT.
Before you start
Section titled “Before you start”- An MCP-capable editor, such as Claude Code or Cursor, or a chat app that accepts custom connectors, such as Claude.
- Your organization’s Promptless setup finished.
- An active membership in the organization. MCP needs no API key and no particular organization role.
Connect the server
Section titled “Connect the server”Promptless has two server URLs:
https://api.gopromptless.ai/mcpis the standard server. Promptless drafts the documentation changes, and you review them. Use it day to day.https://api.gopromptless.ai/mcp/with-direct-editsadds tools so your client can edit doc files itself. The extra tools use more of your client’s context, so switch to/mcponce you no longer need to edit files directly.
Each URL is a separate connection that you authorize on its own. The steps below use /mcp; use the direct-edit URL in its place to get the extra tools.
Connect the server once per editor. For Claude Code, one command sets it up:
claude mcp add --transport http promptless https://api.gopromptless.ai/mcpThe same URL and command also appear in the dashboard under Settings, in the Editor connection (MCP) section, which every organization member can see.
Claude Code
Section titled “Claude Code”-
Run the add command shown above.
-
Run
/mcpand pick promptless. -
Authorize the connection in the browser tab that opens. See Authorize in the browser.
Cursor
Section titled “Cursor”-
Add an HTTP MCP server named
promptless. Use the URLhttps://api.gopromptless.ai/mcp, either in Cursor’s MCP settings or by adding the entry tomcp.json:{"mcpServers": {"promptless": {"url": "https://api.gopromptless.ai/mcp"}}}The
urlkey tells Cursor to use HTTP transport. Or add the server in one step with the Add to Cursor deep link, which registers thepromptlessserver for you. -
Click Needs login.
-
Authorize the connection in the browser tab that opens. See Authorize in the browser.
VS Code
Section titled “VS Code”-
Add the
promptlessserver with thecodeCLI:Terminal window code --add-mcp "{\"name\":\"promptless\",\"type\":\"http\",\"url\":\"https://api.gopromptless.ai/mcp\"}" -
Run MCP: List Servers from the Command Palette and start promptless.
-
Authorize the connection in the browser tab that opens. See Authorize in the browser.
Codex CLI
Section titled “Codex CLI”-
Add the
promptlessserver; Codex infers HTTP transport from the--urlflag:Terminal window codex mcp add promptless --url https://api.gopromptless.ai/mcp -
Run
codex mcp login promptlessto start authorization. -
Authorize the connection in the browser tab that opens. See Authorize in the browser.
Claude
Section titled “Claude”Add Promptless to Claude as a custom connector:
-
In Claude, open Customize > Connectors, select +, then select Add custom connector.
-
Enter
https://api.gopromptless.ai/mcp, then select Add. -
Select Connect, and authorize the connection in the browser tab that opens. See Authorize in the browser.
On a Team or Enterprise plan, an Owner adds the connector under Organization settings > Connectors, then each member selects Connect in Customize > Connectors. Turn the connector on for a conversation from the + menu under Connectors.
Other MCP clients
Section titled “Other MCP clients”Any client that supports HTTP transport and OAuth connects at either URL. The exact steps vary by client.
Authorize in the browser
Section titled “Authorize in the browser”Your editor handles authorization automatically over OAuth; you approve the connection once in the browser.
-
A browser tab opens to the Promptless consent page.
-
Choose the organization to connect. The picker defaults to your active organization.
-
Check the Returns to row. It shows where Promptless sends access when you approve. Promptless doesn’t verify the client name, so go by this row. A local editor such as Claude Code or Cursor returns to a local address with a port, like
127.0.0.1:54321. An app that opens through its own link scheme shows a callback likemyapp://claude.ai/cb, and any app on your device that handlesmyapp://links receives the access. Cancel if you didn’t start this connection from that editor or app. -
Select Authorize as {your email}. Your editor stores the token and returns you to the editor.
A token is tied to one organization. When your client names the server URL in its authorization request, the token works only at that URL. When it doesn’t, the token works at both URLs, so the consent screen lists file reading and editing for every connection. To connect a second organization, authorize again and pick that organization at consent. Your editor can hold one Promptless connection per organization.
Available tools
Section titled “Available tools”Both server URLs carry these tools, which let you check on your collections, tasks, and suggestions, or queue and change your documentation work. The direct-edit URL adds more, described in Read and edit documentation directly. These tools are read-only: list_doc_collections, get_task_status, list_recent_tasks, search_suggestions, and wait_for_task_update. Your editor can auto-approve them, so routine status checks stop prompting you each time. These tools queue or change work: submit_documentation_task, send_task_message, answer_task_question, request_changes, update_suggestion, and close_suggestion. These always ask before they run.
submit_documentation_task
Section titled “submit_documentation_task”Starts a documentation task and returns a task ID (the trigger_event_id) you can check with get_task_status. It also returns a next_call, the next tool call your editor should make. It names wait_for_task_update with its arguments, so your editor can follow the task automatically.
| Argument | Required | Description |
|---|---|---|
instructions | Yes | What you want documented. |
doc_collection_id | No | Target one collection. Omit to route across all your collections. |
context | No | Optional metadata attached to the request; appears in trigger history. |
attachments | No | Links to material that explains the change, such as a screenshot, design file, or spec. Each attachment is a URL (required) with an optional description; nothing is uploaded, so a link Promptless can’t reach is skipped. |
A request that routes across all your collections still applies your relevance filtering per collection. To target one collection, pass a doc_collection_id from list_doc_collections.
A run takes several minutes. The submission returns a next_call, and your editor follows the task with wait_for_task_update until next_call is null. The outcome appears in the same conversation. To check status at a point in time, call get_task_status on request. To find a task later, use list_recent_tasks, which also lists tasks you didn’t start over MCP.
list_doc_collections
Section titled “list_doc_collections”Lists your documentation collections. Use it to get a doc_collection_id to pass to submit_documentation_task.
get_task_status
Section titled “get_task_status”Checks the status of any documentation task in your organization by its trigger_event_id, not only tasks you submitted over MCP. Tasks started from Slack, a GitHub pull request, the dashboard, or the API are all readable. The task’s submitted instructions and context appear in its trigger history.
It also returns the suggestions the task produced. Each comes with its docs pull request link and review status, using the same draft, open, merged, or closed values search_suggestions uses. The response says whether the task has finished. Once it has, outcome says how it ended: suggestions_created, no_change_needed, needs_input, or failed. outcome is null until the task finishes, and for tasks from sources other than the API, MCP, or the dashboard’s New Task page. A resolution note explains how the task ended.
It also returns the task’s conversation. The messages array is the persisted conversation between the customer and Promptless for that task, capped at the latest 100 messages and returned oldest-first. The messages array is populated for tasks submitted over the API, MCP, or the dashboard’s New Task page. It’s also populated for tasks created by calling request_changes over MCP. An empty messages array means either the task has no messages yet or its source doesn’t carry a conversation. Reading the conversation never consumes it.
Each message carries a stable, immutable id, a sequence number, an author object, a created_at, and the message text. The id lets a caller dedupe, relaying each new message only once. Your editor tracks these ids for you, so it doesn’t relay the same message twice. Incremental message delivery comes from wait_for_task_update’s cursor. get_task_status reads the conversation so far at a single point in time. The author object’s type is promptless or customer, and its name is the customer’s email when available, otherwise null.
A status_guidance field is a short text string carrying server-generated advice about following the task and interpreting its outcome. That advice is distinct from the conversation itself, which messages carries.
wait_for_task_update
Section titled “wait_for_task_update”Follows a running task in the same conversation. It waits for new messages, a changed result, or completion. You get the outcome without checking status by hand. It’s read-only, and your editor can auto-approve it.
| Argument | Required | Description |
|---|---|---|
trigger_event_id | Yes | The task to follow. |
cursor | No | Omit for an immediate initial snapshot. Reuse the cursor a prior call returned to receive later messages. |
wait_seconds | No | How long one wait lasts, from 0 to a server maximum of 30 seconds. Defaults to 30 when omitted. |
Each call returns a page of new conversation messages in messages, plus a cursor to pass to the next call. Each messages entry has the same shape as the ones get_task_status returns, with a stable id, a sequence, an author, and the message text. Reads never consume messages. Retrying the same call with the same cursor is safe. It may repeat messages your editor already saw, which your editor dedupes by id. A has_more_messages flag is true when more pages are ready. The update_type is snapshot on the first call for a cursor, which is when you omit cursor. It’s changed when new messages or a new result arrived, and timeout when nothing changed during the wait. The result and finished fields report the task’s outcome and whether it has finished. The result mirrors the outcome payload get_task_status returns. It carries the task’s resolution note and its suggestions, each with its docs pull request link and review status. Every call also returns a next_call, which names wait_for_task_update and its arguments.
Follow next_call until it’s null. next_call stays set while has_more_messages is true or the task isn’t finished. It becomes null only once the task is finished and has_more_messages is false. Your editor never stops on finished alone, so it never drops a trailing message page. A timeout is normal: your editor keeps waiting through the next next_call without a separate sleep and without narrating unchanged state. Waiting doesn’t cancel the cloud work.
You stay in control of following. Ask your editor to follow just once, or to stop at any time. get_task_status stays available to check a long-running task on demand.
send_task_message
Section titled “send_task_message”Use send_task_message to add an instruction to a task that’s still running. Use submit_documentation_task to start a new task, and request_changes to revise a suggestion Promptless already produced.
Sends an additional instruction into a task that’s already running. The instruction folds into that running task’s work, and no new task starts. A task stops accepting messages once it finishes, including one that finished by reporting a blocker or by marking a clarifying question. To answer a clarifying question, use answer_task_question instead; it answers a finished task’s marked question.
| Argument | Required | Description |
|---|---|---|
trigger_event_id | Yes | The original task’s ID (the one returned at submission). Reusing it keeps the reply on the same task; it does not create another task. |
message | Yes | The instruction to add. Up to 20,000 characters after trimming. |
idempotency_key | No | A safe-retry key. Retrying with the same key and the same text returns the original message marked deduplicated. The same key with different text is rejected as a conflict. |
It returns the stored message plus a deduplicated boolean. When the message is newly stored, deduplicated is false; it comes back true only when an idempotency_key retry matches an already-stored message. That stored message has the same shape as an entry in get_task_status’s messages array.
Like reading a task’s status, sending isn’t limited to tasks you started. You can send to an eligible task in your organization by its trigger_event_id. Task conversations apply to tasks submitted over the API, MCP, or the dashboard’s New Task page, and to tasks created by calling request_changes over MCP. Reading a task’s status with get_task_status stays available for every task source.
Like the other work-changing tools, it prompts before it runs and isn’t auto-approved.
answer_task_question
Section titled “answer_task_question”Use answer_task_question to answer a clarifying question a finished task marked. Use send_task_message to add an instruction to a task that’s still running. For the full walkthrough, see Answer a clarifying question.
Answers the one clarifying question a finished task marked, so Promptless continues the work.
| Argument | Required | Description |
|---|---|---|
trigger_event_id | Yes | The finished task whose question you’re answering (UUID). |
question_message_id | Yes | The marked question’s message ID (UUID). |
answer | No | The answer text, 1–8000 characters. Omit it to have your editor open its native input form. Supply it only when you’ve already given the answer. |
It returns the question text, an outcome, an optional continuation trigger_event_id, an optional next_call, and a message. The outcome is one of five values:
submitted. The answer is accepted, and Promptless starts a new continuation task. That continuation carries the original request, context, clarification history, and links to any results.next_callandtrigger_event_idpoint at it, so follownext_call.already_answered. The question already had an answer committed, by an earlier call or an overlapping native form. Retrying with the same answer returns that committed answer instead of erroring. If a different answer won first, yours isn’t submitted. Follow the task the returnedtrigger_event_idnames, which points at the continuation already created.unavailable. Your editor can’t show a native form, so it asks the question in chat and callsanswer_task_questionagain with the answer.declineorcancel. You declined or canceled the question, so following stops.
Like the other work-changing tools, it prompts before it runs and isn’t auto-approved.
request_changes
Section titled “request_changes”Use request_changes when you want Promptless to make the change for you. Use update_suggestion to set the suggestion’s labels, assignees, or title, or to open its pull request yourself. Use close_suggestion to end a review without shipping it.
Asks Promptless to revise a suggestion it already produced. This is the revision loop.
| Argument | Required | Description |
|---|---|---|
suggestion_id | Yes | The ID of the suggestion to change (from search_suggestions or get_task_status). |
instructions | Yes | What to change about the suggestion. |
Promptless updates that suggestion’s existing docs pull request instead of opening a second one. It returns a task ID you check with get_task_status, plus a next_call that follows the revision task with wait_for_task_update. If the suggestion’s pull request is no longer one Promptless can revise, the tool reports that back; start a new task with submit_documentation_task instead.
update_suggestion
Section titled “update_suggestion”Sets a suggestion’s metadata (its labels, assignees, and title) yourself, and optionally opens its docs pull request. This is the path where you make the change yourself. By contrast, request_changes has Promptless make it, and close_suggestion ends a review without shipping it. Pass the suggestion’s ID (from search_suggestions or get_task_status).
| Argument | Required | Description |
|---|---|---|
suggestion_id | Yes | The suggestion to update. |
labels | No | Replaces the suggestion’s stored labels. Omit to leave them alone; pass an empty list to clear them. |
assignees | No | Replaces the suggestion’s stored assignees. Omit to leave them alone; pass an empty list to clear them. |
title | No | Sets the suggestion’s title. |
open_pull_request | No | Pass true to open the suggestion’s docs pull request in this call. Any labels or assignees edits in the same call apply first. |
The title can be set here, but a suggestion’s description can’t. Labels and assignees are applied before the title. The title edit is pushed to the host GitHub or GitLab pull request before it’s stored. While a suggestion’s pull request is open, the host owns its title. So a title edit has to reach the pull request to stick. If the suggestion has no open pull request yet, the title is stored directly, since there’s no pull request to push to. If the host rejects the push, the call fails and the stored title is left unchanged. Any labels or assignees applied in the same call stay applied. The call is idempotent, so repeating it with the same arguments leaves the suggestion unchanged.
It returns the updated labels, assignees, and title. It also returns the docs pull request URL (docs_pr_url), which is null when the suggestion has no open pull request. Finally, it reports whether this call opened the pull request (pull_request_opened).
Because labels and assignees each replace the stored list, adding one without dropping the others means sending the full desired list. Read the current values first with search_suggestions, which returns each suggestion’s labels and assignees. Setting them tags this one suggestion; it isn’t a standing rule that auto-assigns or auto-labels future suggestions.
Opening the pull request is idempotent too. If the suggestion’s docs pull request is already open, setting open_pull_request to true returns the existing pull request. It then reports pull_request_opened as false rather than opening a second one.
close_suggestion
Section titled “close_suggestion”Ends a review without shipping it. This is the close path. It contrasts with revising the suggestion using request_changes, or opening its pull request yourself with update_suggestion.
| Argument | Required | Description |
|---|---|---|
suggestion_id | Yes | The suggestion to close. |
reason | No | An optional note saved with the close. |
Closing the suggestion closes its docs pull request on the host first. If the host refuses to close the pull request, the suggestion stays open and the call reports why. A pull request that already merged, or otherwise shipped, can’t be closed. If the suggestion has no open pull request, the suggestion closes normally.
Closing can’t be undone from your editor: no MCP tool reopens a closed suggestion. To pursue the change again, start a new task with submit_documentation_task.
The close is attributed to your MCP client, so it’s distinguishable from a close done in the dashboard. It also records who closed it: you, plus your editor’s registered client name. Any reason you pass is saved with the close.
In the dashboard’s close dialog, the Send to Promptless option sends your closing comment to Promptless and starts a follow-up run. close_suggestion has no equivalent, so a close over MCP starts no follow-up task.
The call returns the suggestion_id, the resulting status, and a message. Like the other work-changing tools, it prompts before it runs. It’s destructive and can’t be auto-approved.
list_recent_tasks
Section titled “list_recent_tasks”Lists your organization’s recent documentation tasks, newest first, each with the trigger_event_id you pass to get_task_status. Use it when you’ve lost a task’s ID, or to see what Promptless has been working on. Like get_task_status, it covers tasks started from Slack, a GitHub pull request, or the dashboard, as well as tasks submitted over MCP. A task submitted over the API is read by ID with get_task_status.
search_suggestions
Section titled “search_suggestions”Searches your existing suggestions by keyword and status. Use it to check whether a change is already covered before starting a new task, or to find a suggestion to revise.
| Argument | Required | Description |
|---|---|---|
query | Yes | Matches a suggestion’s title and description. Must be at least 3 characters after trimming. |
status | No | Restricts results to one of draft, open, merged, or closed. |
labels | No | A list of label strings. Returns only suggestions carrying at least one of the given labels. This is an any-of match. Omit it or pass an empty list to apply no label filter, so results come back across all labels. Matches exactly, including case, so a label in the wrong case returns nothing; call search_suggestions without labels first to see the exact stored label strings. |
limit | No | Caps how many results come back. Defaults to 25, never exceeds 100. |
When more suggestions match than were returned, the result sets a truncated flag so you know to narrow the query. Filtering by labels pulls a labeled queue, such as every P0 suggestion, in one call. That saves you fetching everything and filtering client-side, and the triage-suggestions workflow skill below relies on it. A draft or open suggestion is still live; a merged or closed one is already resolved. Each result also carries its labels and assignees, each a list of strings, and its branch_name (the git branch in the documentation repository the suggestion targets, always present). Use them to pick the suggestion to hand to update_suggestion or request_changes. You can also check out and diff the proposed change locally, even before its docs pull request opens. Once the suggestion’s pull request has merged or closed, the branch may no longer exist, since hosts often delete it. So a local checkout applies to a still-open suggestion.
Read and edit documentation directly
Section titled “Read and edit documentation directly”These tools are available only at https://api.gopromptless.ai/mcp/with-direct-edits. With them, your client finds pages, edits them on an open suggestion’s branch, checks the diff, and opens the pull request with update_suggestion.
Edits go on an open suggestion. For a change no open suggestion covers, start a task with submit_documentation_task, then edit the suggestion it creates.
Your client can auto-approve the four read tools: list_documentation_files, read_documentation_file, search_documentation, and get_suggestion_diff. The two write tools, write_documentation_file and edit_documentation_file, ask before each run.
Choose what a read covers
Section titled “Choose what a read covers”list_documentation_files, read_documentation_file, and search_documentation take the same two optional arguments to choose what they read:
| Argument | Required | Description |
|---|---|---|
doc_collection_id | No | The collection to read, from list_doc_collections. Pass it when your organization has more than one collection and you don’t pass suggestion_id. |
suggestion_id | No | The suggestion whose branch to read, to see pages as it proposes them. Omit it to read the collection’s default branch, your published docs. |
Each read returns a ref with the sha and branch_name it read. Pass that sha as expected_head_sha when you edit. Reads cover only the paths Promptless maintains for the collection.
list_documentation_files
Section titled “list_documentation_files”Lists a collection’s file paths in sorted order. Use it to find a page’s path before you read or edit it.
| Argument | Required | Description |
|---|---|---|
path_prefix | No | Lists only paths that start with this prefix, such as docs/api/. |
limit | No | How many paths to return. Defaults to 500, never exceeds 2,000. |
It returns the files, a total count of matching paths, and a truncated flag. When truncated is true, narrow the listing with path_prefix.
read_documentation_file
Section titled “read_documentation_file”Reads one text file by its repository-relative path, which is required. It returns the file’s content and size_bytes. It refuses binary files and files over 256 KB.
search_documentation
Section titled “search_documentation”Finds lines that match text or a regular expression across a collection’s text files, such as Markdown, MDX, reStructuredText, YAML, JSON, and HTML.
| Argument | Required | Description |
|---|---|---|
query | Yes | The text to find, or a regular expression when regex is true. Up to 256 characters. |
regex | No | Pass true to treat query as an RE2 regular expression, similar to grep -E. |
case_sensitive | No | Pass true to match case exactly. |
path_prefix | No | Searches only files whose path starts with this prefix. |
limit | No | How many matching lines to return. Defaults to 50, never exceeds 200. |
RE2 syntax covers character classes, alternation, and repetition, such as retr(y|ies) or v[0-9]+\.[0-9]+. It doesn’t support backreferences such as \1 or lookaround such as (?=...).
Each match returns the file path, line number, and line text. A search reads up to 400 files of up to 128 KB each, within 10 seconds. files_skipped counts the files it didn’t reach; when it’s above zero, search again with a narrower path_prefix. truncated is true when more lines matched than limit returned.
get_suggestion_diff
Section titled “get_suggestion_diff”Shows what a suggestion changes. Pass its suggestion_id, which is required. It returns one unified diff per changed file against the collection’s base branch, and each file’s status: added, modified, removed, or renamed. It also returns the suggestion’s head_sha, which you can pass as expected_head_sha when you edit.
Diff text is capped at 200,000 characters per response. Once the cap is reached, each later file carries a diff of null and truncated is true. Binary files carry no diff text.
write_documentation_file
Section titled “write_documentation_file”Creates or replaces one file on an open suggestion’s branch with the full content you pass. Use it for a new page or a rewrite of most of a page. For a change to part of a page, use edit_documentation_file.
| Argument | Required | Description |
|---|---|---|
suggestion_id | Yes | The open suggestion whose branch receives the commit. |
path | Yes | The repository-relative file path, inside the paths Promptless maintains for the collection. |
content | Yes | The complete new file content, up to 256 KB. |
expected_head_sha | No | The ref.sha from your last read, or the head_sha from your last write. The write is refused when the suggestion’s branch has moved since then. |
edit_documentation_file
Section titled “edit_documentation_file”Replaces exact text in one file on an open suggestion’s branch. It takes suggestion_id, path, and expected_head_sha as write_documentation_file does, plus edits, which is required.
edits is a list of 1 to 50 entries, each with an old_text and a new_text. Each old_text must match the file exactly once, so copy it verbatim from a read and include enough surrounding text to make it unique. An empty new_text deletes the matched text. The edits apply in order, and the call is refused when any old_text matches no place or several places.
What a write commits
Section titled “What a write commits”Each write_documentation_file or edit_documentation_file call makes one commit on the suggestion’s branch, attributed to you and your client: Update from <your email> via <client name>. It returns the new head_sha to pass as expected_head_sha on your next write, plus the suggestion’s docs_pr_url and status. When your edits leave the suggestion with no changes against its base branch, Promptless closes the suggestion and its docs pull request.
No tool deletes a file. To remove a page, describe the removal with request_changes.
Answer a clarifying question
Section titled “Answer a clarifying question”A task can finish by marking one clarifying question in your editor. This applies to a task you started over MCP. Answering it starts a new continuation task. That task carries the original request, the original context, the clarification history, and links to any results already produced. You pick up directly from the clarification.
To answer through the native form, you need an MCP client that negotiates a recent protocol version and declares an elicitation capability. That capability is the MCP feature that lets a server show an input form inside your editor.
A clarifying question reaches you through the same task-following loop this page documents. As your editor follows the task with wait_for_task_update, or as you check it with get_task_status, the response carries the marked question and a next_call pointing at answer_task_question. Your editor follows that next_call the same way it follows any other task.
How you answer depends on your MCP client:
- A client that declares an elicitation capability shows a native single free-text field titled Your answer, with the question as its prompt. The answer runs 1–8000 characters.
- A client without that capability receives
outcome: unavailable. Your editor posts the question as a chat message. Reply in the same conversation, and your editor relays your answer by callinganswer_task_questionagain.
Your editor follows the accepted answer via its next_call, which points at the new continuation task. The first committed answer wins. Answering the same question again returns already_answered, and a matching answer comes back unchanged. If a different answer won first, yours isn’t submitted. You follow the task the response names, the continuation already created, to pick up the committed one. If you decline or cancel the question, no continuation is created and following stops. The original finished task and anything it already produced, such as suggestions, remain. To pursue the change, start a new task with submit_documentation_task.
Workflow skills
Section titled “Workflow skills”If your editor supports it, Promptless can hand it step-by-step guidance for multi-step workflows that chain several of these tools together. A skill guides your editor through the tools above and adds no tools of its own. The editor decides when to load a skill, and you ask for what you want as usual.
triage-suggestions is available at both server URLs. edit-documentation is available only at the direct-edit URL.
triage-suggestions is a workflow for working through a backlog of suggestions. It pulls the backlog with search_suggestions and checks the truncated flag to see whether more are waiting. Then it reads each proposal in turn. Next it gives each suggestion one outcome, then hands the queue back to you. It can label or assign a suggestion with update_suggestion, send it back for a revision with request_changes, or close it with close_suggestion. Following that sequence keeps the editor from treating a truncated result set as your whole backlog. It also gives each suggestion exactly one outcome without you prompting each step.
edit-documentation walks your client through one direct edit. It finds the pages, picks or starts a suggestion, edits each page, checks the diff, and opens the pull request.
A skill doesn’t change how the tools behave. The work-changing tools these skills call, such as update_suggestion, request_changes, close_suggestion, and edit_documentation_file, still prompt before each run, just as they do when you call them directly. A skill only guides the sequence; it doesn’t bypass those confirmations.
A client that doesn’t support the extension, or ignores it, sees the same tools and calls them directly.
Ask your editor
Section titled “Ask your editor”Ask in plain language. For example: “List my Promptless doc collections, then start a task to document the new authentication flow in the API docs collection.” Your editor maps that to list_doc_collections, then submit_documentation_task. It follows the task automatically in the same conversation, using the next_call it gets back. It reports the outcome and docs pull request link back to you, without you checking status by hand.
To avoid duplicating work, search before you submit. Your editor runs search_suggestions first, and if nothing live comes back, submits the task. For example: “Before I ask Promptless to document the new webhook retries, search existing suggestions for ‘webhook retries.’”
To check a task at a point in time, ask by its ID: “What’s the status of Promptless task <id>?” Your editor calls get_task_status and reports the outcome and any docs pull request link. This is the on-request check, not the primary way you get an outcome. Reach for it for a task you didn’t follow to completion, or to look in again later or from another session. It works for any task.
To read a task’s conversation, ask for it: “What has Promptless said so far about task <id>?” Your editor calls get_task_status and reports the conversation.
To add to a task that’s still running, tell Promptless what else to cover: “Tell Promptless task <id> to also cover the error responses.” Your editor maps that to send_task_message, and the instruction folds into the running task. This works for tasks you started over the API or MCP, tasks you created with request_changes over MCP, and New Tasks submitted from the dashboard. Check back with get_task_status to see the message added to the conversation.
A task can finish by marking one clarifying question. Answer it in plain language: “Answer Promptless task <id>’s clarifying question: yes, cover the deprecation notice.” Your editor calls answer_task_question, and Promptless picks up your answer in a new task. Your editor follows that task via its next_call.
To change a suggestion Promptless already made, ask for a revision: “Revise Promptless suggestion <id> to also cover single sign-on.” Your editor calls request_changes, and Promptless updates that suggestion’s existing pull request instead of opening a new one. Your editor follows the revision task via next_call until it’s done, the same way it follows a new task.
To set a suggestion’s labels, assignees, or title, or open its docs pull request yourself, ask for that. For example: “Assign Promptless suggestion <id> to @alex, retitle it ‘SSO setup,’ and open its docs PR.” Your editor calls update_suggestion, which applies the change and opens the pull request in the same step. To just retitle it without opening a pull request, leave that part out: “Retitle Promptless suggestion <id> to ‘SSO setup.’”
To close a suggestion you won’t ship, ask for that: “Close Promptless suggestion <id>. We decided not to document this.” Your editor calls close_suggestion and saves your reason with the close; closing also closes the suggestion’s docs pull request.
If you’ve lost track of a task’s ID, ask for your recent ones: “What are my recent Promptless tasks?” Your editor calls list_recent_tasks and lists them newest first, so you can pick the ID to check.
To work through a backlog, ask for a triage pass: “Triage my open Promptless suggestions, label the P0s, and close anything we’ve decided against.” If your editor supports workflow skills, it can follow the triage-suggestions steps; if not, it calls the same tools directly. Either way the work-changing tools still prompt before they run, so you stay in control of what changes.
On the direct-edit URL, name the change and the suggestion to put it on: “Find the pages that say webhook retries default to 3. Change them to 5 on the open webhook retries suggestion, show me the diff, and open the PR.” Each edit asks before it commits.
See your MCP tasks in the dashboard
Section titled “See your MCP tasks in the dashboard”On the Triggers page, a task started over MCP shows an MCP Task pill with a byline reading <client name> · submitted by @<username>. Tasks submitted with an sk-pl- API key show an API Task pill.
To find MCP-originated suggestions on the Suggestions list, set the Trigger source filter to “API”. That filter includes both MCP and API-key submissions.
Manage and revoke your connection
Section titled “Manage and revoke your connection”Connections re-authorize automatically. The connection you approve lasts 90 days. After that, automatic refresh stops, and you approve the connection in the browser again, the way you did at setup.
To revoke a connection, remove the promptless server from your editor, such as from Cursor’s MCP settings. In Claude, remove the connector from Customize > Connectors. The dashboard’s Editor connection (MCP) section shows setup instructions only, so revoke from your editor or chat app.
Promptless checks your organization membership on every call, and revokes the connection if you lose active membership. Each member manages their own connection. An admin can’t revoke another member’s connection for them.
Troubleshooting
Section titled “Troubleshooting”Tool failures come back as errors your editor’s model sees, each formatted as code: message. Common ones:
- Empty
instructions: resubmit with a specificinstructionsstring. - A
doc_collection_idthat isn’t a valid ID (UUID): calllist_doc_collectionsand pass anidfrom the returned list. - An unrecognized
search_suggestionsstatus: use one ofdraft,open,merged, orclosed. - A missing
search_suggestionsquery, or one shorter than 3 characters after trimming: provide aqueryof at least 3 characters. - The organization hasn’t finished setting up Promptless: the tool returns “This organization has not finished setting up Promptless.” Finish setup on the Configuration page, or ask a member with admin access to finish it.
- A requested collection isn’t configured: the tool returns “The requested doc collection is not configured.” Call
list_doc_collectionsfor a validid, or configure the collection first. - A suggestion that can no longer be revised:
request_changesreports that the suggestion is no longer one Promptless can revise. Its pull request has moved beyond where a revision applies. Start a new task withsubmit_documentation_taskinstead. - An
update_suggestioncall that can’t be applied: asuggestion_idthat isn’t a valid ID (UUID) or matches no suggestion returns an error. Callsearch_suggestionsfor a valid ID. Setting a suggestion’s labels, assignees, or title still succeeds even on a closed or merged suggestion. Only opening a pull request is refused for a closed suggestion that hasn’t merged, and the tool reports why. If the host rejects the title push, the call fails and the stored title is left unchanged. Any labels or assignees from the same call stay applied. No MCP tool retracts a pull request while keeping the suggestion open for further editing. Closing over MCP withclose_suggestioncloses the suggestion and its pull request together. If you opened a pull request by mistake and want to keep working the suggestion, close the pull request on the host directly. The host is GitHub or GitLab. - A
close_suggestioncall that can’t be applied: asuggestion_idthat isn’t a valid ID (UUID) or matches no suggestion returns an error. Callsearch_suggestionsfor a valid ID. If the host refuses to close the pull request, the suggestion stays open and the tool reports why. A pull request that already merged can’t be closed. A suggestion that’s already closed can’t be closed again, and the tool reports so. - Sending to a finished task: the tool rejects it with
task_finished. A task that finished by reporting a blocker or a clarification request has still finished, so it also rejects messages. Start a new task withsubmit_documentation_taskto continue. If the finished task marked a clarifying question, answer it withanswer_task_question. That continues the work in a new task. - Sending to a task whose source has no conversation: the tool rejects it with
unsupported_task_source. Task conversations cover API and MCP submissions, tasks created by callingrequest_changesover MCP, and New Tasks submitted from the dashboard. Read the task’s status instead, or submit a New Task or an API or MCP task to converse. - An empty or over-length message: the tool rejects it with
invalid_message. The limit is 20,000 characters after trimming. - A retried message that conflicts with a stored one: the tool rejects it with
idempotency_conflict. The retry reused the sameidempotency_keywith different text. Resend with a newidempotency_key, or with the original text. - A
wait_for_task_updatecursor that’s invalid or from another task: the tool rejects it withinvalid_cursor. Omit the cursor to read from the beginning. If task storage doesn’t respond in time, the tool returnstask_read_timeout; retry the same task and cursor. Setwait_secondsbetween 0 and 30, the server maximum. answer_task_questionreturnsunavailable: your editor can’t show a native form. It asks the clarifying question in chat and callsanswer_task_questionagain with your answer.answer_task_questionreturnsalready_answered: the question already had an answer committed. Follow the task the returnedtrigger_event_idnames, which is the continuation already created. If a different answer won first, yours wasn’t submitted; following that task shows the committed answer.answer_task_questionreturnsdeclineorcancel: you declined or canceled the question. No work continues and following stops. The original task and anything it already produced remain. To pursue the change, start a new task withsubmit_documentation_task.- An answer reference that points at an unrelated task:
answer_task_questionrejects it withcontinuation_conflict. This happens when theidempotency_keymatches a task other than this question’s own continuation. That covers a different parent task, a different question, or a task ineligible for a clarifying answer. Promptless doesn’t reuse that task. Start a new task withsubmit_documentation_task, restating your original request and your answer. - A deduplicated answer whose continuation can’t be found:
answer_task_questionrejects it withcontinuation_unavailable. This case is transient. A concurrent identical answer to the same question was still committing its continuation when this call looked for it. Retryanswer_task_questionwith the same arguments. - A read that names no collection in an organization with several: the tool reports the available collections. Pass a
doc_collection_idfrom that list, or pass asuggestion_id, which selects its collection. - A path outside the paths Promptless maintains: the read, list, or write is refused. Promptless reads and edits only the paths configured for the collection. Call
list_documentation_filesfor valid paths. - A
search_documentationquery that isn’t valid RE2: the tool reports that the query is not a valid RE2 regular expression. The error names what failed to parse. Rewrite the pattern without backreferences or lookaround, or setregextofalseto search for the literal text. - A
search_documentationquery over 256 characters: the tool refuses it. Shorten the query. - A file over 256 KB:
read_documentation_fileand both write tools refuse it. A binary file is refused for reading too. - A write to a closed suggestion: the tool refuses it, since a closed suggestion’s branch accepts no edits. Pick an open suggestion with
search_suggestions, or start a task withsubmit_documentation_task. - A write to a suggestion whose task hasn’t finished: the tool refuses it until Promptless records the suggestion’s first commit. Wait for the task to finish, then retry.
stale_head: the suggestion’s branch changed after your last read, soexpected_head_shano longer matches it. The error names the current commit. Read the file again and retry with that commit asexpected_head_sha.- An
old_textthat matches no place or several places:edit_documentation_filerefuses the whole call and reports which edit failed and how many places it matched. Read the file again, copy the text verbatim, and include enough surrounding text to match once. - Denied, canceled, or expired consent: re-run the authorize step. In Claude Code, run
/mcpand pick promptless again. In Cursor, click Needs login again.
Setup issues
Section titled “Setup issues”First-run snags usually clear with a retry:
- The browser consent tab doesn’t open: re-run the authorize step. In Claude Code, run
/mcpand pick promptless; in Cursor, click Needs login. - No promptless entry under
/mcpin Claude Code: confirm the add command ran, then re-open the client. - Cursor’s Needs login button doesn’t respond: remove the server and add it again.
See also
Section titled “See also”- API triggers, for server-to-server and CI callers that use an API key
- Use Promptless from Claude.ai or ChatGPT, to connect from a web chat app
- Access and permissions, for organization roles and what members can do
- Noise and relevance filtering, to control which submitted tasks produce suggestions