Skip to main content
Glama

search

Read-onlyIdempotent

Find relevant files and function or class definitions across a codebase using natural-language meaning and combined semantic/keyword matching, ideal when exact symbol names are unknown.

Instructions

Search the codebase by MEANING. Modes: 'file' searches file headers/symbols, 'identifier' searches function/class definitions with call chains, 'hybrid' (default) runs both and returns combined results. Uses embeddings for semantic matching plus keyword overlap scoring. For an exact known symbol name in a language with a real language server available (e.g. via an LSP-backed MCP like Serena), prefer that for go-to-definition — this tool is best for meaning-based / fuzzy discovery across the whole repo.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "query": "<query>"
    },
    "name": "search"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoSearch mode: 'file' for files, 'identifier' for functions/classes, 'hybrid' for both. Default: hybrid.
rootNoAbsolute project root. Omit only where this session started; required elsewhere and on every subagent call.
queryYesNatural language description of what you're looking for.
top_kNoNumber of matches to return. Default: 5.
formatNotext (default), compact JSON for agents, or verbose json for diagnostics.
fusionNoHow to combine semantic + keyword scores in file mode. 'rrf' (default) fuses rank positions and is robust when signal scales differ. 'weighted' is an opt-out that blends by semantic_weight/keyword_weight.
presetNoRanking preset. fast favors cheap lexical recall, balanced is default, exhaustive returns a wider set, semantic_only ignores keyword overlap (pure embedding similarity), keyword_only ignores embedding similarity (pure lexical match).
profileNoInclude phase timings in JSON/compact output for diagnosis.
inline_codeNoInline source with file matches. 'crux' (default) returns an ~8-line relevant span, 'full' returns the matched definition body, and 'off' returns pointers only.
include_kindsNoFilter identifier kinds, e.g. ["function", "method"]. Only for identifier/hybrid mode.
keyword_weightNoWeight for keyword overlap. Default: 0.28.
semantic_weightNoWeight for embedding similarity. Default: 0.72.
min_keyword_scoreNoMinimum keyword score filter. Accepts 0-1 or 0-100.
min_combined_scoreNoMinimum final score filter. Accepts 0-1 or 0-100.
min_semantic_scoreNoMinimum semantic score filter. Accepts 0-1 or 0-100.
include_dependenciesNoAdd up to three import pointers from the top two file matches to check supporting code.
require_keyword_matchNoWhen true, only return results with keyword overlap.
require_semantic_matchNoWhen true, only return results with positive semantic similarity.
top_calls_per_identifierNoHow many ranked call sites per identifier (identifier/hybrid mode). Default: 10.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.6.0
    • changedInput schema / properties / root / description
      Previous value: -"Absolute project root. Required with linked worktrees; subagents must pass their own worktree root on every call."New value: +"Absolute project root. Omit only where this session started; required elsewhere and on every subagent call."
  2. First observedv1.4.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description adds real behavioral context by disclosing the underlying mechanism (embeddings plus keyword overlap scoring) and the default mode's combine-both behavior. It stops short of discussing cost, latency, or result size limits for a 19-parameter search, which keeps it off a 5.

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?

Four sentences, front-loaded with purpose and modes, followed by mechanism and the alternative-tool caveat — every sentence adds something. There is minor redundancy in re-explaining the mode enum that the schema already enumerates, but no filler.

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 19-parameter tool with no output schema, the description covers the conceptual model (modes, scoring, defaults) that an agent needs to pick sensible arguments, and the schema handles the rest. The one gap is that with no output schema, the description never indicates what a result record contains or how mode affects the returned shape beyond 'call chains'.

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%, so the schema already documents all 19 parameters including mode, format, fusion, preset and the weight knobs. The description adds only marginal semantic meaning beyond that, mainly restating mode behavior and clarifying that identifier mode carries call chains; it does not explain how the score filters or weight parameters interact in practice.

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?

The description opens with a specific verb and resource ('Search the codebase by MEANING') and immediately qualifies it with the three modes and their distinct targets (file headers/symbols vs. function/class definitions with call chains). It also draws an explicit boundary against LSP-based go-to-definition, so an agent can separate this tool from exact_references or grep without opening the schema.

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

Usage Guidelines5/5

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

It states both when to use this tool ('meaning-based / fuzzy discovery across the whole repo') and when not to ('for an exact known symbol name ... prefer that for go-to-definition'), naming the alternative class of tool and the condition that selects it. The guidance is conditional and actionable rather than a generic 'use this to search'.

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