Skip to main content
Glama
owrede

vault-memory

by owrede
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

search_sections

Read-onlyIdempotent

Retrieve whole note sections instead of isolated chunks: promotes hybrid search hits to their enclosing sections and returns top sections with citations and optional snippets.

Instructions

Section-level retrieval. Composes the v1 hybrid (semantic + BM25 + RRF) pipeline with a chunk-to-section promotion step: runs hybrid with an inflated top_k = limit × 5, promotes each chunk hit to its enclosing section, dedupes by (note, section anchor), scores each section as the MAX of its constituent chunks, tie-breaks by chunk_id_first ASC, and returns the top limit sections. Each hit carries an 8-field citation packet (D-01) with a non-empty section heading_path PLUS the section anchor, score, contributing chunk_ids, and an optional snippet from the best-scoring chunk. Use when you want WHOLE-SECTION context, not a chunk window.

Input Schema

NameRequiredDescriptionDefault
as_ofNo
limitNo
queryYes
vaultsNo
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.
recency_weightNo
authority_weightNo
include_supersededNo
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

A3.5/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior: the inflated top_k, chunk-to-section promotion, MAX scoring, tie-break rule, dedupe key, and the 8-field citation packet. Much of the algorithm detail is more implementation than behavioral guidance, but the output shape and scoring semantics are genuinely useful.

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

Conciseness3/5

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

Front-loaded with purpose, but the bulk is a single dense sentence enumerating pipeline internals (RRF, promotion, dedupe keys, tie-break) that an agent rarely needs to invoke the tool. Sizeable trimming would lose little.

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

Completeness3/5

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

For an 11-parameter tool with no output schema and low schema description coverage, the description does cover the return shape (citation packet) but leaves most parameters undocumented. It is adequate for a knowledgeable caller but incomplete given the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 36%, so the description must carry the load, but it only clarifies `limit` (via the top_k = limit × 5 note) and lightly touches scoring. It never explains max_chars, projection, heading_paths, recency_weight, authority_weight, include_superseded, include_observations, as_of, or vaults.

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?

Opens with a specific verb+resource ("Section-level retrieval") and explains the retrieval pipeline plus its distinguishing scope (whole-section context). It contrasts implicitly with chunk-window tools rather than naming a sibling like search_hybrid, so differentiation is strong but not fully explicit.

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?

"Use when you want WHOLE-SECTION context, not a chunk window" gives a clear selection condition against chunk-based retrieval. It stops short of naming the alternative tools (search_hybrid / search_semantic) or stating when NOT to use this one.

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