openclaw - 💡(How to fix) Fix [Feature]: Improve MCP server tool discoverability and search precision for email agents [1 participants]

Summary

MCP server tools have generic descriptions that make it hard for LLM agents to select the right tool and use it effectively. Key issues: duplicate search_emails vs search_all_emails, no way to filter by account/folder/date, and raw verbose JSON responses that overwhelm context windows.

Problem to solve

When an LLM agent connects to the OpenClaw MCP email server, it faces three problems:

1. Tool confusion: search_emails and search_all_emails have nearly identical descriptions. The agent cannot determine which to use.

2. No filtering: search_emails only takes a query string. The agent cannot filter by account, folder, date range, or unread status. This forces multiple round-trips and wastes tokens.

3. Verbose responses: get_email_content returns full raw JSON (headers, body, attachments metadata). For a 50-line email, the response can be 2000+ tokens. The agent only needs the visible text.

Proposed solution

1. Differentiate tool descriptions — Make search_emails description say "search in the currently selected account" and search_all_emails say "search across all connected accounts". Add parameter descriptions.

2. Add search_emails_filtered — New tool with structured filters:

{
  "query": "invoice",
  "account": "[email protected]",
  "folder": "INBOX",
  "since": "2026-04-01",
  "unread_only": true,
  "limit": 10
}

1. Add response summarization — For get_email_content, return a condensed version by default:

{
  "from": "[email protected]",
  "subject": "Invoice #1234",
  "date": "2026-04-23",
  "body_text": "<first 500 chars>",
  "attachments": ["invoice.pdf"]
}

Alternatives considered

• Better prompts only — Works sometimes but is fragile. Different LLMs interpret vague descriptions differently.
• Single search tool with optional params — Simpler API but breaks backward compatibility for existing users.

Impact

• Affected: Anyone using MCP server with LLM agents (OpenClaw, Claude Code, Codex, etc.)
• Severity: Medium — agent wastes tokens on wrong tool selection and verbose responses
• Frequency: Every email search/get interaction
• Consequence: Slower responses, higher token cost, occasional wrong results

Evidence

Tested with MiMo-V2-Pro and DeepSeek Reasoner. Both models consistently confused search_emails vs search_all_emails. Average email content response was 1800 tokens when 400 would suffice.