Skip to main content
Glama
Sign In
Guildora

Guildora

by az-xx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

Search messages

search_messages
Read-onlyIdempotent

Searches Discord messages by text, author, mentions, attachments, pinned status, and date range across server history or a single channel, returning message IDs and channels for follow-up context.

Instructions

Finds messages by text, author, mentions, attachments/links (has), pinned state and date range. Uses Discord's server-wide search when available (whole history, all channels). Otherwise, or if scan: true, it scans one channel's history up to scan_limit and states exactly how much it scanned. Results include message IDs and channels; use get_message or read_messages around=ID for context.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "search_messages"
  }
}

Input Schema

NameRequiredDescriptionDefault
hasNoOnly messages that have all of these.
scanNoSkip server search and scan the channel history directly.
sortNoServer search only (default newest).
afterNoOnly after this ISO date or message ID.
guildNoServer ID or name. Optional if DISCORD_GUILD_ID is set or the bot is in one server.
limitNoMax results (1-25, default 25).
queryNoText the message must contain.
authorNoOnly messages by this user (ID, mention or name).
beforeNoOnly before this ISO date or message ID.
cursorNonext_cursor from a previous call.
pinnedNo
channelNoLimit to one channel or thread (ID, mention, link or name).
mentionsNoOnly messages that mention this user.
scan_limitNoMax messages to scan (default and cap: GUILDORA_SCAN_LIMIT).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.4.0

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, and the description adds real behavioral context beyond them: server search covers whole history and all channels, the fallback scans exactly one channel bounded by scan_limit, and the response reports how much was actually scanned. It also states that results carry message IDs and channels. Rate limits and pagination behavior (cursor) are left unmentioned.

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 primary capability is front-loaded in the first sentence, followed by the mode-selection rule and the follow-up hint; every sentence carries information. It is dense but not padded, though the mode/fallback sentence is packed enough that it takes a second read.

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?

With 14 optional parameters, no output schema, and strong annotation coverage, the description does the necessary work: it explains the two execution paths, the scan bound, and what the result objects contain (IDs and channels). The one real gap is pagination via cursor, which an agent would only learn from the schema field.

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 93%, so nearly every parameter is already self-documenting and the baseline is 3. The description adds cross-parameter meaning about how scan and scan_limit interact with the server-search path, but it never explains which filters still apply in scan mode or how cursor is used, so it does not substantially exceed the schema.

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 plus the full filter surface it searches over (text, author, mentions, has, pinned, date range), so an agent knows exactly what kind of lookup this is. It also names get_message and read_messages as the context-follow-up tools, separating it from the retrieval siblings.

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?

Explains the two operating modes and the condition that selects each: server-wide search when available, otherwise (or with scan: true) a single-channel history scan. It also tells the agent to follow up with get_message or read_messages around=ID for surrounding context. It stops short of explicit exclusions (e.g. 'do not use this to fetch one known message'), which is why it is not a 5.

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