Agents reach planpage through the MCP server at https://app.planpa.ge/mcp. Scripts and CI can call the same tools over HTTPS. Both act as an agent connection, so the connection's workspaces and access levels apply; see Agents and access.
Tools marked Read only work at every access level. The rest need Publish only or Publish and run. Tools that carry out plans (claim_step, release_step, update_step, link_ref, complete_plan and pick_up_brief) need Publish and run.
Errors come back as a plain message saying what went wrong and, where it helps, what to do, for example "This plan has no approved version yet." Over REST, the HTTP status also says what kind of error it is: 400 for invalid arguments, 403 when the connection isn't allowed to do it, 404 for something that doesn't exist (including an unknown tool), 409 when the document changed since you read it, and 500 for a fault on planpage's side, which is worth retrying.
Docs for agents
These docs are also available as plain markdown, so agents don't have to read rendered pages:
https://planpa.ge/llms.txtlists every page with a one-line description, in the llms.txt format.https://planpa.ge/llms-full.txtis every page in one file.- Any page as markdown: add
.mdto its address, such ashttps://planpa.ge/docs/connect-an-agent.md, or request the normal address withAccept: text/markdown.
Each docs page also links its markdown version in its <head> and in a Link header. All of it is built from the same source as these pages, so it is always current.
REST API
Every MCP tool is also available over HTTPS, for scripts and CI.
| Request | What it does |
|---|---|
GET https://app.planpa.ge/api/v1/tools |
Lists every tool with its JSON schema. |
POST https://app.planpa.ge/api/v1/tools/<name> |
Calls a tool. The JSON body is the tool's arguments; the response is { "result": … } or { "error": … }. |
Authenticate with an API token from Your account → Agent connections:
curl -s https://app.planpa.ge/api/v1/tools/whoami -X POST \
-H "Authorization: Bearer pp_…" -H "content-type: application/json" -d '{}'
The token acts with the access levels it was given in each workspace.
MCP tools
planpage has 50 tools. Agents see the same names and descriptions.
ask_human
Ask a human. Add a blocking question to the document and notify the reviewers. Put it beside what it's about: pass after_block_id (a step, a heading's section, or any block) so the reviewer has the facts on screen; without it the question goes at the end. Read the answer later with get_feedback.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
prompt |
string | Yes | |
options |
list of string | No | |
after_block_id |
string | No | Insert right after this block (e.g. the step it's about), or at the end of this heading's section (block id or heading text). Ids from read_document_blocks or outline. |
claim_step
Claim step. Claim a step so other agents don't work on it. Claims expire (default 30 min) and renew when you update the step.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
step |
string | Yes | Step block id, e.g. s1 |
ttl_seconds |
integer | No |
comment
Comment. Start a comment thread, optionally anchored to a block. Write @name#0042 in the body to mention someone who can open the document's workspace (see mentionable_people): they get an inbox notification, including the person this connection acts for when you need their attention. Attach screenshots with images (marks optional). On an image block, pin puts the thread on a spot of the image.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
body |
string | Yes | |
block_id |
string | No | |
images |
list of object | No | Screenshots to attach (up to 6): upload each with upload_image first |
pin |
object | No | Pin the thread to this spot on block_id's image, in the image's pixels |
complete_plan
Complete plan. Finish an approved plan with a report: steps done, skipped and added, and how the result differs from the plan.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
report_markdown |
string | Yes | |
title |
string | No |
create_project
Create project. Create a project in a workspace you can write to (whoami lists them). In a folder without a usable git remote, list_repositories suggests GitHub repositories (and their names) to link.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | |
repo_url |
string | No | |
workspace_id |
string | No | From whoami. Omit for your first personal workspace. |
organization_id |
string | No | Old name for workspace_id, still accepted. |
create_workspace
Create workspace. Create a workspace: a personal one (only you see it), or one in a team you're on (whoami's teams say where you can). You become its owner, this connection reaches it, and its workspace_id is returned for create_project. Team workspaces start private unless visibility is open. Only do this when the user asks.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | |
team_id |
string | No | From whoami's teams. Omit for a personal workspace. |
visibility |
private · open |
Yes | Team workspaces only. Open: everyone on the team can find and join it. |
delete_image
Delete image. Delete an image uploaded by you or one of your agents. Its URL stops working everywhere it's used, including GitHub, and documents show a placeholder. Copies already cached by browsers or GitHub's image proxy may linger until they expire. Only do this when the user asks.
| Parameter | Type | Required | Description |
|---|---|---|---|
image_id |
string | Yes | |
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
diff_versions
Diff versions. Unified diff between two versions (or a version and the working copy). Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
from |
integer | Yes | |
to |
integer | No |
edit_blocks
Edit blocks. Targeted edits by block id (from read_document_blocks): replace, insert_after, insert_before, delete, append. Leaves the rest of the document untouched. @name#0042 in the markdown mentions that person and notifies them.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
edits |
list of value | Yes | |
base_revision |
integer | No | |
save_version |
boolean | Yes | |
summary |
string | No |
find_people
Find people. Look people up to invite or share with. People you already work with match by name or username from the first letter and come first. From 3 letters, anyone on Planpage matches by the start of their name or username (top 5 results). An exact username#0000 or email address finds that person. Needs the connection to be allowed to invite people and share documents. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | A name, username#0000 or email address |
get_feedback
Get feedback. Review status, the reviewer's note, unresolved comments (with quoted context), widget state and a diff of human edits since your last version. On a long document pass section to get only that section's comments, widgets and edits, or thread_id for one thread. A decision's picked is the chosen option's title, or the reviewer's own answer when pickedOther is true (they chose "Other" and wrote it; follow it over your options). Picks and answers count only once the reviewer approves or requests changes: ones they've clicked since are hidden (held: true, with reviewInProgress set), so never start work on a document that has reviewInProgress or isn't approved. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
section |
string | No | Only this section: a heading's text or block id (from outline), or the id of any block inside it. A section runs to the next heading at its level or above. |
thread_id |
string | No | Only this comment thread |
get_skill
Get the planpage skill. The planpage SKILL.md for Claude Code, Codex, Antigravity and other agents, with its version and install path. Pass client so the path matches where your client reads skills. Use it to install or update the local skill when the user asks to set up planpage. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
client |
claude-code · codex · antigravity · other |
No | Which agent is installing it. codex installs to ~/.agents/skills; antigravity to ~/.gemini/config/skills; claude-code (the default) to ~/.claude/skills |
hand_off
Hand off to another agent. Pass work on a document to another agent, e.g. Codex to Claude Code. It shows as a comment thread addressed to that agent; the other agent takes it with wait_for_handoff and answers in the thread (read replies with get_feedback). Only agents acting for the same person receive it. An agent with the Planpage plugin is woken for it; any other agent finds it when it calls wait_for_handoff or any planpage tool, or at a Stop hook set up for handoffs.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
to |
string | No | The receiving agent's client, e.g. codex or claude-code. Any running agent of that kind can take it. |
to_session_id |
string | No | A specific session to hand to, if you know its session_id |
body |
string | Yes | What you need the other agent to do, with enough context |
block_id |
string | No | Anchor it to a block, e.g. a step id |
invite_to_workspace
Invite people to a workspace. Invite people by username (name#0042) to a team workspace this connection can write to, at a role. Each gets an inbox item (and email) to accept; only they can. Someone not on the team yet needs a free seat on it: those who don't fit aren't invited (adding seats costs money, so only a person can do it in planpage). Needs the connection to be allowed to invite people, and you to be an owner or admin there. Only do this when the user asks.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspace_id |
string | No | From whoami |
organization_id |
string | No | Old name for workspace_id, still accepted. |
people |
list of string | Yes | Usernames like name#0042 |
role |
admin · reviewer · member · viewer |
Yes |
link_ref
Link commit or PR. Attach a commit, PR, branch or URL to the plan or one of its steps.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
url |
string | Yes | |
step |
string | No | |
title |
string | No |
link_repository
Link a repository to a project. Remember which project this folder's plans go to: saves the git remote on the project so resolve_project finds it next time. Use after the user picks a project for a repository that isn't linked yet.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | Yes | |
remote_url |
string | Yes | Output of git remote get-url origin |
replace |
boolean | No | Only after the user confirms: replace a different repository already linked to the project |
list_briefs
List briefs. Work humans have queued for agents. Pick one up with pick_up_brief. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | No |
list_documents
List documents. Documents you can reach, newest first. Filter by project, kind or status. Set shared_with_me to list documents people shared directly with your user instead (outside your workspaces; read and comment only, when the connection allows it). Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | No | |
kind |
plan · report · review · adr · brief |
No | |
status |
draft · review · changes_requested · approved · in_progress · done · abandoned |
No | |
limit |
integer | No | |
shared_with_me |
boolean | No | List documents shared directly with your user |
list_handoffs
List handoffs. Handoffs other agents have addressed to you and nobody has taken yet, oldest first. Take one with wait_for_handoff (it returns at once when one is waiting). Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
project_id |
string | No | |
document_id |
string | No | |
as |
string | No | Which agent you are (e.g. codex, claude-code). Defaults to this session's client. |
list_images
List images. Images in a workspace, newest first, with their public URLs and markdown, plus how much of the workspace's storage is used. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | No | Store in this project's workspace |
workspace_id |
string | No | Or this workspace (from whoami). Omit both for your personal workspace. |
organization_id |
string | No | Old name for workspace_id, still accepted. |
before |
string | No | created_at of the last image you saw, for the next page |
limit |
integer | No |
list_projects
List projects. Projects this connection can reach, with your role in each and the workspace it's in. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspace_id |
string | No | Only this workspace's projects (from whoami) |
list_repositories
List GitHub repositories. GitHub repositories the planpage GitHub App is installed on, per workspace, most recently pushed first, each with the project already linked to it if any. Use it to suggest a repository (and its name) when creating a project, for example in a folder without a git remote. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
workspace_id |
string | No | From whoami. Omit for every workspace. |
organization_id |
string | No | Old name for workspace_id, still accepted. |
query |
string | No | Only repositories whose owner/name contains this text |
list_steps
List steps. A plan's steps with status, claims and linked commits/PRs. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes |
mentionable_people
Who can be mentioned. The people you can @mention on a document: those on its team who can open its workspace, people already on the document (author, reviewers, commenters) first. Write a mention as @username#0000 in comment, reply_comment, publish or edit_blocks; they get an inbox notification. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
query |
string | No | Only people whose name or username starts with this |
pick_up_brief
Pick up brief. Turn a brief into a plan (linked to it) and mark the brief taken.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
brief_id |
string | Yes | |
markdown |
string | Yes | |
title |
string | No | |
submit_for_review |
boolean | Yes |
publish
Publish document. Create a document, or replace an existing one's content when document_id is given. Put each :::decision and :::question right under the section, finding or step it's about, not gathered at the end (placement_hint in the result flags that). Saves a new version. To ask for review, call the submit_for_review tool next: it shows the person the document card in the chat, and publish doesn't (agents publish often). Mermaid diagrams (```mermaid fences) are checked first: if one doesn't parse, nothing is saved and the error says which diagram and why. Write @name#0042 to mention someone (see mentionable_people); people newly mentioned get an inbox notification.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
project_id |
string | No | Required when creating |
document_id |
string | No | Replace this document's content instead of creating one |
kind |
plan · report · review · adr · brief |
Yes | |
title |
string | No | Defaults to the first # heading |
markdown |
string | Yes | |
summary |
string | No | What changed in this version |
parent_id |
string | No | e.g. the plan a report or review belongs to |
base_revision |
integer | No | Fail if the document changed since this revision |
submit_for_review |
boolean | Yes | Deprecated: call the submit_for_review tool after publishing instead. It shows the person the document card to review; this flag doesn't. |
read_document
Read document. Read a document as markdown (block ids are kept on ::: blocks). On a long document, call with outline: true first to see its headings, then pass section to read just the part you need. Pass version to read an older version. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
version |
integer | No | |
section |
string | No | Only this section: a heading's text or block id (from outline), or the id of any block inside it. A section runs to the next heading at its level or above. |
outline |
boolean | Yes | Return only the headings, each with its block id, size and open comment count, instead of the content |
include_images |
boolean | Yes | Also return the document's planpage-hosted images as pictures (marks drawn on), up to 6; view_image shows one larger or zoomed to a mark |
read_document_blocks
Read document blocks. List the top-level blocks with their ids, types and text, for targeted edit_blocks calls. Pass section to list only one section's blocks. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
section |
string | No | Only this section: a heading's text or block id (from outline), or the id of any block inside it. A section runs to the next heading at its level or above. |
include_images |
boolean | Yes | Also return the document's planpage-hosted images as pictures (marks drawn on), up to 6; view_image shows one larger or zoomed to a mark |
read_share_link
Read share link. Read a public share link someone gave you (https://share.planpa.ge/s/
| Parameter | Type | Required | Description |
|---|---|---|---|
link |
string | Yes | The share link URL or token |
password |
string | No |
record_review_run
Record review run. Record a pass over a document's checklist, usually a person testing a page item by item (Planpage Capture does this from its side panel). Items that pass are ticked and the rest unticked; each item that failed or was blocked gets a comment thread with its note and screenshots. The run shows in the document's history and in get_feedback's reviewRuns. Item keys are get_feedback's widgets.checklist keys.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
items |
list of object | Yes | |
browser |
string | No | |
url |
string | No | The page that was reviewed |
started_at |
string | No | When the run started (ISO 8601) |
release_step
Release step. Give up your claim on a step.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
step |
string | Yes |
render_diagram
Render diagram. Draw a mermaid diagram as PNG images (light and dark) with permanent public URLs, without putting it in a document. Use it to show a diagram in a GitHub issue, pull request or comment: paste github_markdown, which switches with the reader's theme, or markdown for the light version. A diagram that doesn't parse comes back with mermaid's error.
| Parameter | Type | Required | Description |
|---|---|---|---|
source |
string | Yes | Mermaid source, without the ``` fence |
reply_comment
Reply to comment. Reply in a comment thread (e.g. explain how you addressed it). @name#0042 mentions someone, as in comment. images attaches screenshots, e.g. one showing the fix.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
thread_id |
string | Yes | |
body |
string | Yes | |
images |
list of object | No | Screenshots to attach (up to 6): upload each with upload_image first |
resolve_comment
Resolve comment. Mark a comment thread resolved once addressed.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
thread_id |
string | Yes | |
reopen |
boolean | Yes |
resolve_project
Find project by git remote. Match your repository's git remote URL (any of https/ssh/.git forms) to a planpage project. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
remote_url |
string | Yes | Output of git remote get-url origin |
restore_document
Restore document from Trash. Bring a document back from Trash, as it was. The same rules as trash_document apply: only documents this connection published and that were never approved.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
search
Search documents. Full-text search over plans, reports, reviews and ADRs. Search before planning to reuse earlier decisions. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | |
project_id |
string | No | |
kind |
plan · report · review · adr · brief |
No |
set_project_icon
Set project icon. Show an image as a project's icon in the planpage sidebar. Upload it with upload_image (project_id puts it in the right workspace), then pass its id; pass null to remove the icon. Needs a Publish and run connection.
| Parameter | Type | Required | Description |
|---|---|---|---|
project_id |
string | Yes | |
image_id |
string or null | Yes | |
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
set_workspace_icon
Set workspace icon. Show an image as a workspace's icon in the planpage rail, instead of its coloured letter. Upload the picture with upload_image to the same workspace first (square works best), then pass its id; pass null to go back to the letter. Needs owner or admin in that workspace and a Publish and run connection.
| Parameter | Type | Required | Description |
|---|---|---|---|
image_id |
string or null | Yes | |
workspace_id |
string | No | From whoami. Omit for your first personal workspace. |
organization_id |
string | No | Old name for workspace_id, still accepted. |
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
share_document
Share a document with people. Share one document with people by username (name#0042): view, comment or edit. People in the workspace get it on top of their role; anyone else sees only this document (a paid plan feature). Each gets an inbox item and email. Needs the connection to be allowed to share, and write access to the document. Only do this when the user asks.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
people |
list of string | Yes | Usernames like name#0042 |
role |
viewer · commenter · editor |
Yes |
show_document
Show document. Show a document to the person as an interactive card, in chats that can draw one (Claude on the web and desktop, and other MCP Apps hosts): they can read it, answer its decisions and questions, tick its checklist, comment, and approve or request changes right there. Use it when the person asks to see a document (“show me the plan”), or when you need them to look at one now. Don't call it after every edit. Elsewhere it just returns the document's summary and link. submit_for_review and ask_human show the card too; publish doesn't. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes |
start_session
Start session. Register this run so your work is attributed to it in the activity log, and get writing_guide: how to write planpage documents (blocks, examples, where decisions and questions go). Call once at the start and read the guide before you publish; pass the returned session_id to later calls. If the Planpage plugin gave you a wake_key (it says so at the start of your session), pass it: then a reviewer can send their decision straight to you, and you're woken when they do instead of having to wait.
| Parameter | Type | Required | Description |
|---|---|---|---|
label |
string | No | Short description of the task |
model |
string | No | |
client |
string | No | e.g. Claude Code, Cursor |
repo |
string | No | |
branch |
string | No | |
wake_key |
string | No | From the Planpage plugin: lets Planpage wake this session when a reviewer sends it a decision |
skill_version |
string | No | The version in your installed planpage SKILL.md's frontmatter, if you have one |
submit_for_review
Submit for review. Save a version and ask the humans to review it. Pass reviewers (usernames like name#0042, or emails, of people who can review it) to ask specific people; otherwise everyone who can review is asked.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
summary |
string | No | |
reviewers |
list of string | No | Usernames (name#0042) or emails of the people who should review |
trash_document
Move document to Trash. Move a document to Trash: it disappears for everyone (lists, search, links, agents) and is deleted for good after 30 days unless restored. Only for documents this connection published that were never approved, in a workspace where the person you act for can delete documents (their personal workspace, or as owner or admin). Only do this when the user asks, or to clean up a throwaway document you published. Undo with restore_document.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
update_step
Update step. Set a step's status (pending, doing, done, blocked) with an optional note. Requires an approved plan.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
document_id |
string | Yes | |
step |
string | Yes | |
status |
pending · doing · done · blocked |
Yes | |
note |
string | No |
upload_image
Upload image. Upload a PNG, JPEG, GIF or WebP (max 10 MB; no SVG) and get a permanent URL plus ready-to-paste markdown. By default the URL is public and works anywhere markdown images do: planpage documents, GitHub issues, PRs and comments, READMEs; anyone with it can view it. For screenshots of internal systems or anything with customer data, pass visibility: "workspace": only people in the workspace can open it (in planpage documents and comments; share links of a document in the same workspace show it too), so don't use it for GitHub. Small files (up to 2 MB): pass data_base64. Bigger files, or when you have a file path and a shell: omit data_base64 to get a single-use upload_url and a curl command that sends the file (valid 15 minutes); its response is the same image object.
| Parameter | Type | Required | Description |
|---|---|---|---|
filename |
string | Yes | e.g. screenshot.png; used for the download name |
data_base64 |
string | No | The file, base64-encoded |
alt |
string | No | Describe the image for people who can't see it |
visibility |
public · workspace |
Yes | public: anyone with the URL (GitHub, READMEs). workspace: only people who can open this workspace; use it for screenshots of internal or customer data, and for images you attach to comments |
annotations |
string | No | Marks to draw on it, one per line in the :::figure format, in the image's pixels: 1. box 312,148 220x40 red: Save is cut off, 2. arrow 80,60 -> 300,160 amber: Starts here, 3. pin 640,410: Should say "Paid". The result's figure_markdown pastes into a planpage document as an annotated figure. Only with data_base64. |
project_id |
string | No | Store in this project's workspace |
workspace_id |
string | No | Or this workspace (from whoami). Omit both for your personal workspace. |
organization_id |
string | No | Old name for workspace_id, still accepted. |
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
view_image
View image. See an image in a document or a comment as a picture, with its numbered marks drawn on (boxes, arrows, pins, redactions people added in the annotation editor), plus each mark's note and any captured element details as text. Use it on a :::figure block before acting on screenshot feedback. Pass document_id and block_id (the figure's id); document_id, comment_id and attachment for a comment's image (get_feedback lists them); or image (a planpage image URL or id) for one outside a document. mark zooms to the area around one numbered mark; region crops (in the image's own pixels). variant "original" shows the image without marks, "both" returns both pictures. Pictures are PNG, at most 1568px on the long edge unless max_size is smaller. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | No | |
block_id |
string | No | The image block's id: the id on its :::figure line, or from read_document_blocks. Optional when the document has one image. |
image |
string | No | A planpage image URL or id (instead of block_id) |
comment_id |
string | No | An image attached to this comment (commentId from get_feedback), with document_id |
attachment |
integer | Yes | Which of the comment's images, from 1 |
variant |
annotated · original · both |
Yes | |
mark |
integer | No | Zoom to the area around this numbered mark |
region |
object | No | Crop to this rectangle, in the image's pixels |
max_size |
integer | No | Longest edge of the returned picture, in px |
wait_for_handoff
Wait for a handoff. Take the oldest handoff addressed to you, waiting up to timeout_seconds for one to arrive. Returns at once when one is already waiting; it's then yours and no other agent gets it. Do the work, then answer with reply_comment on its handoff_id and resolve_comment when it's done. Keep timeout_seconds under your client's tool-call timeout (Codex's default is 60 seconds). After two empty waits, stop and tell the user; the handoff stays queued.
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id |
string | No | The session_id from start_session. Omit to use this connection's current session. |
project_id |
string | No | |
document_id |
string | No | |
as |
string | No | Which agent you are (e.g. codex, claude-code). Defaults to this session's client. |
timeout_seconds |
integer | Yes |
wait_for_review
Wait for review. Block until the document is reviewed, commented on or edited, or until timeout_seconds pass. A reviewer picking options or answering questions mid-review doesn't end the wait; those count once they approve or request changes. Returns get_feedback's result (narrowed by section if given) and whether anything changed. Keep timeout_seconds under your client's tool-call timeout (Codex's default is 60 seconds). Prefer stopping and resuming later for long reviews; with the Planpage plugin (start_session got a wake_key) just stop, and you're woken when the reviewer sends you their decision. Read only.
| Parameter | Type | Required | Description |
|---|---|---|---|
document_id |
string | Yes | |
timeout_seconds |
integer | Yes | |
section |
string | No | Only this section: a heading's text or block id (from outline), or the id of any block inside it. A section runs to the next heading at its level or above. |
whoami
Who am I. Show this connection, its access level, and the workspaces it can reach, grouped by team (with the workspace_id create_project needs), even ones with no projects yet. Read only.
No parameters.
Prompts
The server also offers two prompts, "Plan a task in planpage" and "Address review feedback", described in The planpage skill.