Skip to main content
Glama

search_files

Search user-selected folders by words to find matching documents, PDFs, images, screenshots, recordings, or videos, returning files best first with the matching passage.

Instructions

Search the folders the user chose under Files (documents, PDFs, pictures, screenshots, recordings and video on their computer) by words. Returns matching files, best first, with the passage that matched. Requires the separate file-access permission.

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_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
afterNoOptional local day (YYYY-MM-DD): only files dated on or after it.
kindsNoOptional: only these kinds of file.
limitNoMaximum files (default 10, maximum 50).
queryYesWords to find.
beforeNoOptional local day (YYYY-MM-DD): only files dated before it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the burden and usefully discloses the permission requirement and return behavior: matching files ranked best first, including the matching passage. It does not explicitly state that the operation is read-only or what happens if the permission is missing, but the search framing strongly implies a non-mutating operation.

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?

The description is front-loaded with the core purpose, then adds return behavior and the permission prerequisite in compact form. Every sentence contributes useful information and there is no wasted wording.

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?

Because there is no output schema, the description appropriately explains what is returned: matching files, best first, with the matched passage. It also notes the access prerequisite, while parameter details are left to the full-coverage schema. A minor gap is that it does not describe failure behavior when file access is unavailable.

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 five parameters, including after, before, kinds, and limit. The description adds only a broad mapping such as 'by words' for query and file-type examples, without explaining the date filters or limit behavior, so baseline 3 is appropriate.

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 states a specific verb and resource: search the user's chosen folders under Files by words. It enumerates the covered file types and local-computer scope, which distinguishes it from siblings such as search_screen, search_meetings, and search_agent_notes.

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 gives clear context for use: searching local files the user has chosen, with a prerequisite file-access permission. It does not explicitly contrast this tool with search_screen or other search siblings, nor does it state when not to use it, so it falls short of full alternative guidance.

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