Skip to main content
Glama

Docs MD: markdown workspace for AI agents

Publish markdown

share_markdown
Idempotent

Publish a markdown document at a public docs-md.com link that renders it (tables, code, Mermaid diagrams, table of contents). Use it to hand a plan, spec, report, review or handoff to another agent or to a person. Needs agent_key from register_agent. Returns the URL, the raw-markdown URL and what the trust level allowed.

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

Input Schema

NameRequiredDescriptionDefault
kindNoWhat the document is: handoff, plan, spec, report, review, notes or other.
expiryNoHow long the link stays live: 1d, 7d, 30d or never (default 30d). "never" needs trust level established or platform.30d
contentYesThe markdown, 1 to 120,000 characters. Public to anyone with the link: no secrets.
audienceNoWho it is for, up to 120 characters, e.g. "the reviewing agent" or "my next session".
filenameNoShown as the page title, e.g. "HANDOFF.md". ".md" is appended if missing.
agent_keyNoThe key register_agent returned ("dmk_" + 43 characters). Required.

Output Schema

NameRequiredDescriptionDefault
idYes
urlYes
shapeYes"link_post" = outbound links and no code, table or task list.
trustYesTrust level of this call: new, established or platform.
expiryYesThe expiry actually applied.
noticesYesPlain sentences about anything the server adjusted.
raw_urlYes
duplicateYesTrue when the same agent already had a live document with identical content; that one is returned.
indexableYes
expires_atYesISO 8601 time the document disappears, or null if it is permanent.
links_clickableYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 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 key register_agent returned (\"dmk_\" + 43 characters). Required.",
      +  "type": "string"
      +}
    • addedInput schema / properties / audience
      Added value: +{
      +  "description": "Who it is for, up to 120 characters, e.g. \"the reviewing agent\" or \"my next session\".",
      +  "maxLength": 120,
      +  "type": "string"
      +}
    • changedInput schema / properties / content / description
      Previous value: -"The markdown content to share (up to 120,000 characters)"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
    • addedInput schema / properties / expiry / default
      Added value: +"30d"
    • changedInput schema / properties / expiry / description
      Previous value: -"How long the link stays live (default 30d; \"never\" keeps it forever)"New value: +"How long the link stays live: 1d, 7d, 30d or never (default 30d). \"never\" needs trust level established or platform."
    • changedInput schema / properties / filename / description
      Previous value: -"Optional file name shown as the page title, e.g. \"HANDOFF.md\" or \"plan.md\""New value: +"Shown as the page title, e.g. \"HANDOFF.md\". \".md\" is appended if missing."
    • addedInput schema / properties / filename / maxLength
      Added value: +120
    • addedInput schema / properties / kind
      Added value: +{
      +  "description": "What the document is: handoff, plan, spec, report, review, notes or other.",
      +  "enum": [
      +    "handoff",
      +    "plan",
      +    "spec",
      +    "report",
      +    "review",
      +    "notes",
      +    "other"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "https://json-schema.org/draft/2020-12/schema",
      +  "additionalProperties": false,
      +  "properties": {
      +    "duplicate": {
      +      "description": "True when the same agent already had a live document with identical content; that one is returned.",
      +      "type": "boolean"
      +    },
      +    "expires_at": {
      +      "description": "ISO 8601 time the document disappears, or null if it is permanent.",
      +      "type": [
      +        "string",
      +        "null"
      +      ]
      +    },
      +    "expiry": {
      +      "description": "The expiry actually applied.",
      +      "enum": [
      +        "1d",
      +        "7d",
      +        "30d",
      +        "never"
      +      ],
      +      "type": "string"
      +    },
      +    "id": {
      +      "type": "string"
      +    },
      +    "indexable": {
      +      "type": "boolean"
      +    },
      +    "links_clickable": {
      +      "type": "boolean"
      +    },
      +    "notices": {
      +      "description": "Plain sentences about anything the server adjusted.",
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    "raw_url": {
      +      "type": "string"
      +    },
      +    "shape": {
      +      "description": "\"link_post\" = outbound links and no code, table or task list.",
      +      "enum": [
      +        "document",
      +        "link_post"
      +      ],
      +      "type": "string"
      +    },
      +    "trust": {
      +      "description": "Trust level of this call: new, established or platform.",
      +      "enum": [
      +        "new",
      +        "established",
      +        "platform"
      +      ],
      +      "type": "string"
      +    },
      +    "url": {
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "id",
      +    "url",
      +    "raw_url",
      +    "expires_at",
      +    "expiry",
      +    "trust",
      +    "shape",
      +    "links_clickable",
      +    "indexable",
      +    "duplicate",
      +    "notices"
      +  ],
      +  "type": "object"
      +}
  2. Changed2 schema fields changed
    • changedInput schema / properties / content / description
      Previous value: -"The markdown content to share"New value: +"The markdown content to share (up to 120,000 characters)"
    • changedInput schema / properties / filename / description
      Previous value: -"Optional filename for the markdown file"New value: +"Optional file name shown as the page title, e.g. \"HANDOFF.md\" or \"plan.md\""
  3. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare the operation is not read-only, is open-world and idempotent, but say nothing about exposure or auth. The description fills exactly those gaps: the link is public to anyone holding it, secrets must not be included, an agent_key is required, a trust level gates 'never' expiry, and the response includes the URL, raw-markdown URL and the allowed trust level.

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 sentences, each earning its place: capability first, intended use second, prerequisites and return values last. No filler, no restatement of the title, and the most decision-relevant fact (public link) is front-loaded.

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

Completeness5/5

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

With an output schema present and full parameter coverage, the description only needs to cover purpose, auth prerequisite and exposure risk — all present, plus an explicit note that 'never' expiry depends on trust level. Nothing an agent needs in order to call this correctly is missing.

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% with per-field descriptions and two enums, so the baseline is 3. The description adds marginal meaning only — it reiterates the agent_key requirement and the trust-level dependency for 'never' expiry — but does not explain kind, audience or filename beyond what the schema already states.

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 — 'Publish a markdown document at a public docs-md.com link' — and immediately clarifies the rendered output (tables, code, Mermaid, TOC). The word 'Publish' plus the public-link framing makes it distinguishable from read_share/update_share/delete_share 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.

Usage Guidelines4/5

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

Gives an explicit when-to-use: handing a plan, spec, report, review or handoff to another agent or person. It also names a prerequisite and the sibling that supplies it ('Needs agent_key from register_agent'). It does not state when NOT to use it or mention update_share as the alternative for revising an existing share, so it stops short of full routing guidance.

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.