Fetch plain text email content for 1-10 mailbox identities, returning ordered partial results.
Read plain text for 1-10 exact identities with ordered partial results.
| Name | Required | Description | Default |
|---|---|---|---|
| identities | Yes | ||
| max_text_chars | No |
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Changes observed during successful MCP inspections.
v0.11.0Output schema / $defs / BatchMessageOutput / properties / error / anyOfPrevious value: -[
- {
- "type": "string"
- },
- {
- "type": "null"
- }
-]New value: +[
+ {
+ "$ref": "#/$defs/SafeErrorOutput"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / $defs / BatchMessageOutput / properties / error / titleRemoved value: -"Error"Output schema / $defs / SafeErrorOutputAdded value: +{
+ "properties": {
+ "code": {
+ "enum": [
+ "partial_move",
+ "permission_denied",
+ "not_found",
+ "invalid_request",
+ "timeout",
+ "rate_limited",
+ "draft_busy",
+ "recovery_required",
+ "imap_error",
+ "connection_error",
+ "broker_error",
+ "outcome_unknown"
+ ],
+ "title": "Code",
+ "type": "string"
+ },
+ "message": {
+ "title": "Message",
+ "type": "string"
+ },
+ "reason": {
+ "anyOf": [
+ {
+ "enum": [
+ "task_rate",
+ "session_queue_timeout",
+ "imap_worker_capacity",
+ "ipc_helper_capacity",
+ "request_deadline",
+ "transport_loss"
+ ],
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Reason"
+ },
+ "retry_after_seconds": {
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Retry After Seconds"
+ },
+ "scope": {
+ "enum": [
+ "request",
+ "item",
+ "account",
+ "broker",
+ "client"
+ ],
+ "title": "Scope",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message",
+ "scope",
+ "reason",
+ "retry_after_seconds"
+ ],
+ "title": "SafeErrorOutput",
+ "type": "object"
+}v0.10.0Output schema / $defs / AttachmentMetadataOutput / properties / encoded_sizeAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "title": "Encoded Size"
+}Output schema / $defs / AttachmentMetadataOutput / properties / size / anyOfAdded value: +[
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+]Output schema / $defs / AttachmentMetadataOutput / properties / size / typeRemoved value: -"integer"Output schema / $defs / AttachmentMetadataOutput / requiredPrevious value: -[
- "attachment_id",
- "filename",
- "content_type",
- "size"
-]New value: +[
+ "attachment_id",
+ "filename",
+ "content_type",
+ "size",
+ "encoded_size"
+]v0.9.0Input schema / properties / max_text_charsAdded value: +{
+ "anyOf": [
+ {
+ "type": "integer"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "title": "Max Text Chars"
+}Output schema / $defs / MessageOutput / properties / text_total_charsAdded value: +{
+ "title": "Text Total Chars",
+ "type": "integer"
+}Output schema / $defs / MessageOutput / properties / text_truncatedAdded value: +{
+ "title": "Text Truncated",
+ "type": "boolean"
+}Output schema / $defs / MessageOutput / requiredPrevious value: -[
- "identity",
- "headers",
- "text",
- "flags",
- "attachments"
-]New value: +[
+ "identity",
+ "headers",
+ "text",
+ "flags",
+ "attachments",
+ "text_total_chars",
+ "text_truncated"
+]v0.1.4Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds that results are plain-text and may be partial/ordered, but the phrase 'partial results' is vague and does not clarify truncation, pagination, or output 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?
The description is a single dense sentence with no filler. It front-loads the core action and packs useful constraints into a compact form.
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?
The description is adequate for a batch read operation but leaves ambiguity around the meaning of 'ordered partial results,' the effect of max_text_chars, and how this tool relates to get_email or search_emails.
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 0%, so the description must compensate. It clarifies that identities must be exact and limited to 1-10, but it does not explain the max_text_chars parameter or what 'partial results' means in relation to it.
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 the action ('Read plain text'), the target resource ('emails' via exact identities), and the batch scope ('1-10 exact identities'). This distinguishes it from single-email retrieval and HTML retrieval, though it does not explicitly name sibling tools.
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?
'Exact identities' implies this tool is for known identifiers rather than search_emails, and 'plain text' distinguishes it from get_email_html. It provides clear context but does not explicitly state when not to use it or name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.