metu-webmail-mcp

search_emails

Search a mailbox for emails by keyword, sender, recipient, subject, folder, or date range, and filter results to unread or flagged messages only.

Instructions

Search for emails matching specific criteria.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum number of results to return (default: 20).
`query`	No	Free-text keyword search in subject and body.
`folder`	No	Mailbox folder to search in (default: 'INBOX').	INBOX
`sender`	No	Filter by sender name or email address (e.g. 'rektory@metu.edu.tr' or 'Ahmet').
`subject`	No	Filter by text contained in the subject line.
`recipient`	No	Filter by recipient name or email.
`since_date`	No	Search for emails received on or after this date (format: 'DD-Mon-YYYY', e.g. '01-Aug-2026').
`before_date`	No	Search for emails received before this date (format: 'DD-Mon-YYYY').
`unread_only`	No	If True, only match unread emails.
`flagged_only`	No	If True, only match starred/flagged emails.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 12, 2026

TDQS

C2.6/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. 'Search' weakly implies a read-only, non-destructive operation, but the description discloses nothing about result ordering, pagination beyond the limit default, or whether unset filters broaden or narrow results.

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?

A single front-loaded sentence with zero padding. It is efficient, though the brevity is a consequence of under-specification rather than disciplined editing.

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

Completeness2/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 the input schema is fully documented. However, for a 10-parameter search tool with no annotations, the description supplies no filter-combination semantics or routing guidance, leaving the agent to guess at invocation behavior.

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% — all 10 parameters carry their own descriptions, including formats and defaults. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a generic verb+resource ('Search for emails') but the qualifier 'matching specific criteria' is filler that adds no discriminating information. It does not distinguish this tool from the sibling list_emails, which an agent would need to know about to pick correctly.

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-to-use guidance, no mention of when search is preferable to list_emails, and no note about how filters combine (AND semantics) or what happens with all-null criteria. The agent must infer the entire usage model.

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

Deploy Server