Skip to main content
Glama

Add to a document, or to a task's page

append_doc
Destructive

Add at a document's end, or under the heading in under, without reading it or a print; nothing written changes, unless replace rewrites a task page's assistant notes. For logs, minutes and dated notes; a changed fact is edit_doc.

Instructions

Add at a document's end, or under the heading in under, without reading it or a print; nothing written changes, unless replace rewrites a task page's assistant notes. For logs, minutes and dated notes; a changed fact is edit_doc. The answer says how much it grew. A task's id in doc adds under the assistant's notes on its page, dated and signed.

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": {
      "doc": "<doc>",
      "body": "<body>"
    },
    "name": "append_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
docYesA document's id, not its title, or a task's to add to its page
bodyYesMarkdown to add, after a blank line
echoNoHand back the lines around the change, instead of reading again
underNoA heading, as it reads: adds at the end of what it holds
replaceNoOnly with a task's id: rewrite the assistant's notes on its page whole, as one dated digest; a box in it is no step
keep_compactionNoOnly on the person's word: `rules` «tidying»

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.47.1
    • changedInput schema / properties / under / description
      Previous value: -"A heading, as it reads: adds at the end of what it holds. Left out, at the end of the document"New value: +"A heading, as it reads: adds at the end of what it holds"
  2. 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»"
  3. Changed6 schema fields changedv1.43.2
    • changedInput schema / properties / body / description
      Previous value: -"Markdown to add. A blank line is put between this and what was there"New value: +"Markdown to add, after a blank line"
    • changedInput schema / properties / doc / description
      Previous value: -"The document's id, as `docs` hands it back — an opaque name like `q7ntmzbm-0001`, not its title — or a task's id, to add to that task's page"New value: +"A document's id, not its title, or a task's to add to its page"
    • changedInput schema / properties / echo / description
      Previous value: -"Hand back the lines around the change as well, instead of reading the document again to see it"New value: +"Hand back the lines around the change, instead of reading again"
    • 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 / replace / description
      Previous value: -"Only with a task's id in `doc`: the assistant's notes on its page are written again, whole, as `body` — one dated digest of state, decisions, what was ruled out and references. The rest of the page stays as it is, a box in it never becomes a step, and what it replaced is kept for `restore_doc` with the task's id"New value: +"Only with a task's id: rewrite the assistant's notes on its page whole, as one dated digest; a box in it is no step"
    • changedInput schema / properties / under / description
      Previous value: -"A heading to add under, written as it reads. It goes at the end of what that heading holds, before the next one of its rank. Left out, it goes at the end of the document"New value: +"A heading, as it reads: adds at the end of what it holds. Left out, at the end of the document"
  4. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true and non-idempotent, and the description earns credit by localizing the destruction: nothing changes unless `replace` rewrites a task page's assistant notes whole. It also discloses the return shape ('The answer says how much it `grew`') and the no-read-needed behavior. The phrasing is compressed enough that the exact scope of `replace`'s overwrite takes a second pass to parse.

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 the core action and scope, and every clause carries information. Some phrasing is idiosyncratic ('without reading it or a `print`', '`rules` «tidying»'), which costs a little immediate clarity but not length.

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 6-parameter mutation tool with no output schema, it covers the main branches (append, heading-scoped append, task-page append, task-page rewrite), states the return value, and flags the one destructive path. Minor gaps remain around what happens when `under` matches no heading.

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 real meaning: `under` places content at the end of a heading's contents, `replace` is valid only with a task id and rewrites notes as one dated digest, and a task id in `doc` triggers dated, signed insertion. That is genuine semantics beyond the schema text.

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 ('Add at a document's end, or under the heading in `under`') and extends it to the task-page case ('A task's id in `doc` adds under the assistant's notes on its page'). It also names the sibling it is not ('a changed fact is `edit_doc`'), so an agent can separate it from edit_doc 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 explicit when-to-use ('For logs, minutes and dated notes') and an explicit alternative with the condition that selects it ('a changed fact is `edit_doc`'). It also states a precondition for the risky path ('Only on the person's word' for keep_compaction) and that no prior read is needed.

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