Skip to main content
Glama

search_project

Read-only

Find a literal string across a project's text documents and return each match's file path, line, and column, so you can locate content without reading every document.

Instructions

Search a project's text documents for a literal string and return where it occurs, instead of reading every document. Returns matches [{ filePath, line, column, preview }], with 1-based line and column (UTF-16 units, as the editor counts) and preview the matching line cut to 160 characters around the match, with … where cut; totalMatches, every match including those past limit; truncated; filesSearched; and binaryFilesSkipped. query is matched literally, never as a regular expression, and ignoring case unless caseSensitive. path narrows the search to one document or a folder; one that names nothing is NOT_FOUND. Documents are read one at a time as read_file reads them, so text in a tracked deletion is not found, and at most 300 per call: it saves calls and context, not wall-clock time. A larger scope, or more matches than limit, returns what was found with truncated true.

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": {
      "projectId": "<projectId>",
      "query": "<query>"
    },
    "name": "search_project"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathNoA document, or a folder whose documents are searched
limitNoMost matches returned, 1 to 500; totalMatches still counts every one
queryYesLiteral text to find, 1 to 200 characters
projectIdYesOverleaf project ID
caseSensitiveNoMatch case exactly; by default case is ignored

Output Schema

NameRequiredDescriptionDefault
matchesYes
truncatedYes
totalMatchesYes
filesSearchedYes
binaryFilesSkippedYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.0

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past readOnlyHint=true: discloses the 300-file-per-call cap, that binary files are skipped, that text in tracked deletions is not found, that matching is literal and case-insensitive by default, and that truncated is set rather than failing on large scopes.

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-loads purpose and return shape, then layers semantics and constraints. Some sentences are densely packed with clauses, but nearly all of them carry unique information and there is no filler.

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?

Despite an output schema existing, it describes the match record fields, 1-based/UTF-16 coordinates, and preview truncation, and it covers performance and scope caveats. An agent has everything needed to call it and interpret results.

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; the description still adds real meaning — query is never a regex, path naming nothing yields NOT_FOUND, and limit affects returns while totalMatches counts all. It does not restate types or bounds, which the schema already carries.

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 specific verb and resource ('search a project's text documents for a literal string') plus the value proposition 'return where it occurs, instead of reading every document', which immediately separates it from read_file and get_full_document.

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?

It sets the condition for choosing this over reading documents one by one, and explains when truncation occurs ('a larger scope, or more matches than limit'). It stops short of explicitly naming siblings other than read_file, but the usage context is clear.

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