Pages

Create, read and rewrite HTML page artifacts under a required version check.

Tool	Scope	Kind
`create_page`	`documents:write`	write
`read_page`	`documents:read`	read-only
`write_page`	`documents:write`	write, destructive

create_page

Scope: documents:write (step-up) · Kind: write · Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false

Create an HTML page artifact — in a conversation (conversation_id, its card is posted to the room) or in the person’s library with a scope: user (private, the default), pod (needs pod_id), or org. The HTML is stored verbatim; scripts are stripped when the page is viewed, and you are warned when that will happen. Returns — the version write_page requires.

Parameters

Pass either conversation_id or scope (with pod_id when the scope is pod), never both.

string

required

string

required

The page’s HTML, stored verbatim. Must be non-empty.

string

Create inside this conversation; a card is posted to the room.

'user' | 'pod' | 'org'

default:"user"

Where the page lives when no conversation_id is given.

string

Required with scope: "pod".

Returns

string

The artifact id. Use it as page_id for read_page and write_page, and as document_id for comments and export.

string

number

The version write_page must pass as expected_version.

number

string[]

["script_stripped"] when the HTML contains <script> elements, inline event handlers or javascript: URLs. They are stored but removed when the page is viewed, so its interactivity will not run.

Text: Created page "<title>" (page_id: <id>, version <n>). plus Note: its scripts will be stripped when viewed. when applicable.

Permissions and side effects

Needs documents:write.
The access gate runs inside the create transaction: with conversation_id you must be able to participate in the room; with scope: "pod" you must be a pod member.
The caller becomes the owner. With conversation_id a card lands in the room; with a scope nothing is posted.

Errors

Text	Cause
`Tool failed: Pass either \`conversation_id` or `scope`, not both`	Both targets given
`Tool failed: \`pod_id` is required for scope pod`	Pod scope without a pod
`Tool failed: … Artifact not found`	Conversation or pod you cannot reach
`That conversation is archived or gone, so nothing was created.`	Archived room

Limitations

No idempotency key on this tool; a retried create makes a second page.
Pages are served with scripts stripped. Style with inline CSS.

Example

Request

{
  "name": "create_page",
  "arguments": {
    "scope": "user",
    "title": "Acme rollout timeline",
    "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — November</li></ol>"
  }
}

Response (structuredContent)

{
  "page_id": "k55timeline0example000000000000000",
  "title": "Acme rollout timeline",
  "version": 1,
  "byte_size": 104,
  "warnings": []
}

read_page

Scope: documents:read (step-up) · Kind: read-only · Annotations: readOnlyHint: true, destructiveHint: false, openWorldHint: false

Read a page’s stored HTML source and its version — the token write_page’s expected_version is checked against.

Parameters

string

required

The page’s artifact id.

Returns

string

The stored source, scripts included (they are stripped only at view time).

number

Pass as expected_version to write_page.

Text: # <title> (version <n>) followed by the HTML.

Permissions and side effects

Needs documents:read and any role on the page. The access check and the source read happen in one transaction.
Reads only. Recorded in the agent activity history.

Errors

Text	Cause
`That artifact is a document, not an HTML page — use read_document.`	The id names a document or table
`That page has no content yet.`	The page exists but has no stored source
`Tool failed: … Artifact not found`	Not visible, wrong workspace or no such id

Example

Request

{ "name": "read_page", "arguments": { "page_id": "k55timeline0example000000000000000" } }

Response (structuredContent)

{
  "page_id": "k55timeline0example000000000000000",
  "title": "Acme rollout timeline",
  "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — November</li></ol>",
  "version": 1
}

write_page

Scope: documents:write (step-up) · Kind: write, destructive · Annotations: readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false

Replace a page’s HTML wholesale. expected_version is REQUIRED — the version read_page (or create_page) returned. If the page moved since your read, the write refuses with the current version and a line-level diff of what changed, so you can merge and retry; there is no force flag, by design. Scripts are stored but stripped at view.

Parameters

string

required

string

required

The complete new HTML. Must be non-empty.

number

required

The version read_page or create_page returned. Must be a non-negative integer.

Returns

string

number

string[]

["script_stripped"] when the HTML carries scripts.

Text: Wrote the page; it is now at version <n> (<bytes> bytes).

Permissions and side effects

Needs documents:write and the editor or owner role. The role is re-checked inside the write transaction.
Replaces the whole page. The previous source is kept as a checkpoint.
Attributed to you via the host.

Errors

`error`	Text (abridged)	What to do
—	`Tool failed: \`expected_version` must be a non-negative integer`	Pass the integer from your read
—	`That artifact is a document, not an HTML page — use edit_document.`	Use `edit_document`
—	`That artifact is a table, not an HTML page. …`	Tables are not editable
`version_conflict`	`The page moved from version A to B since you read it. What changed:\n<diff>\nMerge your changes onto the current page (read_page) and write again with expected_version B.`	Merge and retry; `diff_excerpt` and `changed_range` are included when available
—	`Tool failed: … This document is read-only for you`	You are a viewer
—	`Tool failed: … You can comment on this document but not edit it`	You are a commenter
—	`Tool failed: … This document is archived`	Archived
—	`Tool failed: … Artifact not found`	Not visible, wrong workspace or no such id

There is deliberately no way to overwrite a newer version without reading it first.

Example

Request

{
  "name": "write_page",
  "arguments": {
    "page_id": "k55timeline0example000000000000000",
    "expected_version": 1,
    "html": "<h1>Acme rollout</h1><ol><li>Sandbox — September</li><li>Pilot — October</li><li>GA — December</li></ol>"
  }
}

Response (structuredContent)

{
  "page_id": "k55timeline0example000000000000000",
  "new_version": 2,
  "byte_size": 103,
  "warnings": []
}

Conflict response (structuredContent)

{
  "error": "version_conflict",
  "expected_version": 1,
  "current_version": 3,
  "diff_excerpt": "-<li>GA — November</li>\n+<li>GA — 2 December</li>"
}

Get started

Use it

Reference

create_page

Parameters

Returns

Permissions and side effects

Errors

Limitations

Example

read_page

Parameters

Returns

Permissions and side effects

Errors

Example

write_page

Parameters

Returns

Permissions and side effects

Errors

Example

​create_page

​Parameters

​Returns

​Permissions and side effects

​Errors

​Limitations

​Example

​read_page

​Parameters

​Returns

​Permissions and side effects

​Errors

​Example

​write_page

​Parameters

​Returns

​Permissions and side effects

​Errors

​Example

create_page

Parameters

Returns

Permissions and side effects

Errors

Limitations

Example

read_page

Parameters

Returns

Permissions and side effects

Errors

Example

write_page

Parameters

Returns

Permissions and side effects

Errors

Example