A remote MCP server that lets Claude/ChatGPT publish the HTML they generate to a private, unguessable miinideck link (create / update in place / list), no deploy step.
Scored across 9 tools
Most tools are crisply separated: create/update/get/delete/restore_page each map to one lifecycle action, and prepare_upload/finish_upload are a clearly-sequenced pair. The one overlap is create_page vs. the prepare_upload→finish_upload path, since both publish a new page; the descriptions disambiguate strictly by size/type (~100 KB boundary) but an agent still has to apply that rule to pick correctly.
Every tool follows a consistent snake_case verb_noun pattern (create_page, list_pages, update_page, delete_page, restore_page, get_page, list_projects, prepare_upload, finish_upload). The verbs are used consistently for the same semantic operation across resources.
Nine tools is well-scoped for a page-publishing server, with no filler. Each tool earns its place, including the two-step large-file upload flow and the trash/restore pair.
Full page lifecycle is covered: create, list, get, update, soft-delete, restore, plus batch vs. large-file publishing and project listing. Minor gaps exist — no way to create/rename/delete projects explicitly, no permanent purge, no access to the 30-day version history — but agents can work around all of these.
Publish an HTML document to a private, unguessable miinideck link and return the shareable URL. Use this whenever the user wants to share, publish, host, send, or get a link for an HTML page, report, slide deck, or artifact you produced. Pass the COMPLETE, self-contained HTML document (including ) as html. Optionally file it under a project by name with project (call list_projects first to see existing ones). SIZE LIMIT: this tool carries the whole document as a text argument, so it only fits pages you can output in one response — roughly under ~100 KB. For a LARGER file (or a ZIP / PDF / image), do NOT call this tool (the HTML would be truncated): if you can run shell commands, use prepare_upload → curl → finish_upload, which send the file's real bytes with no text-size limit; otherwise tell the user to upload it with the miinideck CLI (npx miinideck deploy <path>) or the web uploader at miinideck.com.
| Name | Required | Description | Default |
|---|---|---|---|
| html | Yes | The complete, self-contained HTML document to publish. | |
| title | No | Optional human title shown in the owner's dashboard. | |
| expiry | No | When the link expires. Default 'never' (Free tier falls back to 7 days unless an always-on slot is free). | |
| project | No | Optional project (folder) to file this page under, BY NAME. Matches one of the user's existing projects case-insensitively, or creates a new project with this name if none matches. Omit to use the default Inbox. | |
| password | No | Optional password a viewer must enter to open the page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does much of it: it discloses the privacy model (unguessable link), the hard size limit (~100 KB) and the concrete failure mode (truncated HTML), which is exactly the kind of behavioral trait an agent would otherwise discover by damaging output. It stops short of stating auth/plan constraints (beyond the schema's Free-tier expiry note) or what happens on partial failure, so not a full 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded correctly: purpose, then trigger conditions, then parameter guidance, then the size constraint and fallback path. The size-limit paragraph is long, but nearly every clause is load-bearing (limit value, failure mode, ordered fallbacks). Slight over-length keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description compensates by naming the return value (the shareable URL). Combined with full schema coverage and explicit escalation paths for oversized inputs, an agent has everything needed to decide and call correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline would be 3; the description adds real meaning beyond the schema by insisting on a COMPLETE self-contained document with <!doctype html>, and by telling the agent to call list_projects before using `project` by name. It does not elaborate on `expiry` or `password`, but those are already well-described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Publish an HTML document") plus the outcome ("private, unguessable miinideck link") and the return value ("shareable URL"). It is clearly separable from siblings: prepare_upload/finish_upload are named as the path for larger files, and list_projects is referenced for the project parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit positive trigger ("whenever the user wants to share, publish, host, send, or get a link for an HTML page, report, slide deck, or artifact") and an explicit negative case (files over ~100 KB, ZIP/PDF/image — "do NOT call this tool"). It also routes to concrete alternatives (prepare_upload → curl → finish_upload, the miinideck CLI, or the web uploader).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Move one of your published pages to Trash. This takes the page OFFLINE immediately — its private link stops working right away. It is RECOVERABLE, not a permanent delete: the page sits in the owner's miinideck dashboard Trash and can be brought back with restore_page (until it is later permanently purged from Trash). Because this unpublishes a link the user may have already shared, CONFIRM with the user before calling — name the page you're about to delete and wait for a clear yes. Identify the page with page (its viewer URL or slug, e.g. from list_pages). You can only delete your own pages.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | The page's viewer URL or its slug (the part after the last '/'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does it well: it discloses the immediate side effect (page goes OFFLINE, private link breaks instantly), reversibility via Trash and restore_page, that this unpublishes an already-shared link, and the authorization constraint. That is exactly the context an agent needs before invoking a destructive-looking action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and the offline consequence, then recovery, then the confirmation gate. Slightly verbose with capitalized emphasis and a parenthetical about purging, but every clause carries relevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter mutation with no output schema and no annotations, the description covers side effects, reversibility, confirmation protocol, ownership restriction, and identifier sourcing. Nothing material an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single parameter already documents 'viewer URL or slug (the part after the last /)'. The description largely restates it; the only added value is the provenance hint 'e.g. from list_pages'. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Move one of your published pages to Trash' — and immediately distinguishes it from a permanent delete and from restore_page. An agent can tell it apart from update_page or restore_page 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when to use it, gives a hard pre-condition ('CONFIRM with the user before calling — name the page ... and wait for a clear yes'), names the recovery sibling restore_page, points to list_pages for obtaining the identifier, and states the ownership limit ('only delete your own pages').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish the file you just sent with curl after prepare_upload. Pass the ticket prepare_upload gave you. Returns the private link (the SAME link if you passed page to prepare_upload). If it says the file wasn't found, the curl step did not succeed or took too long — run prepare_upload again for a fresh ticket and re-send.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Optional title for a NEW page. A replaced page keeps its existing title. | |
| expiry | No | Optional expiry for a new page. Default 'never' (Free tier falls back to 7 days unless an always-on slot is free). | |
| ticket | Yes | The ticket from prepare_upload, exactly as given. | |
| project | No | Optional project (folder) BY NAME for a new page; created if it doesn't exist. | |
| password | No | Optional viewer password for a new page. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the return value (private link), link identity when replacing a page, and the meaning of a 'file not found' error. However, it does not cover permissions, side effects of publishing, or whether a replacement overwrites existing content.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action, then adds workflow context and error recovery. Every sentence is relevant, and there is no redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, it describes the workflow, required ticket, return link, and failure recovery well. It is nearly complete, though it could say more about permissions or replacement side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters in detail. The description reinforces the ticket relationship to prepare_upload but adds little beyond the schema for title, expiry, project, and password.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Publish the file you just sent with curl after prepare_upload.' It clearly places the tool as step 3 of the upload workflow and distinguishes it from prepare_upload, which must already have run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context: call this after prepare_upload and after sending the file with curl, passing the ticket. It also names the recovery path when the file is not found. It does not state when not to use it versus alternatives like create_page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the details of a single published page: its title, private link, total view count, when it was created, when it expires (or 'never'), whether it's searchable, whether it's password-protected, and which project it's filed under. Use this to answer questions like 'how many views does my page have?' or to check a page's current settings before changing them. Identify the page with page (its viewer URL or slug). You can only read your own pages.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | The page's viewer URL or its slug (the part after the last '/'). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reasonably well: "Fetch" plus the settings-inspection framing makes the read-only nature clear, and "You can only read your own pages" is a genuine authorization constraint not otherwise encoded. It does not state what happens for a nonexistent, deleted, or restored page (relevant given delete_page/restore_page siblings).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then purpose, then parameter guidance; every sentence has a function. The returned-field enumeration is a long comma-separated run that borders on a list dump but is justified because no output schema exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Since there is no output schema, spelling out the returned fields is exactly the right compensation, and the ownership restriction plus param identification cover what is needed to call it. Missing only edge-case behavior (page not found, unpublished/trashed pages) for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema itself explains "the part after the last '/'", so the description's restatement of the `page` parameter (viewer URL or slug) adds no meaning beyond structured data. Baseline 3 applies since the schema does the heavy lifting for the single required param.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ("Fetch the details of a single published page") and then enumerates exactly which attributes come back, so the agent knows precisely what this returns. It is clearly distinguishable from list_pages (many) and update_page (mutation) among the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete usage triggers ("how many views does my page have?" and checking settings "before changing them"), which implicitly routes to update_page for the mutation case. It stops short of explicitly naming update_page or list_pages as alternatives/exclusions, so the routing is inferential rather than declared.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the miinideck pages the signed-in user has published — each with its private link and current status: when it expires (or 'never expires'), whether it's searchable by search engines, and whether it's password-protected. Call this to find a page's URL/slug (and see its state) before update_page, delete_page, get_page, or restore_page.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the disclosure burden and does well: it scopes results to the signed-in user's published pages and describes the per-page fields returned, including the 'never expires' case. It leaves ordering, result-set size/pagination, and any auth failure behavior unstated, which matters for a list call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the verb and scope, then the routing advice. The listing of status fields is dense but justified because there is no output schema to carry it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters and no output schema, the description correctly compensates by describing the returned per-page state. The remaining gaps are operational: whether the list is paginated, how it is ordered, and whether unpublished or trashed pages can appear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly adds no parameter talk that would confuse the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the miinideck pages the signed-in user has published') plus the exact scope (signed-in user, published only), which cleanly separates it from list_projects and from the single-page get_page. It also enumerates what each entry carries (private link, expiry, searchability, password protection).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent: call this to obtain a page's URL/slug before update_page, delete_page, get_page, or restore_page — naming four siblings as alternatives. It stops short of the inverse condition (skip listing when the slug is already known) and doesn't say how to narrow the list, so it falls one step short of a full when/when-not treatment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the projects (folders) the signed-in user can file pages under. Call this before create_page when the user wants to choose a project, so you can pass an exact existing name as create_page's project argument.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the burden, and it does disclose the result scope: only projects the signed-in user can file pages under, which implies permission filtering rather than a global list. It does not state ordering, whether archived projects are included, or whether the list can be empty, which are the remaining behavioral gaps for a zero-param read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, with the resource definition front-loaded and the call-order instruction second. Every clause earns its place by either defining the resource or routing the agent to the follow-up tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-param, read-only listing with no output schema, the description covers purpose, scope, and sequencing, and implies the response contains project names. It stops short of describing the returned fields beyond names, which is the only thing an agent might still want to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, so the baseline is 4; the description still adds cross-tool semantics by naming create_page's `project` argument as the downstream consumer of the returned names. That linkage is value the empty schema cannot provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb plus resource ("List the projects") with an immediate disambiguation that projects are folders used to file pages. This cleanly separates it from the sibling list_pages, which enumerates a different resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call it ("before create_page when the user wants to choose a project") and why (to pass an exact existing name). The alternative path — skipping this and guessing a project name — is implicitly ruled out by the word "exact".
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Publish or replace a file TOO BIG to pass as text to create_page / update_page (anything over ~100 KB, or a ZIP / PDF / image). Requires that you can run shell commands (to run curl) and read the file from disk. Three steps: (1) call prepare_upload — it returns a one-time upload URL, a ready curl command and a ticket; (2) run that curl command in your shell, replacing @FILE with the path to the file (it sends the file's raw bytes, so there is no size limit beyond the plan's file cap); (3) call finish_upload with the ticket to publish. To UPDATE a page you already published and keep its SAME link, pass page (its viewer URL or slug); omit page to make a new link. If curl cannot reach the upload URL (no network access from your sandbox), tell the user to upload with the miinideck CLI (npx miinideck deploy <path>) or the web uploader instead — do not retry with create_page.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Optional. The viewer URL or slug of a page you own, to replace its content in place (same link). Omit to create a new page. | |
| title | No | Optional readable label used when making a NEW link. Ignored when `page` is set. | |
| file_kind | Yes | What the file is: 'html' (one HTML file), 'zip' (a multi-file site as a ZIP), 'pdf', 'png' or 'jpeg'. | |
| size_bytes | Yes | The file's exact size in bytes (e.g. from `wc -c`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it discloses the multi-step contract: a one-time upload URL, a generated curl command, a ticket consumed by finish_upload, raw-byte transfer with no size limit beyond the plan cap, and the sandbox-network failure mode. Gaps remain: no statement of auth/permission requirements, ticket lifetime or expiry, or what happens if step 2 is interrupted and retried.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The gating condition (file too big, needs shell) is front-loaded before the numbered steps, and every sentence carries operational weight. It is on the long side for a tool description, with some overlap between the 'three steps' recap and the parameter notes, but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema and no annotations, the description fully specifies what prepare_upload returns (URL, curl command, ticket), how it chains to finish_upload, and what to do on failure. For a stateful three-call workflow tool, an agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters including the page/title interaction and the enum values. The description restates the page semantics in workflow terms ('keep its SAME link'), which is mildly useful framing but adds little beyond the schema text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('publish or replace a file too big to pass as text') and immediately positions it against siblings create_page/update_page and its partner finish_upload. An agent can classify this tool without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit trigger conditions (>~100 KB, ZIP/PDF/image, shell access required), an ordered three-step procedure, and a when-not path ('if curl cannot reach the upload URL... do not retry with create_page') with named alternatives (miinideck CLI, web uploader). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bring a page back from Trash (the inverse of delete_page) — its private link starts working again. Identify the page with page (its viewer URL or slug). Only works while the page is still in your Trash; a page that has already been permanently purged can't be restored. You can only restore your own pages.
| Name | Required | Description | Default |
|---|---|---|---|
| page | Yes | The viewer URL or slug of a page currently in your Trash. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses the side effect (private link becomes active again), the state precondition (currently in Trash), the hard failure case (permanently purged pages cannot be restored), and the ownership restriction. These are exactly the constraints an agent could otherwise trip over.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and its inverse, followed by identification and constraints. Every sentence adds information; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter mutation tool with no annotations or output schema, the description covers the essential mechanics and preconditions. It is slightly thin on what the call returns or how failure is signalled (e.g., an error for purged pages), which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema description already says 'viewer URL or slug of a page currently in your Trash'. The description restates the same accepted formats without adding syntax, examples, or edge-case guidance, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Bring a page back from Trash') and anchors it against a sibling by calling it 'the inverse of delete_page'. An agent can distinguish it from delete_page, get_page, and update_page immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear preconditions for use: the page must still be in Trash, must not be purged, and must belong to the caller. It names the inverse operation but does not explicitly route to an alternative tool for other cases, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Change a page you already published, keeping the SAME private link. Use this whenever the user wants to update, edit, revise, fix, re-publish, rename, re-file, password-protect, or change the expiry of a page you previously created — do NOT call create_page for any of that, which would mint a new throwaway link. Identify the page with page (its viewer URL or slug, e.g. from create_page or list_pages). Every change field is optional and independent: pass only what you want to change, and anything you omit is left exactly as-is. You must pass at least one of html, title, password, expiry, or project. html swaps the content as a new version (the previous version stays in the 30-day history). password sets a viewer password, or pass an empty string "" to REMOVE the password — note a searchable page can't take a password. expiry is one of '1d' | '7d' | '30d' | 'never' ('never' pins the page always-on; the Free tier is limited to '7d' or 'never', and on Free '7d' only takes a page off always-on, where it resumes the countdown it had when it was pinned — it never extends a page that is already counting down or revives an expired one). title renames it; project re-files it under a project by name (created if it doesn't exist). SIZE LIMIT: the html argument travels as text (roughly under ~100 KB). For a larger content swap, don't use this tool: if you can run shell commands, call prepare_upload with page set to this page, curl the file, then finish_upload — that replaces the content and keeps the SAME link; otherwise tell the user to re-upload with the miinideck CLI or the web uploader.
| Name | Required | Description | Default |
|---|---|---|---|
| html | No | Optional. The complete, self-contained HTML document (including <!doctype html>) to publish as the new version. Omit to leave the content unchanged. | |
| page | Yes | The page's viewer URL or its slug (the part after the last '/'). | |
| title | No | Optional new title shown in the owner's dashboard. Pass an empty string to clear it. Omit to leave unchanged. | |
| expiry | No | Optional new expiry. 'never' pins the page always-on. Free tier may only pick '7d' or 'never'; on Free, '7d' can't extend a page that is already counting down. Omit to leave unchanged. | |
| project | No | Optional project (folder) to move this page under, BY NAME. Matches an existing project case-insensitively, or creates a new one. Omit to leave unchanged. | |
| password | No | Optional. Set a viewer password, or pass an empty string "" to remove an existing one. Rejected if the page is searchable. Omit to leave unchanged. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses link preservation, version-history behavior for html, password removal semantics, searchable-page restrictions, expiry tier nuances, project creation, and a size limit with a fallback workflow. It also implies ownership by specifying a page the user already published.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and logically structured: purpose, sibling routing, parameter constraints, then size-limit fallback. It is long and restates some schema parameter details, especially around password and project, which keeps it from being maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a six-parameter mutation tool with no annotations and no output schema, the description covers the essential invocation context: when to use it, field independence, the at-least-one-field rule, side effects, size limits, and the correct fallback for larger uploads. No significant invocation detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 important meaning beyond the schema: at least one of html, title, password, expiry, or project must be supplied, and omitted fields remain unchanged. It also adds version-history behavior and Free-tier expiry nuance, though some password and project details are already present in the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: changing an already-published page while keeping the same private link. It explicitly distinguishes this from create_page, so an agent can select it without opening the sibling schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance and an explicit when-not-to-use rule: do NOT call create_page for updates, edits, renames, re-filing, password changes, or expiry changes. It also names prepare_upload and finish_upload as the correct alternative for large HTML replacements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.