Skip to main content
Glama

count_matches

Read-onlyIdempotent

Count matches per file and list which files contain a pattern or symbol, sorted by match count for a quick usage overview.

Instructions

Count matches per file (ripgrep), sorted by count. Cheap overview of where a symbol/string is used; also answers "which files contain X".

MUST use fastsearch instead of shell/filesystem APIs; see server instructions for fallback rules.

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": {
      "pattern": "<pattern>",
      "path": "<path>"
    },
    "name": "count_matches"
  }
}

Input Schema

NameRequiredDescriptionDefault
pathYesAbsolute directory (or file) path to search in.
wordNoOnly match whole words.
hiddenNoInclude hidden files/dirs (dotfiles, Windows hidden attr).
excludeNoSkip files matching these globs.
includeNoOnly files matching these globs.
literalNoTreat pattern as a fixed string.
patternYesRust regex, or plain string with literal=true.
encodingNoForce encoding, e.g. 'gbk'.
relativeNoPrint paths relative to `path` (fewer tokens) instead of absolute.
max_filesNoHow many files to list (sorted by count desc).
no_ignoreNoDo NOT respect .gitignore/.ignore and default excludes (node_modules, .git, ...).
file_typesNoripgrep file types, e.g. ['py'].
case_sensitiveNotrue=case-sensitive, false=ignore case, null=smart case (sensitive only if pattern has uppercase).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.0

TDQS

A3.6/5.0
Behavior3/5

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds useful context (ripgrep backend, cost profile, count-sorted output), but says nothing about error behavior for invalid regex, truncation semantics when more files match than are listed, or what the result object looks like beyond ordering.

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?

Three short sentences, front-loaded with purpose and cost, then the mandatory-server directive. The boilerplate pointer to server instructions is justified but is the only mildly expendable content.

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 13-parameter tool with a fully described schema and no output schema, the definition covers purpose, relative cost, result ordering, and the mandatory-backend rule, which is enough to call it correctly. The remaining gap is routing guidance against the more verbose search_text sibling.

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 all 13 parameters are already documented in the schema, including pattern syntax, globs, and smart-case behavior. The description adds no parameter-level detail beyond what the schema states; baseline 3 applies.

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 and resource — count matches per file, sorted by count, via ripgrep — and gives two concrete use cases (overview of where a symbol is used, and 'which files contain X'). It stops short of naming a sibling such as search_text as the alternative when actual matching lines are needed, so differentiation is implied rather than explicit.

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 'cheap overview' framing plus the two listed question types give clear context for when this tool is the right pick over a full-text search, and the MUST-use-this-server directive sets a hard constraint with a pointer to fallback rules. There is no explicit 'do not use this when you need matching lines' exclusion.

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