Skip to main content
Glama
jgravelle

jdocmunch-mcp

by jgravelle
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

search_sections

Read-only

Search sections by relevance. Hybrid (BM25 lexical + semantic embedding) fusion when the index was built with use_embeddings=true; falls back to lexical-only otherwise. Returns summaries only — use get_section for full content.

Instructions

Search sections by relevance. Hybrid (BM25 lexical + semantic embedding) fusion when the index was built with use_embeddings=true; falls back to lexical-only otherwise. Returns summaries only — use get_section for full content. Results with text_source="ocr" came from a scanned page via OCR and may contain errors.

Input Schema

NameRequiredDescriptionDefault
repoNoRepository identifier
roleNoOptional v1.19+ role filter. Values: concept, tutorial, how_to, reference, api, example, troubleshooting, changelog, faq, other.
tagsNov1.45+ — restrict to sections whose Section.tags contains every listed tag (AND semantics). Case-insensitive.
queryYesSearch query
rolesNov1.52+ — restrict to sections whose metadata.role matches ANY listed role (positive OR-match). Differs from singular `role` (which is exact). Case-insensitive.
dedupeNov1.34+ — collapse near-duplicate sections to a single representative based on the v1.34 cluster sidecar. _meta.deduped reports suppressed member ids.
fieldsNov1.121+ — explicit per-row field whitelist (e.g. ['id','title','doc_path','_score']). Wins over compact. `id` is always returned.
compactNov1.121+ — drop per-row fields a caller can't act on (repo, parent_id, children, byte_start/byte_end, content_hash, inline_code, references; plus empty tags and a summary identical to the title). Per-row _freshness is kept only when it isn't 'fresh'. ~40% fewer bytes per result. Default off — the full row is unchanged.
profileNov1.32+ — task-aware retrieval profile. install/debug/explain/api each boost a small role set so matching sections rank ahead. Explicit role= overrides.
doc_pathNoOptional: limit search to a specific document
semanticNonull/omit (auto — hybrid when embeddings exist), true (force hybrid), false (force lexical-only). Zero performance cost when the index has no embeddings.
max_levelNov1.44+ — restrict to sections at heading level <= this. Inclusive. Stacks with min_level.
min_levelNov1.44+ — restrict to sections at heading level >= this. Inclusive.
path_globNov1.36+ — fnmatch glob restricting results to matching doc_paths (e.g. 'api/**/*.md'). Stacks with doc_path.
repo_groupNov1.26+ — fan out across the named repo group (defined via define_repo_group). When set, the per-repo `repo` arg is ignored; results from each member repo are fused via RRF.
max_resultsNoMaximum number of results to return
exclude_tagsNov1.51+ — drop sections whose Section.tags contains ANY listed tag (negative ANY-match). Stacks with `tags`. Case-insensitive.
exclude_rolesNov1.52+ — drop sections whose metadata.role matches ANY listed role. Case-insensitive. Stacks with `roles` (the result must match an included role and not match any excluded role).
semantic_onlyNoSkip lexical scoring; rank purely by embedding cosine similarity.
snippet_bytesNov1.121+ — inline the first N bytes of each section's body as `snippet` so a confident top hit needs no get_section round-trip. UTF-8 safe (never splits a codepoint); `snippet_truncated: true` marks a cut section. 0 = off.
max_byte_lengthNov1.53+ — drop sections longer than this many bytes. Use to filter out oversized dumps. Stacks with min_byte_length.
min_byte_lengthNov1.53+ — drop sections shorter than this many bytes (byte_end - byte_start). Use to filter out stubs / one-liners.
min_quotabilityNov1.42+ — drop results whose v1.33 _quotability score is below this threshold (0–1). Stacks with min_answerability.
semantic_weightNoWeight (0.0–1.0) of semantic component in hybrid fusion. Lexical gets 1 - weight. Omit to use this repo's tuned weight, else 0.5; a value you pass is always honoured. _meta.semantic_weight and _meta.semantic_weight_source report which applied. Paraphrased queries usually want 0.7–0.95: RRF (k=60) structurally penalises an answer that is strong in only one channel, so 0.5 can rank below a section that is mediocre in both.
min_answerabilityNov1.42+ — drop results whose v1.33 _answerability score is below this threshold (0–1). _meta.quality_filtered reports drop count.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv1.130.0
    • removedInput schema / properties / semantic_weight / default
      Removed value: -0.5
    • changedInput schema / properties / semantic_weight / description
      Previous value: -"Weight (0.0–1.0) of semantic component in hybrid fusion. Lexical gets 1 - weight. Default 0.5."New value: +"Weight (0.0–1.0) of semantic component in hybrid fusion. Lexical gets 1 - weight. Omit to use this repo's tuned weight, else 0.5; a value you pass is always honoured. _meta.semantic_weight and _meta.semantic_weight_source report which applied. Paraphrased queries usually want 0.7–0.95: RRF (k=60) structurally penalises an answer that is strong in only one channel, so 0.5 can rank below a section that is mediocre in both."
  2. Changed3 schema fields changedv1.121.0
    • addedInput schema / properties / compact
      Added value: +{
+  "default": false,
+  "description": "v1.121+ — drop per-row fields a caller can't act on (repo, parent_id, children, byte_start/byte_end, content_hash, inline_code, references; plus empty tags and a summary identical to the title). Per-row _freshness is kept only when it isn't 'fresh'. ~40% fewer bytes per result. Default off — the full row is unchanged.",
+  "type": "boolean"
+}
    • addedInput schema / properties / fields
      Added value: +{
+  "description": "v1.121+ — explicit per-row field whitelist (e.g. ['id','title','doc_path','_score']). Wins over compact. `id` is always returned.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • addedInput schema / properties / snippet_bytes
      Added value: +{
+  "default": 0,
+  "description": "v1.121+ — inline the first N bytes of each section's body as `snippet` so a confident top hit needs no get_section round-trip. UTF-8 safe (never splits a codepoint); `snippet_truncated: true` marks a cut section. 0 = off.",
+  "minimum": 0,
+  "type": "integer"
+}
  3. Addedv1.118.0
  4. Removedv1.100.0
  5. First observedv1.66.3

TDQS

A3.8/5.0
Behavior3/5

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

Annotation readOnlyHint=true already establishes the safety profile, and the description adds real value: hybrid BM25+embedding fusion conditional on the index being built with use_embeddings=true, a lexical-only fallback, summaries-only results, and an OCR accuracy caveat tied to text_source="ocr". That OCR warning is genuinely non-obvious and hard to get anywhere else. However it stops short of describing pagination, result ordering guarantees, or what the returned summary row contains, so it is good rather than complete.

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, zero waste, and front-loaded with the core operation. The retrieval-mode mechanics come second and the escape hatch to get_section plus the OCR caveat close it out in priority order.

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?

For a 25-parameter tool with a fully documented schema and no output schema, the description covers the three things the schema cannot: how ranking actually works, that results are summaries not bodies, and that OCR-derived text may be corrupted. What is missing is minor by comparison: no note on result ordering or how the required repo/query pair scopes the search.

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 100% across 25 parameters, so the schema already carries the full semantic load, including the nuanced semantic_weight tuning advice and role/roles distinction. The description adds only the indirect hint that index build state governs hybrid behavior. Baseline 3 is appropriate when the schema does all the parameter work.

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 specific verb+resource ('Search sections by relevance') and immediately scopes the operation to relevance ranking rather than enumeration. It distinguishes itself from get_section by declaring that only summaries are returned. It does not differentiate from the sibling search_titles, and there is no title, so an agent must infer the sections-vs-titles split.

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?

Provides explicit routing guidance: this tool returns summaries, so use get_section when full content is needed. That is a real when-to-use-an-alternative statement. It gives no guidance on when to prefer search_titles or get_sections instead, and no guidance on when filters like profile or dedupe should be engaged.

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