search_sections
Read-only
Locate relevant documentation sections through hybrid lexical-semantic search, returning summaries so agents can pinpoint answers without consuming full files.
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository identifier | |
| role | No | Optional v1.19+ role filter. Values: concept, tutorial, how_to, reference, api, example, troubleshooting, changelog, faq, other. | |
| tags | No | v1.45+ — restrict to sections whose Section.tags contains every listed tag (AND semantics). Case-insensitive. | |
| query | Yes | Search query | |
| roles | No | v1.52+ — restrict to sections whose metadata.role matches ANY listed role (positive OR-match). Differs from singular `role` (which is exact). Case-insensitive. | |
| dedupe | No | v1.34+ — collapse near-duplicate sections to a single representative based on the v1.34 cluster sidecar. _meta.deduped reports suppressed member ids. | |
| fields | No | v1.121+ — explicit per-row field whitelist (e.g. ['id','title','doc_path','_score']). Wins over compact. `id` is always returned. | |
| compact | No | 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. | |
| profile | No | v1.32+ — task-aware retrieval profile. install/debug/explain/api each boost a small role set so matching sections rank ahead. Explicit role= overrides. | |
| doc_path | No | Optional: limit search to a specific document | |
| semantic | No | null/omit (auto — hybrid when embeddings exist), true (force hybrid), false (force lexical-only). Zero performance cost when the index has no embeddings. | |
| max_level | No | v1.44+ — restrict to sections at heading level <= this. Inclusive. Stacks with min_level. | |
| min_level | No | v1.44+ — restrict to sections at heading level >= this. Inclusive. | |
| path_glob | No | v1.36+ — fnmatch glob restricting results to matching doc_paths (e.g. 'api/**/*.md'). Stacks with doc_path. | |
| repo_group | No | v1.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_results | No | Maximum number of results to return | |
| exclude_tags | No | v1.51+ — drop sections whose Section.tags contains ANY listed tag (negative ANY-match). Stacks with `tags`. Case-insensitive. | |
| exclude_roles | No | v1.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_only | No | Skip lexical scoring; rank purely by embedding cosine similarity. | |
| snippet_bytes | No | 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. | |
| max_byte_length | No | v1.53+ — drop sections longer than this many bytes. Use to filter out oversized dumps. Stacks with min_byte_length. | |
| min_byte_length | No | v1.53+ — drop sections shorter than this many bytes (byte_end - byte_start). Use to filter out stubs / one-liners. | |
| min_quotability | No | v1.42+ — drop results whose v1.33 _quotability score is below this threshold (0–1). Stacks with min_answerability. | |
| semantic_weight | No | 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. | |
| min_answerability | No | v1.42+ — drop results whose v1.33 _answerability score is below this threshold (0–1). _meta.quality_filtered reports drop count. |