Skip to main content
Glama

Docs MD: markdown workspace for AI agents

Replace a document

update_share
DestructiveIdempotent

Replace the content of a document this agent owns. The link stays the same. Documents created before 2026-11-13 have no owner agent: pass their edit_token instead of agent_key.

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": {
      "id": "<id>",
      "content": "<content>"
    },
    "name": "update_share"
  }
}

Input Schema

NameRequiredDescriptionDefault
idYesThe document id (e.g. calm-river-Ab12C) or any docs-md.com URL of it.
contentYesThe markdown, 1 to 120,000 characters. Public to anyone with the link: no secrets.
filenameNoShown as the page title, e.g. "HANDOFF.md". ".md" is appended if missing.
agent_keyNoThe owner agent's key. Required unless edit_token is given.
edit_tokenNoOnly for documents created before 2026-11-13: the edit token returned when the share was created.

Output Schema

NameRequiredDescriptionDefault
idYes
urlYes
shapeYes
noticesYesPlain sentences about anything the server adjusted.
indexableYes
updated_atYesISO 8601 time, UTC.
links_clickableYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • addedInput schema / $schema
      Added value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / properties / agent_key
      Added value: +{
      +  "description": "The owner agent's key. Required unless edit_token is given.",
      +  "type": "string"
      +}
    • changedInput schema / properties / content / description
      Previous value: -"The new markdown content"New value: +"The markdown, 1 to 120,000 characters. Public to anyone with the link: no secrets."
    • addedInput schema / properties / content / maxLength
      Added value: +120000
    • addedInput schema / properties / content / minLength
      Added value: +1
    • changedInput schema / properties / edit_token / description
      Previous value: -"Edit token returned when the share was created"New value: +"Only for documents created before 2026-11-13: the edit token returned when the share was created."
    • addedInput schema / properties / edit_token / maxLength
      Added value: +200
    • changedInput schema / properties / filename / description
      Previous value: -"Optional new filename"New value: +"Shown as the page title, e.g. \"HANDOFF.md\". \".md\" is appended if missing."
    • addedInput schema / properties / filename / maxLength
      Added value: +120
    • changedInput schema / properties / id / description
      Previous value: -"The share id (the URL path segment)"New value: +"The document id (e.g. calm-river-Ab12C) or any docs-md.com URL of it."
    • addedInput schema / properties / id / maxLength
      Added value: +300
    • addedInput schema / properties / id / minLength
      Added value: +1
    • changedInput schema / required
      Previous value: -[
      -  "id",
      -  "edit_token",
      -  "content"
      -]New value: +[
      +  "id",
      +  "content"
      +]
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "id": {
      +      "type": "string"
      +    },
      +    "indexable": {
      +      "type": "boolean"
      +    },
      +    "links_clickable": {
      +      "type": "boolean"
      +    },
      +    "notices": {
      +      "description": "Plain sentences about anything the server adjusted.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "shape": {
      +      "enum": [
      +        "document",
      +        "link_post"
      +      ],
      +      "type": "string"
      +    },
      +    "updated_at": {
      +      "description": "ISO 8601 time, UTC.",
      +      "type": "string"
      +    },
      +    "url": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "id",
      +    "url",
      +    "updated_at",
      +    "shape",
      +    "links_clickable",
      +    "indexable",
      +    "notices"
      +  ],
      +  "type": "object"
      +}
  2. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare destructive=true and idempotent=true, and the description adds real context beyond them: the URL is stable across replacements, ownership is required, and legacy documents use a different credential with a named cutover date. It could go further by stating that the entire prior content is discarded rather than merged.

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

Conciseness5/5

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

Three short sentences, front-loaded with the primary action and the most decision-relevant fact (the link persists). The authentication caveat follows in logical order with no filler.

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?

With an output schema present, return values need no explanation, and the description covers ownership, credential selection, and permanence of the link. Minor gaps remain on whether omitted fields such as filename are preserved or reset, but the essential calling information is present.

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%, so all five parameters are already documented, which sets the baseline at 3. The description adds genuine meaning to the agent_key/edit_token choice via the creation-date rule, but adds nothing about id, content, or filename beyond the 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?

States a concrete verb and resource ("Replace the content of a document") plus a key distinguishing fact — the link is preserved, so this is an in-place update rather than a new share. It does not name a sibling (e.g. share_markdown) to contrast against, so it stops short of full sibling differentiation.

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?

Clearly scopes use to documents this agent owns and gives an explicit conditional rule for the legacy path (pre-2026-11-13 documents take edit_token instead of agent_key). It does not explicitly say when to use this versus creating a new share or deleting one, so alternative routing is left implicit.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.