Skip to main content
Glama

Make pages, put them in order, or take one out

page_doc
Idempotent

Hang a document under another as a page, or with no page_of take a page back out to its old folder. A page goes everywhere with its document.

Instructions

Hang a document under another as a page, or with no page_of take a page back out to its old folder. A page goes everywhere with its document. Hanging writes the line naming it at the document's end, or where after, before or at say; taking out leaves the line for you to remove. order reorders a document's pages. Reading order is line order, each line ![Its title](tisty:doc/its-id), bang included.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "page_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
atNoBefore or after every page line, for when there is no page to name
docNoThe id of the document to hang or take out, not its title, or a list of ids: if one cannot, none moves
afterNoId of another page of that document, whose line this one's goes right after. Needs `page_of` and one `doc`, and that page needs a line
orderNoIts pages' ids, two or more, each once, in reading order: their lines trade places, nothing else moves. With `page_of` alone; each needs a line
beforeNoThe same, right before
page_ofNoId of the document it becomes a page of

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.47.1
    • changedInput schema / properties / page_of / description
      Previous value: -"Id of the document it becomes a page of. Left out, it becomes a document of its own"New value: +"Id of the document it becomes a page of"
  2. Changed6 schema fields changedv1.43.2
    • changedInput schema / properties / after / description
      Previous value: -"The id of another page of that same document. The line naming this page is written straight after the line naming that one, which is what puts it next in reading order. Needs `page_of`, takes one `doc`, and the page you name has to have a line already"New value: +"Id of another page of that document, whose line this one's goes right after. Needs `page_of` and one `doc`, and that page needs a line"
    • changedInput schema / properties / at / description
      Previous value: -"Where to write the line when you are not naming a page to sit beside: \"first\" puts it before every page the document names, \"last\" after them all. It is what to send for a document whose pages no line names yet, since there is no page there to name"New value: +"Before or after every page line, for when there is no page to name"
    • changedInput schema / properties / before / description
      Previous value: -"The same, on the other side: the line goes straight before the one naming this page"New value: +"The same, right before"
    • changedInput schema / properties / doc / description
      Previous value: -"The id of the document to hang or to take out, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title. A list of ids does the same to all of them in one go, and if one of them cannot, none of them moves."New value: +"The id of the document to hang or take out, not its title, or a list of ids: if one cannot, none moves"
    • changedInput schema / properties / order / description
      Previous value: -"The pages of one document, by their ids, in the order they are to be read. Their lines are moved into each other's places and nothing else in the text moves, so pages you leave out stay where they are. Two or more ids, each named once. Needs `page_of`, and goes on its own: no `doc`, `after`, `before` or `at` — one call says an order, another puts one page somewhere. Every page it names has to have a line of its own already"New value: +"Its pages' ids, two or more, each once, in reading order: their lines trade places, nothing else moves. With `page_of` alone; each needs a line"
    • changedInput schema / properties / page_of / description
      Previous value: -"The id of the document it becomes a page of — an opaque name like `q7ntmzbm-0001`, not its title. Leave it out to make it a document of its own"New value: +"Id of the document it becomes a page of. Left out, it becomes a document of its own"
  3. First observed

TDQS

A3.8/5.0
Behavior4/5

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), and the description adds real behavior beyond that: hanging writes a link line into the document body at the end or at the position named by `after`/`before`/`at`, while taking out leaves the link line behind for the caller to delete. That partial-state warning is exactly the kind of non-obvious consequence an agent needs. The remaining gap is that it says nothing about permissions or what a call returns.

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?

Four sentences, front-loaded with the primary action and both of its inverse cases, with no repetition of the schema. The one cost is stylistic: phrases like 'bang included' and 'take a page back out to its old folder' add charm but slightly slow parsing of an otherwise tight definition.

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

Completeness4/5

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

For a six-parameter, all-optional mutation tool with no output schema, the description covers the three modes, the target document, ordering semantics, and the leftover-line side effect. The only missing piece is return behavior, which no output schema covers, so the description carries that burden and does not address it.

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 already 100%, so the baseline is 3, but the description adds meaning the schema does not: it explains that reading order is line order represented as `![Its title](tisty:doc/its-id)`, which is why `after`/`before` are line-relative, and it clarifies that `at` is the positional fallback when no page is being named. That is genuine interpretive value on top of a well-documented schema.

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

Purpose4/5

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

The description names three concrete operations on a specific resource: hanging a document as a page under another, taking a page back out, and reordering pages via `order`. The verb 'Hang a document under another as a page' is unusual phrasing but the resource and effect are unambiguous. It never names or differentiates against plausible siblings such as `append_doc`, `attach`, or `move`, so an agent cannot rule those out from the description alone.

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

Usage Guidelines3/5

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

Mode selection is implied through parameters: with `page_of` it hangs a page, with no `page_of` it takes a page out, and `page_of` alone with `order` reorders. That is useful conditional guidance, but it is keyed to arguments rather than stated as when-to-use rules, and no alternative tool is ever mentioned as the right choice in a different situation.

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