Skip to main content
Glama

scoped_search

Search code and text with token-bounded results to replace raw grep/find, cutting context use while finding symbols, identifiers, or regex matches by scope.

Instructions

Safe, token-bounded symbol/text search replacing raw grep/find (-90% tokens). '|' or \d in query auto-enables regex when use_regex is omitted; false forces literal.

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": "scoped_search"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoDirectory to search (alias for project_path; relative or absolute)
queryYesText, identifier, or symbol name
scopeNoFilter: 'code', 'config', 'all', extension ('go', '*.py'), or subfolder ('internal/promo') (default 'all')
use_regexNoOmit = auto-detect ('|', \d → regex); false = literal; true = regex
max_resultsNoMax matching lines (default 25, max 100)
project_pathNoOptional root directory (defaults to current project)
case_sensitiveNoCase-sensitive search (default false)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv3.1.5
    • changedInput schema / properties / case_sensitive / description
      Previous value: -"Whether search is case-sensitive (default: false)"New value: +"Case-sensitive search (default false)"
    • changedInput schema / properties / max_results / description
      Previous value: -"Maximum matching lines to return (default: 25, max: 100)"New value: +"Max matching lines (default 25, max 100)"
    • changedInput schema / properties / path / description
      Previous value: -"Directory or project path to search (alias for project_path, e.g. '.', './src', 'internal/promo')"New value: +"Directory to search (alias for project_path; relative or absolute)"
    • changedInput schema / properties / project_path / description
      Previous value: -"Optional root directory path (defaults to current project)"New value: +"Optional root directory (defaults to current project)"
    • changedInput schema / properties / query / description
      Previous value: -"Text, identifier, or symbol name to search for"New value: +"Text, identifier, or symbol name"
    • changedInput schema / properties / scope / description
      Previous value: -"Filter scope: 'code', 'config', 'all', a file extension (e.g. 'go', 'ts', '*.py'), or a subfolder path (e.g. 'internal/promo') (default: 'all')"New value: +"Filter: 'code', 'config', 'all', extension ('go', '*.py'), or subfolder ('internal/promo') (default 'all')"
    • changedInput schema / properties / use_regex / description
      Previous value: -"Whether query is a regular expression (default: false)"New value: +"Omit = auto-detect ('|', \\d → regex); false = literal; true = regex"
  2. First observedv2.8.4

TDQS

A3.7/5.0
Behavior3/5

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

With no annotations supplied, the description carries the full load: it discloses that results are token-bounded, claims a ~90% savings, and explains the regex auto-detection trigger ('|' or \d, false forces literal). However, 'safe' is undefined, return shape/truncation behavior is not described, and read-only semantics are only implied by the word 'search'. Reasonable but incomplete for a zero-annotation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the value proposition and followed by a parenthetical on the one behavior most likely to cause a wrong call. 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 7-parameter search tool with full schema coverage and no output schema, the description supplies purpose, token-cost rationale, and regex edge-case behavior. What it lacks is what 'safe' concretely means and whether large result sets are truncated beyond max_results, but nothing critical to invoking it correctly is missing.

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 baseline is 3, but the description adds real clarification on the non-obvious use_regex auto-detect/override interaction, which is the one parameter whose omission behavior could trip an agent up. It slightly restates the schema rather than extending it, keeping it short of a 5.

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?

States a specific verb+resource ('symbol/text search') with a clear scope modifier ('token-bounded'), and frames it as a replacement for raw grep/find, which tells an agent what class of operation this covers. It doesn't name any MCP sibling (e.g., list_dir or smart_read_file) to differentiate against, so it stops short of the top mark.

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

Usage Guidelines3/5

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

The 'replacing raw grep/find' framing implies when to reach for it, but there is no explicit when-not condition, no named alternative tool, and no prerequisite stated. Usage is inferable rather than spelled out.

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