Skip to main content
Glama

search_messages

Search Google Chat messages server-side across all chats, or limit results to one space, date range, or direct messages. Each hit returns its space and thread IDs.

Instructions

Search messages server-side across all chats, like Chat's search box.

space_id (+ is_dm) limits it to one chat. since/until are ISO dates or datetimes (e.g. "2026-11-01"; no timezone means UTC). order: "newest" or "relevance". Each hit includes its space_id and thread_id.

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

Input Schema

NameRequiredDescriptionDefault
is_dmNo
orderNonewest
queryYes
sinceNo
untilNo
space_idNo
page_sizeNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.0.2

TDQS

A4.3/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does a fair amount: it declares the search is server-side, explains how space_id and is_dm scope results to one chat, specifies ISO date/datetime input for since/until with the UTC default, lists the two ordering modes, and states that each hit carries space_id and thread_id. It stops short of stating permissions, pagination behavior, or result limits.

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?

Four short sentences, front-loaded with the core purpose, then scoping, then formats, then return shape. Nothing is repeated and nothing wasted.

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?

For a seven-parameter search tool with no annotations, the description supplies the scoping semantics, the date format rule, the ordering options, and the identity fields present in each hit, while the output schema covers return structure. The only small gap is page_size, which is minor against the rest.

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%, so the description has to compensate, and it does for six of seven parameters: query (by analogy), space_id, is_dm, since, until, and order, including a concrete date example and the timezone default. Only page_size is left without any explanation beyond its schema default of 20.

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?

"Search messages server-side across all chats" names a specific verb (search) and resource (messages) plus the scope (all chats), and the analogy "like Chat's search box" pins down that this is full-text retrieval rather than a listing. That is enough for an agent to distinguish it from listing-style siblings such as read_messages or list_unread.

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?

Usage is implied by "like Chat's search box" and by the statement that space_id (+ is_dm) narrows it to a single chat, so the agent can infer this is the query-driven path and the other tools are the browsing paths. But no alternative tool is named and there is no explicit when-not guidance, so the routing is left partly to inference.

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