search_sections
Search documentation sections by relevance using hybrid lexical and semantic ranking, returning concise summaries for quick identification of useful 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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo | No | Repository identifier | |
| query | Yes | Search query | |
| doc_path | No | Optional: limit search to a specific document | |
| path_glob | No | v1.36+ — fnmatch glob restricting results to matching doc_paths (e.g. 'api/**/*.md'). Stacks with doc_path. | |
| max_results | No | Maximum number of results to return | |
| 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. | |
| semantic_only | No | Skip lexical scoring; rank purely by embedding cosine similarity. | |
| semantic_weight | No | Weight (0.0–1.0) of semantic component in hybrid fusion. Lexical gets 1 - weight. Default 0.5. | |
| role | No | Optional v1.19+ role filter. Values: concept, tutorial, how_to, reference, api, example, troubleshooting, changelog, faq, other. | |
| 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. | |
| 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. | |
| min_answerability | No | v1.42+ — drop results whose v1.33 _answerability score is below this threshold (0–1). _meta.quality_filtered reports drop count. | |
| min_quotability | No | v1.42+ — drop results whose v1.33 _quotability score is below this threshold (0–1). Stacks with min_answerability. | |
| min_level | No | v1.44+ — restrict to sections at heading level >= this. Inclusive. | |
| max_level | No | v1.44+ — restrict to sections at heading level <= this. Inclusive. Stacks with min_level. | |
| tags | No | v1.45+ — restrict to sections whose Section.tags contains every listed tag (AND semantics). Case-insensitive. | |
| exclude_tags | No | v1.51+ — drop sections whose Section.tags contains ANY listed tag (negative ANY-match). Stacks with `tags`. Case-insensitive. | |
| 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. | |
| 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). | |
| min_byte_length | No | v1.53+ — drop sections shorter than this many bytes (byte_end - byte_start). Use to filter out stubs / one-liners. | |
| max_byte_length | No | v1.53+ — drop sections longer than this many bytes. Use to filter out oversized dumps. Stacks with min_byte_length. | |
| 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. |