Skip to main content
Glama

Write a document

write_doc
Destructive

Create or rewrite a Markdown document stored locally as Tisty memory, converting it into Tisty language and reporting what changed.

Instructions

Write a document, something kept and read again; work to do is propose. Markdown is turned into the Tisty language and turned says what changed. Alone it writes a new one: find first, as a subject with a document is updated there, and a title in use is refused. With doc and print it rewrites that one whole, page lines the body drops going back at the end; one passage is edit_doc. #words in its text tag it.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "body": "<body>"
    },
    "name": "write_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
docNoId of a document to write again whole, not its title; needs `print`. Left out, a new one
bodyYesThe whole document; its first line is its title. One line per paragraph: a single newline is a line break, so wrapped text reads broken
langNoWith `translation_of`: the body's language tag, like `es`, `en` or `pt-BR`
printNoThe `print` `read_doc` gave with the text you worked from; if the document changed since, nothing is written
anywayNoWrite it although a document names the same subject; only when it truly is another
folderNoThe existing folder its subject belongs in, by name, path or id; left out needs a reason. Not with `doc`: `file_doc` moves one
compactNoWith `doc` and `print`: this write puts the document back in order, as `rules` «tidying» says. Refused on one the person began unless `person_asked`
page_ofNoId of the document this is a page of: it is named at that document's end (`page_doc` moves the line), takes its folder and holds no pages
person_askedNoWith `compact`: the person asked you in this conversation to compact a document they began
translation_ofNoId of a document this one says in another language, joined as one more of its languages; both say their language, in `lang` or a `lang:` property
keep_compactionNoOnly on the person's word: `rules` «tidying»

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.47.0
    • changedInput schema / properties / keep_compaction / description
      Previous value: -"The person told you in this conversation to keep the compaction awaiting their word"New value: +"Only on the person's word: `rules` «tidying»"
  2. Changed11 schema fields changedv1.43.2
    • changedInput schema / properties / anyway / description
      Previous value: -"A new document whose title names the same subject as one already here is refused; this writes it all the same. Only when it truly is another subject"New value: +"Write it although a document names the same subject; only when it truly is another"
    • changedInput schema / properties / body / description
      Previous value: -"The whole document. Its first line becomes its title. Each paragraph goes on one line, however long: in the Tisty language a single newline is a line break, so markdown wrapped at 80 columns reads broken in the middle of its sentences. Nothing checks this on the way in"New value: +"The whole document; its first line is its title. One line per paragraph: a single newline is a line break, so wrapped text reads broken"
    • changedInput schema / properties / compact / description
      Previous value: -"With `doc` and `print`: this writing puts the document back in order — what holds today, the subject, the decisions, the history — rather than changing what it says. Call `rules` first: it says the order. In one whole write: before it, move what leaving pages hold and mark them; in it, today first, then the subject, the decisions and a history naming every link and file taken out — one lost without a name is refused. Only what Tisty confirms is stated as today; what you only read stays dated and unconfirmed. Refused on a document the person began unless `person_asked`. The window shows the person it was compacted, by whom and when, with one click to undo; until they decide, only one more whole `compact` of yours goes in"New value: +"With `doc` and `print`: this write puts the document back in order, as `rules` «tidying» says. Refused on one the person began unless `person_asked`"
    • changedInput schema / properties / doc / description
      Previous value: -"The id of a document to write again — an opaque name like `q7ntmzbm-0001`, not its title — replacing its body. Needs `print`. Left out, a new document is written instead"New value: +"Id of a document to write again whole, not its title; needs `print`. Left out, a new one"
    • changedInput schema / properties / folder / description
      Previous value: -"The existing folder its subject belongs in, by its name, its whole path or its id. Expected: `docs` says which exist, the `folder` tool makes a new one once the person agrees, and a name no folder has is refused here. Left out, it sits outside them all, and that needs a reason. Writing an existing document again with `doc` and `print` cannot take `folder`: `file_doc` moves one that is already here"New value: +"The existing folder its subject belongs in, by name, path or id; left out needs a reason. Not with `doc`: `file_doc` moves one"
    • changedInput schema / properties / keep_compaction / description
      Previous value: -"Only when the person told you in this conversation to keep a compaction of this document that waits for their word: it is kept, and this write goes ahead"New value: +"The person told you in this conversation to keep the compaction awaiting their word"
    • changedInput schema / properties / lang / description
      Previous value: -"With `translation_of`: the language the body is in, as a tag like `es`, `en` or `pt-BR`, written into its properties"New value: +"With `translation_of`: the body's language tag, like `es`, `en` or `pt-BR`"
    • changedInput schema / properties / page_of / description
      Previous value: -"The id of the document this one is a page of — an opaque name like `q7ntmzbm-0001`, not its title. The page is named at the end of that document, and where it is named is where it sits; `page_doc` with `after` puts that line somewhere else. A page follows that document everywhere and takes its folder, so `folder` is ignored, and it holds no pages of its own"New value: +"Id of the document this is a page of: it is named at that document's end (`page_doc` moves the line), takes its folder and holds no pages"
    • changedInput schema / properties / person_asked / description
      Previous value: -"With `compact`: the person asked you in this conversation to compact a document they began. Never otherwise"New value: +"With `compact`: the person asked you in this conversation to compact a document they began"
    • changedInput schema / properties / print / description
      Previous value: -"The `print` `read_doc` gave you with the text you are working from. If the document has moved on since, nothing is written and you are told to read it again — so the person cannot lose what they wrote while you were thinking"New value: +"The `print` `read_doc` gave with the text you worked from; if the document changed since, nothing is written"
    • changedInput schema / properties / translation_of / description
      Previous value: -"The id of a document this one says the same as, in another language. It is written as a document of its own beside that one, in its folder, and the person sees them as one document with a switch between their languages. Its language comes from `lang` or a `lang:` line in its properties, and that document has to say its own. One document per language: a language the group already has is refused"New value: +"Id of a document this one says in another language, joined as one more of its languages; both say their language, in `lang` or a `lang:` property"
  3. Changed2 schema fields changedv1.41.1
    • addedInput schema / properties / lang
      Added value: +{
      +  "description": "With `translation_of`: the language the body is in, as a tag like `es`, `en` or `pt-BR`, written into its properties",
      +  "type": "string"
      +}
    • addedInput schema / properties / translation_of
      Added value: +{
      +  "description": "The id of a document this one says the same as, in another language. It is written as a document of its own beside that one, in its folder, and the person sees them as one document with a switch between their languages. Its language comes from `lang` or a `lang:` line in its properties, and that document has to say its own. One document per language: a language the group already has is refused",
      +  "type": "string"
      +}
  4. First observed

TDQS

A3.7/5.0
Behavior4/5

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

Beyond the destructive/non-idempotent hints, it discloses that a whole rewrite drops page lines and puts them back at the end, that a title in use is refused, that `compact` requires `person_asked`, and that its text is tagged with #words. These are substantive consequences not present in annotations, though it doesn't state permission or authorship rules clearly.

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

Conciseness3/5

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

It is short and packs a lot into three clauses, but the semicolon-heavy construction and unusual vocabulary make it hard to front-load or scan. The opening is vague before the concrete mode distinctions arrive, so structure is weaker than its length.

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?

For an 11-parameter mutation tool with no output schema, the description covers the major mode splits and failure cases reasonably well, but several behaviors (return value `turned`, permission requirements, what exactly is refused) are only glanceable. Adequate but not fully complete for this complexity.

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 description coverage is 100% and 11 parameters are documented in the schema, so the schema already carries most semantics. The description adds cross-param relationships (doc + print together, lang with translation_of) but does not add much beyond what the schema fields already say, so baseline 3 applies.

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 gives a specific verb and resource (write a document) and distinguishes it from siblings: alone it writes a new document, while `edit_doc` handles one passage and `propose` is for work to do. A caller can tell the main modes apart, though the deliberately odd register ("something kept and read again") slows parsing.

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

Usage Guidelines4/5

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

It is explicit about modes and alternatives: run `find` first because an existing subject is updated there, use `doc` + `print` to rewrite one whole, and use `edit_doc` for a single passage. Exclusions such as `find` first and the edit_doc redirect give real routing guidance, though prerequisites like permission needs are only implied.

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