mail_inbox_messagesList messages in an inbox, filter unread items with seen=false, and paginate results by cursor to help agents process pending mail.
Khi trực hộp, liệt kê thư nhận; lọc seen=false để lấy thư chưa xử lý, phân trang bằng cursor. / Use to list messages an agent needs to handle.
| Name | Required | Description | Default |
|---|---|---|---|
| seen | No | false = chỉ thư chưa đọc. | |
| limit | No | ||
| since | No | ||
| cursor | No | ||
| inbox_id | Yes |
Changes observed during successful MCP inspections.
v0.11.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered structurally. The description adds genuinely useful behavior beyond that: cursor-based pagination and the seen=false filter for unprocessed mail. It still omits ordering, result-size behavior and rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact, front-loaded sentence that puts the filtering and pagination behavior before the generic English summary. The bilingual duplication is slightly redundant but arguably serves the tool's audience.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter, no-output-schema read tool, the description covers purpose, the main filter and pagination but says nothing about result ordering, what a page contains, or how limit/since interact with cursor. Adequate but with visible gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only 'seen' is annotated), so the description must carry more weight. It does explain seen=false and cursor pagination, but leaves inbox_id (required), limit (default 50, max 100) and since undocumented in both places.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('liệt kê thư nhận' / list messages in an inbox) and scopes it to what an agent must handle. It does not explicitly distinguish itself from the singular sibling mail_inbox_message or from mail_inbox_wait, so sibling differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Khi trực hộp' (when on inbox duty) and 'Use to list messages an agent needs to handle' imply the context, and 'lọc seen=false để lấy thư chưa xử lý' gives one concrete filter recipe. However, no alternative is named (e.g., mail_inbox_message for a single message, mail_inbox_wait for polling) and no exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.