fmrl

Edit a fmrl.site page

fmrl_edit

Saves new content as the next revision of an existing page and checks base_rev, preventing overwrites when a newer revision exists.

Instructions

Save new content to an existing page as its next revision; earlier revisions stay readable through fmrl_get's rev. To make a new page use fmrl_publish, and to change who can read a page use fmrl_set_visibility. Pass base_rev (the rev you read): if someone saved a newer revision meanwhile, nothing is saved and the answer gives latest_rev to read first. Works on pages this key owns and on any page whose management token you were given (pass the page URL as id and the token or recovery link separately as manage_token). A private page stays private under its same key, so every existing link keeps opening it; public content carrying a recognizable credential is refused. Editing watches the page: revisions other editors make afterwards show up in fmrl_inbox, with no fmrl_watch call.

Input Schema

Name	Required	Description
`id`	Yes	A page id or page URL, optionally with its private key (#p=). Supply recovery separately as manage_token.
`title`	No	Page title; for a private page it titles the encrypted document only.
`format`	No	html or md; leave out to let the server detect it, or, with content_file, to take it from the extension. A private page is always sent as HTML, rendered here from Markdown.
`content`	No	The page's new HTML or Markdown: 2 MiB at most on a public page, roughly 1.4 MB on a private one. Give this or content_file, not both.
`base_rev`	No	The revision you read and are editing from; the edit fails if someone saved a newer one.
`content_file`	No	Read the new content from this page's own file instead, so a large page never passes through the model: write it with fmrl_get's to_file, edit the file, save it from there. Only <id>.md or <id>.html (or .htm, .markdown, .mdx, .txt) in the fmrl folder (~/fmrl unless FMRL_FILES_DIR says otherwise) is read, where <id> is this page's id: give its file name or its full path. 2 MiB at most.
`manage_token`	No	A 22-character recovery token or /c/<token> link for this page. It grants management, not deletion, and is used only with the edit.

Output Schema

Name	Required	Description	Default
`id`	Yes
`rev`	No
`url`	No
`watching`	No
`latest_rev`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.17.8Nov 9, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
- addedInput schema / properties / base_rev / maximum
```
Added value: +9007199254740991
```
First observedv0.17.6Nov 9, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say it is a non-idempotent, non-destructive, open-world write. The description adds what the annotations cannot: conflict behavior on base_rev, the privilege model (owning key or management token), privacy preservation ('a private page stays private under its same key, so every existing link keeps opening it'), refusal of public content carrying a credential, and the auto-watch side effect that replaces an fmrl_watch call.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action, then the alternatives, then the concurrency rule, then the side effect. Every sentence carries distinct information, though the ownership/token sentence is packed with several ideas that could be split for easier scanning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation tool with an output schema already published, the description covers everything an agent needs: identity resolution, conflict handling, permission scope, privacy behavior, and the implicit watch side effect. No reliance on inference for call correctness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: base_rev is defined as 'the rev you read' with the optimistic-concurrency consequence ('nothing is saved and the answer gives latest_rev'). The manage_token/id pairing (pass the page URL as id, token separately) is also clarified. Slight overlap with schema text keeps it from a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening clause states a specific verb and resource ('Save new content to an existing page as its next revision') and immediately names the two siblings that cover adjacent operations (fmrl_publish for new pages, fmrl_set_visibility for readership). An agent can distinguish this tool from its siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes: new page -> fmrl_publish, change readers -> fmrl_set_visibility, and this tool for a new revision. It also states the ownership condition ('pages this key owns' or a management token) that gates callability, which is the key when-to-use criterion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server