Skip to main content
Glama

Search nodes and documents

search
Read-only

Find nodes or documents by the words they contain. Nothing here matches by meaning, so use recall for a natural-language question. method "keyword" (default): ranked full-text search over active nodes; terms are AND-combined, and a multi-word query that matches nothing is retried once as an OR of its words. It returns cards, not bodies (default limit 5). method "exact": the matching line per node for a literal substring, or a POSIX regex with regex:true, across every status including done and archived (default limit 50). scope "documents": a line search of document bodies, a literal substring or, with regex:true, a JavaScript regex; it ignores method and type, and limit caps the number of documents unless max_docs is set. Every hit carries id, title, and url; limit is at most 50, with no paging. Read a full body with fetch.

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_slug": "<project_slug>",
      "query": "<query>"
    },
    "name": "search"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeNoLimit node results to one type.
limitNoMax results.
queryYesWhat to search for.
regexNoFor method "exact": treat query as a POSIX regex. For scope "documents": treat query as a JavaScript regex.
scopeNo"nodes" (default) or "documents".
methodNo"keyword" (default, ranked relevance) or "exact" (literal term/pattern).
max_docsNoFor scope "documents" only. Max docs in the response. Default 10.
component_idNoFor scope "documents" only. Optional parent-component filter. Pass a COMP-N to scope the search to docs under that component.
project_slugYesProject slug, e.g. "acme-app" — list(what="projects") returns yours.
context_linesNoFor scope "documents" only. Lines of surrounding context returned before and after each match. Default 1.
case_sensitiveNoFor scope "documents" only. Default false (case-insensitive).
max_matches_per_docNoFor scope "documents" only. Max matches surfaced per doc. Default 5.

Output Schema

NameRequiredDescriptionDefault
dataYesRanked search results with ChatGPT-compatible citation fields.
actionYesThe action that produced this result.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / $schema
      Previous value: -"https://json-schema.org/draft/2020-12/schema"New value: +"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"https://json-schema.org/draft/2020-12/schema"New value: +"http://json-schema.org/draft-07/schema#"
    • changedOutput schema / properties / data / additionalProperties
      Previous value: -{}New value: +true
    • changedOutput schema / properties / data / properties / results / items / additionalProperties
      Previous value: -{}New value: +true
  2. Changed5 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • removedInput schema / additionalProperties
      Removed value: -false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / properties / data / additionalProperties
      Previous value: -trueNew value: +{}
    • changedOutput schema / properties / data / properties / results / items / additionalProperties
      Previous value: -trueNew value: +{}
  3. Changed6 schema fields changed
    • addedInput schema / properties / case_sensitive
      Added value: +{
      +  "description": "For scope \"documents\" only. Default false (case-insensitive).",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / component_id
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "Shareable id: TASK-N (task), KNOW-N (knowledge), COMP-N (component), DOC-N (document), or NODE-N (any).",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "For scope \"documents\" only. Optional parent-component filter. Pass a COMP-N to scope the search to docs under that component."
      +}
    • addedInput schema / properties / context_lines
      Added value: +{
      +  "description": "For scope \"documents\" only. Lines of surrounding context returned before and after each match. Default 1.",
      +  "maximum": 10,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / max_docs
      Added value: +{
      +  "description": "For scope \"documents\" only. Max docs in the response. Default 10.",
      +  "maximum": 50,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / max_matches_per_doc
      Added value: +{
      +  "description": "For scope \"documents\" only. Max matches surfaced per doc. Default 5.",
      +  "maximum": 50,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • changedInput schema / properties / regex / description
      Previous value: -"For method:exact — treat query as a POSIX regex."New value: +"For method \"exact\": treat query as a POSIX regex. For scope \"documents\": treat query as a JavaScript regex."
  4. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint false), and the description adds substantial context beyond them: hits return cards not bodies, default limits of 5/50/10, no paging, the AND-then-single-OR retry behavior, that exact search spans all statuses including done/archived, and that scope "documents" ignores method/type.

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?

Front-loaded with the purpose sentence, and each subsequent sentence earns its place by disambiguating a mode or constraint. It is dense and packs several concepts per sentence, but for a 12-parameter tool with three modes it stays proportionate rather than padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 12 params, three enums, and an output schema, the description supplies everything the agent needs: mode selection, defaults, result shape (id/title/url), limit/paging behavior, and a cross-reference to `fetch`. Return-value detail is optional given the output schema, yet it is still summarized usefully.

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 the schema already documents every parameter; however the description adds real meaning beyond it, notably the interaction semantics ("limit caps the number of documents unless max_docs is set", scope documents ignores method and type, limit max 50 with no paging). This exceeds the baseline-3 case where the schema does all the work.

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?

States a concrete verb and resource ("Find nodes or documents by the words they contain") and immediately names the sibling alternative `recall` for semantic queries, so an agent can route keywords vs. meaning without opening either schema. The method/scope breakdown further pins down what each invocation actually does.

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?

Explicitly states when NOT to use it ("Nothing here matches by meaning, so use `recall`") and names the alternative. It then gives selection conditions for each mode: keyword vs. exact, nodes vs. documents, and points to `fetch` for full bodies.

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.