Skip to main content
Glama

get_doc

Read-onlyIdempotent

Read a document's metadata, outline, or a single section without loading the whole body into context. Use body=true for the full page and the returned version as the base for updates.

Instructions

Read a document. By DEFAULT returns metadata plus the outline (headings) and NOT the body — a document is far larger than a task, and a body you read stays in your context for the rest of the session. The outline lists headings; section="" returns just that part; body=true returns the whole page. The returned version is what update_doc takes as base_version. If you addressed the document by an old path or a bare slug, the reply carries moved_to (its current path); a bare slug shared by several documents fails with 409 and the list of full paths.

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>"
    },
    "name": "get_doc"
  }
}

Input Schema

NameRequiredDescriptionDefault
docYesDocument UUID, or a slug path like 'architecture/adr/adr-004' (a path also needs project_id). A path survives the document being moved: the old path still resolves, and so does a bare slug ('adr-004') when exactly one live document in the project has it. When the reference was not the live path, the reply carries moved_to — the document's current path; use that from now on. A bare slug shared by several documents is a 409 ('Ambiguous document slug') listing the full paths: pick one and repeat the call with the full path or the UUID. The UUID never changes.
bodyNoReturn the full markdown body. Prefer section= when you need one part.
sectionNoReturn only this section: a heading's text, or its anchor from the outline.
project_idNoProject UUID. Required only when doc is a slug path.
version_onlyNoReturn just the version — the cheap 'has this changed since I read it?' check before a write.
outline_depthNoLimit the outline to headings at this level or shallower (e.g. '2' for chapters, not every subsection). Default: all levels.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.1

TDQS

A4.6/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds real value beyond them: the context-cost rationale for not fetching bodies, the fact that the returned version is what update_doc requires as base_version, and the two error/redirect behaviors (moved_to on stale paths, 409 with candidate paths on ambiguous slugs). It stops short of describing what the metadata payload contains, but the critical behavioral traits are disclosed.

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 default behavior – the single most important fact – before alternatives and edge cases. The final sentence about moved_to and 409 largely duplicates text already present in the doc parameter's schema description, which is the only real waste.

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?

No output schema exists, so the description must carry return expectations, and it does: metadata plus outline, optional section or full body, moved_to on stale references, 409 with candidate paths, and the version value used for later writes. An agent has everything needed to call this correctly and interpret the result.

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; the description earns above that by explaining the tradeoff behind body vs section (size/context cost) rather than just restating them, and by tying the response's moved_to/409 outcomes back to how doc references resolve. The project_id-only-with-path rule is left entirely to the schema, which keeps this from a 5.

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?

"Read a document" states a specific verb and resource, then immediately qualifies the scope: default returns metadata plus outline, not the body. It also distinguishes itself from siblings implicitly by noting the returned version is the base_version for update_doc, so an agent knows this is the read side of a read/modify pair.

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?

Explicitly routes among the three read modes: default outline, section="<heading>" for one part, body=true for the whole page, with stated preference for section=. It also names a fourth use case (version_only-style cheap change check implied by base_version) and explains the moved_to recovery path, so there is no ambiguity about which call to make.

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