Skip to main content
Glama
owrede

vault-memory

by owrede
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

get_document_bundle

Read-onlyIdempotent

Retrieve a document's citation anchor, outline, backlinks, forward links, and recent edits in one structured bundle to support agentic knowledge tasks.

Instructions

Document-tree retrieval. Returns a structured bundle for a single document: { anchor (citation packet + optional status/superseded_by), outline (section tree via buildOutlineTree — same shape as get_outline.root), backlinks (citation packets + property_snippet + relation:"wikilink"), forward_links (same shape; broken links omitted), recent_edits (≤10 most recent audit_log rows mapped to {at, op, client_id, is_memory_sink_write?}) }. Every citation packet is the full 8-field D-01 shape from src/memory/citation-packet.ts. v2.0.0 accepts only depth:1 (one-hop links); the field is zod-pinned to z.literal(1) for forward compatibility. recent_edits is keyed by the anchor's CURRENT note path — pre-rename history is preserved in audit_log but not surfaced here (Phase 4 widens). Unknown doc_id returns { isError: true, error: "doc_not_found", doc_id }.

Input Schema

NameRequiredDescriptionDefault
as_ofNo
depthNoLink-walk depth. v2.0.0: only 1 (one-hop). Phase 4 may widen.
doc_idYesOpaque DocId (obsidian-fs://<vault>/<path>) of the anchor document
vaultsNoOptional vault filter; usually omitted (the DocId names a vault)
max_charsNoGlobal UTF-16 body character budget. Sections defaults to 6000; zero excludes body text. Metadata is always body-free.
projectionNoOptional v2 projection; sections requires heading_paths. Defaults to the legacy response.
heading_pathsNoExact heading paths on the anchor, or filters on section-search results.
include_observationsNoInclude explicitly categorized statements when the derived source hash is fresh; preserves provenance and shares the body budget.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv2.5.0
    • addedInput schema / properties / as_of
      Added value: +{
+  "type": "string"
+}
    • addedInput schema / properties / heading_paths
      Added value: +{
+  "description": "Exact heading paths on the anchor, or filters on section-search results.",
+  "items": {
+    "items": {
+      "minLength": 1,
+      "type": "string"
+    },
+    "minItems": 1,
+    "type": "array"
+  },
+  "minItems": 1,
+  "type": "array"
+}
    • addedInput schema / properties / include_observations
      Added value: +{
+  "description": "Include explicitly categorized statements when the derived source hash is fresh; preserves provenance and shares the body budget.",
+  "type": "boolean"
+}
    • addedInput schema / properties / max_chars
      Added value: +{
+  "description": "Global UTF-16 body character budget. Sections defaults to 6000; zero excludes body text. Metadata is always body-free.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / properties / projection
      Added value: +{
+  "description": "Optional v2 projection; sections requires heading_paths. Defaults to the legacy response.",
+  "enum": [
+    "full",
+    "metadata",
+    "sections"
+  ],
+  "type": "string"
+}
  2. First observedv2.0.0-rc.5

TDQS

A4.2/5.0
Behavior5/5

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

Annotations already cover read-only/idempotent/non-destructive, and the description still adds substantial behavioral detail: the unknown-doc_id error shape, that broken links are omitted, that recent_edits is capped at 10 and keyed by the CURRENT anchor path (pre-rename history hidden), and that depth is zod-pinned for forward compatibility. This is context well beyond what structured fields provide.

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?

Purpose is front-loaded and the bundle shape is given before the caveats, so an agent can skim the first sentence for routing. It is dense but earns most of its length; minor redundancy appears in the repeated depth:1/'same shape' statements.

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 no output schema, the description substitutes by specifying the exact return structure, field shapes, error contract, and known limitations. For an 8-parameter tool this is sufficiently complete for correct invocation.

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 88%, so the schema already documents params thoroughly. The description largely restates schema content (depth:1, max_chars budget) rather than adding new meaning; the only incremental semantics are the depth-literal versioning caveat and the ≤10 recent_edits bound, which is modest additive value at this coverage level.

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+resource ('Document-tree retrieval', returns a bundle for a single document) and then enumerates the exact bundle components (anchor, outline, backlinks, forward_links, recent_edits). It also distinguishes itself from siblings by noting the outline 'same shape as get_outline.root' and that it consolidates what list_backlinks/list_forward_links/audit_log expose separately.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the enumeration of collected artifacts signals that this tool replaces several narrow sibling calls for one document. However, there is no explicit 'use this instead of X when Y' guidance, and no when-not conditions beyond the depth:1 versioning note.

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

Deploy Server

Other Tools