Skip to main content
Glama

search_query

Read-onlyIdempotent

Search an index. The default hybrid ranking fuses exact-keyword matching (typo-tolerant, great for SKUs, usernames, IDs, and any literal term) with meaning-based matching — so a document containing the query words ranks first, AND conceptually related documents are still found. Each result has its original content and metadata, a relevance score, a snippet that highlights the match (wrapped in …), and a signals breakdown of which signal(s) matched. offset pages through results — the response carries a page object with total and has_more.

Example:

{
  "project_id": "my-saas",
  "index": "help-articles",
  "query": "reset password",
  "limit": 5
}
// Returns: {
//   "results": [{ "id": "art-1", "content": "How to reset your password...", "metadata": { "category": "account" }, "score": 0.031, "snippet": "How to <mark>reset</mark> your <mark>password</mark>...", "signals": { "lexical": -3.1, "semantic": 0.92 } }, ...],
//   "page": { "offset": 0, "limit": 5, "total": 12, "has_more": true },
//   "mode": "hybrid"
// }

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": {
      "project_id": "<project_id>",
      "index": "<index>",
      "query": "<query>"
    },
    "name": "search_query"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNoRanking mode: 'hybrid' (default — keyword + meaning, fused), 'semantic' (meaning only), or 'lexical' (keyword only, with typo-tolerant prefix matching).
indexYesIndex name to search.
limitNoMax results per page (default 10, max 100).
queryYesQuery text — keywords and/or natural language.
offsetNoSkip this many results for pagination (default 0). Pages together with limit; the response includes page.total and page.has_more. Applies to hybrid and lexical modes.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4/5.0
Behavior4/5

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

Annotations only declare readOnly and idempotent, and the description adds substantial context beyond that: each result carries content, metadata, a score, a <mark>-wrapped snippet, and a signals breakdown, plus a page object with total and has_more. With no output schema present, this return-shape disclosure is doing important work. The one gap is that it presents offset as generally applicable, while the schema limits it to hybrid and lexical modes.

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?

Purpose and ranking behavior are front-loaded, then the example follows. The embedded JSON-with-comments block is long but earns its place by showing the exact return envelope, which no output schema covers. Prose sentences are dense but not redundant.

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 six-parameter, three-required search tool with no output schema, the description supplies the missing return-value information through the annotated example. Mode behavior, scoring signals, snippet markup, and pagination are all covered. What remains absent is any guidance on failure modes or on choosing this tool over sibling search tools.

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

Parameters4/5

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

Schema coverage is 100%, so a 3 would be the baseline, but the worked example adds concrete meaning: it shows project_id accepting a slug rather than a UUID and demonstrates how limit and offset surface as page.offset, page.limit, page.total, and has_more. The default hybrid mode is also called out in prose. It does not add syntax detail for query beyond what the schema says.

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?

It opens with a specific verb and resource ('Search an index') and then explains what the default hybrid ranking actually fuses. The purpose is unambiguous, but it never distinguishes this tool from siblings like db_query, docs_query, fs_search, or memory_search, so an agent must infer which search surface applies.

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?

The description gives real selection guidance for the ranking modes, stating hybrid is the default and that lexical is typo-tolerant and good for SKUs, usernames, and IDs. It also explains pagination via offset. It stops short of saying when to prefer this index search over the other search tools in the catalog, so no exclusions are stated.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources