Sumibako

Write a page

write_page

Idempotent

File a Markdown document into the user's vault as a page, creating it or updating an existing one. This replaces the whole page, so use edit_page instead to change part of one. Returns the page and a link to it. Set externalId to a stable key for this artifact, such as the source file's path in the repository, so that writing it again updates the same page rather than adding a second copy. The previous version is kept for 14 days and the owner can restore it.

Input Schema

Name	Required	Description
`icon`	No	One emoji, shown beside the title in the sidebar and above it on the page. Always choose one that fits the document - a map for a plan, a scale for a decision, a handshake for a handoff, a microscope for research - even when the user did not ask. A new page sent without one gets a guess from its title; an existing page keeps the icon it has.
`cover`	No	The banner across the top of the page, by name. Choose one that suits the document when you create a page. One of: brush (one ink brush stroke on paper), blue-hour (blue mountains under a moon), contours (a contour map on paper), flow (dark flowing lines with amber threads), mist (grey ridges in mist), sundown (amber ridges at sunset), garden (a raked sand garden with stones), stars (constellations on a night sky), enso (an ink circle on paper), ridges (white ridgelines on black), doodles (small doodles on paper), doodles-night (the same doodles on black), boxes (white cubes, a few in black and amber), stitch (indigo cloth with white stitching), dawn (a soft gradient, sky blue to peach), dusk (a deep gradient, blue to violet and red). Or "none" for no cover. A new page sent without one gets a banner picked from its title; an existing page keeps the cover it has, and a picture the owner uploaded is never replaced.
`title`	No	Optional. Defaults to a title in the Markdown's frontmatter, else its leading level-one heading. With neither, a new page is called Untitled and an existing page keeps the title it has.
`access`	No	Optional. "passcode" puts the page on the web behind a six-character passcode, returned in the result, which the user sends along with the link. "anyone" opens it to anyone with the link. Omit to keep the page at the level it has - a page behind a passcode is never opened up unless you send "anyone", and only do that when the user asks.
`project`	No	The repository or project this artifact belongs to, such as the repository's name. Send the same one every time. A key is unique within its project, and a new page is filed in the project's own folder. Leave it out only for work that belongs to no project.
`publish`	No	Optional. True also puts the page on the web and returns publicUrl. Omit to leave the page's current visibility alone. A connected app can set this on a page it wrote, not on one the user made in the app.
`markdown`	Yes	The page body, in Markdown. Headings, lists, tables, task lists, quotes, code blocks, links, images and dividers are kept. Anything else degrades to its own text and is named in warnings.
`documentId`	No	Optional. Update this exact page, using an id an earlier call returned. Takes precedence over externalId.
`externalId`	No	A stable key for this artifact, unique within its project. Strongly recommended: without it, writing the same document twice leaves two pages.
`newPasscode`	No	Optional. True replaces the passcode with a new one, so the old one stops working everywhere. Only for a page behind a passcode.
`parentDocument`	No	Optional. File a new page underneath this one. Ignored when updating.

Output Schema

Name	Required	Description
`url`	Yes	Where the owner reads it, signed in.
`icon`	No	The emoji beside the title.
`cover`	No	The banner across the top of the page, by name. "uploaded" when it is a picture the owner put there.
`title`	Yes
`access`	No	Who can open the shareable link: anyone who has it, or only somebody who also has the passcode.
`created`	No
`passcode`	No	The passcode the link needs, when access is passcode. Give it to the user exactly as written, alongside the link.
`warnings`	No
`publicUrl`	No	The shareable link, when the page is published.
`documentId`	Yes
`isPublished`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 29, 2026

changedInput schema / properties / externalId / description

Previous value: -"A stable key for this artifact, unique within the vault. Strongly recommended: without it, writing the same document twice leaves two pages."New value: +"A stable key for this artifact, unique within its project. Strongly recommended: without it, writing the same document twice leaves two pages."

addedInput schema / properties / project

Added value: +{
+  "description": "The repository or project this artifact belongs to, such as the repository's name. Send the same one every time. A key is unique within its project, and a new page is filed in the project's own folder. Leave it out only for work that belongs to no project.",
+  "type": "string"
+}

First observedOct 14, 2026

TDQS

A4/5.0

Behavior3/5

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

Goes well beyond the annotations by disclosing that the whole page is replaced but the prior version is retained for 14 days and restorable, that a passcode is returned in the result, that markdown constructs degrade into warnings, and that a user-uploaded cover is never replaced. However, the replacement semantics sit uncomfortably beside destructiveHint=false; the description mitigates this with the restore window but never explicitly reconciles the two.

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-loaded with purpose, then the edit_page exclusion, then the return value and the externalId rule, so the highest-value information arrives first. Five dense sentences with no filler, though the externalId sentence overlaps the schema text and could have been trimmed.

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

Completeness3/5

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

An output schema exists and the description still notes the return value and link, and annotations cover the safety profile, so coverage is largely adequate for an 11-parameter mutation tool. The remaining gap is the tension between whole-page replacement and destructiveHint=false, which an agent calling this destructively would want resolved.

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

Parameters3/5

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

Schema coverage is 100% and every parameter already carries a rich description, so the schema does the heavy lifting; baseline is 3. The prose adds one useful example (externalId as the source file path in the repository) but otherwise repeats what the schema states.

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?

States a specific verb and resource ("File a Markdown document into the user's vault as a page") plus the scope of the operation (create-or-update). It also names the sibling it is not ("use edit_page instead to change part of one"), so an agent can route between the two without opening either 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?

Gives an explicit when-not with the alternative named (whole-page replacement vs. edit_page), and adds conditional guidance for the risky parameters: only send "anyone" when the user asks, and leave access/publish out to preserve current visibility. The externalId advice (use the source file path so rewrites update rather than duplicate) is actionable usage guidance, not just a restatement.

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

All Sumibako tools Inspect

Try in Browser

Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?