Skip to main content
Glama
Sign In
OpenPyXL MCP Server

OpenPyXL MCP Server

by jonemo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

search_in_cell_range

Search a defined Excel cell range for a string, with optional exact-match filtering, to locate matching values in a worksheet.

Instructions

Search for a string in a continuous range of cells in an Excel workbook.

Args: filepath: The path to the Excel workbook. For example, "~/Downloads/test.xlsx" or "C:\myfolder\myfile.xlsx". If only a filename is provided, the file will be searched for in the Desktop and Downloads folders. sheet_name: The name of the sheet to get the value from. top_left_cell: The top left cell of the range. For example, "A1". bottom_right_cell: The bottom right cell of the range. For example, "RC976". search_string: The string to search for. exact_match: True if the entire cell value must match, False if it can be a substring. Defaults to False.

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": {
      "filepath": "<filepath>",
      "sheet_name": "<sheet_name>",
      "top_left_cell": "<top_left_cell>",
      "bottom_right_cell": "<bottom_right_cell>",
      "search_string": "<search_string>"
    },
    "name": "search_in_cell_range"
  }
}

Input Schema

NameRequiredDescriptionDefault
filepathYes
sheet_nameYes
exact_matchNo
search_stringYes
top_left_cellYes
bottom_right_cellYes

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

B3.3/5.0
Behavior3/5

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

No annotations are supplied, so the description carries the burden; it does disclose one genuinely non-obvious behavior (a bare filename is looked up in Desktop and Downloads). It is silent on case sensitivity, whether multiple hits are returned, and cost/performance over large ranges, all of which matter for a search tool with a required bounding box.

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?

The purpose is front-loaded in a single sentence, and the Args block is uniformly formatted with no filler. The per-argument text is slightly repetitive of parameter names ('The name of the sheet to get the value from'), but nothing is padding.

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

Completeness3/5

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

An output schema exists, so return values need not be explained, and all parameters are documented. Still, for a search tool with five required parameters and no annotations, the description leaves key behaviors unstated: whether all matches are returned or just the first, case sensitivity, and what happens on a missing file or invalid range.

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 description coverage is 0%, and the description compensates well: every one of the six parameters is given meaning, with path examples plus the filename fallback rule, cell reference examples, and an explicit definition of exact_match including its default. The only weakness is that the cell-reference format is loosely illustrated ('A1' versus 'RC976') without stating the accepted syntax.

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?

The first line gives a specific verb and resource plus the scope constraint ('continuous range of cells in an Excel workbook'), which cleanly separates it from the get_* siblings that read a single cell, an explicit range, or the sheet list. It does not name those siblings explicitly, so the differentiation is implicit rather than stated.

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

Usage Guidelines2/5

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

There is no when/when-not guidance and no mention of alternatives. An agent must infer on its own that this is the right tool for locating a value versus get_values_of_cell_range for retrieving every value, and nothing tells it whether this is preferable for large ranges or when a match is expected to be unique.

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

Deploy Server

Other Tools