Skip to main content
Glama

Label a thread

threads_modify
DestructiveIdempotent

Apply and remove labels on one thread, or one message of it, to file it in a folder, star it or mark it read or unread - an Outlook mailbox's categories and its own folders are its labels. The ids come from labels_list. Adding STARRED to a thread stars its newest message the person received - on an Outlook mailbox, flags it - as their own mail app does, and removing it unstars every message. Adding SPAM junks it, and taking SPAM off brings it back to the inbox. Adding INBOX brings it back from the archive. In a Gmail connected by Google sign-in adding TRASH bins it too; an Outlook mailbox takes UNREAD, STARRED, SPAM and INBOX beside its categories and its folders, and no other id, and junks a thread's inbox messages alone, filing into one folder a call: adding a folder moves the messages into it from whatever folder each is in, and a folder is left only for another folder added - never Deleted Items, Junk or a folder under either, which threads_trash and SPAM own - or for INBOX, which brings them back; a Gmail mailbox whose provider is imap takes only UNREAD, STARRED, SPAM, INBOX and its own labels, several a call, as Gmail does, each message keeping its id; any other mailbox whose provider is imap takes only UNREAD, STARRED, SPAM, INBOX and its folders' labels, filing into one folder a call: adding a label moves the messages into its folder from whatever folder each is in - so removing one label and adding another moves them from one folder to the other - and removing labels alone moves their messages back to the inbox, each message moved taking a new id, which the answer names. There, and in an Outlook mailbox, a thread's sent mail and drafts, and any message in the provider's own scheduled, snoozed or outgoing folder - in an Outlook mailbox its copies of mail it could not sync too - stay where they are, untouched, each answered with skipped saying which. Outlook and a mailbox whose provider is imap take INBOX added, never removed - threads_archive takes a thread out of the inbox - and move nothing out of the bin, which is threads_untrash's: outside a Gmail, a binned message they would have moved is answered with skipped. With ids in place of id it takes 2 to 100 at once under one call's time, counted as one action: each thread it reached is answered under threads - done; notDone, saying why; or possiblyDone, moved in part or asked with no answer back, which threads_get - or messages_get for a message - reads to check - and each it did not reach, its time spent, its connection lost or the mailbox refusing it whole, is left untouched under notReached, for the same call again.

Input Schema

NameRequiredDescriptionDefault
idNoThe threadId a search or a read answered, or with scope message the message's id.
idsNo2 to 100 threadIds - or with scope message message ids - in place of id, acted on in one call.
flagNoOn an Outlook mailbox, a follow-up flag on these days, set as adding STARRED sets one. No other mailbox keeps a date on a flag: adding STARRED flags mail there without one.
scopeNothread, the default, acts on the whole thread; message acts on that one message alone.
mailboxYesThe mailbox's name or its email address.
importanceNoThe importance each message it reaches takes: an Outlook mailbox sets its own, and a Gmail connected by Google sign-in marks high as important and normal or low as not. A mailbox whose provider is imap keeps none.
addLabelIdsNo
removeLabelIdsNo

Output Schema

NameRequiredDescriptionDefault
idNo
threadsNoEach thread the call reached, with ids.
labelIdsNo
messagesNo
newestOnlyNoThe folders whose provider showed only their newest messages, each with how many it showed: every one holds more, and nothing before those was read, searched, counted or acted on, so finding nothing there says nothing of the rest.
notReachedNoThe ids the call did not reach - its time ran out, its connection to the mailbox was lost, or the mailbox refused it whole, as the thread that met the refusal says - each left untouched, for the same call again.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedOutput schema / properties / newestOnly
      Added value: +{
      +  "description": "The folders whose provider showed only their newest messages, each with how many it showed: every one holds more, and nothing before those was read, searched, counted or acted on, so finding nothing there says nothing of the rest.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "folder": {
      +        "type": "string"
      +      },
      +      "shown": {
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "folder",
      +      "shown"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / threads / items / properties / newestOnly
      Added value: +{
      +  "description": "The folders whose provider showed only their newest messages, each with how many it showed: every one holds more, and nothing before those was read, searched, counted or acted on, so finding nothing there says nothing of the rest.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "folder": {
      +        "type": "string"
      +      },
      +      "shown": {
      +        "type": "number"
      +      }
      +    },
      +    "required": [
      +      "folder",
      +      "shown"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
  2. Changed2 schema fields changed
    • changedOutput schema / properties / notReached / description
      Previous value: -"The ids the call did not reach - its time ran out, its connection to the mailbox was lost, or the mailbox refused it whole, as the thread that met the refusal says - each left untouched: make the same call again with them."New value: +"The ids the call did not reach - its time ran out, its connection to the mailbox was lost, or the mailbox refused it whole, as the thread that met the refusal says - each left untouched, for the same call again."
    • changedOutput schema / properties / threads / items / properties / outcome / description
      Previous value: -"done, whole; notDone, left as it was, reason saying why; possiblyDone, moved in part - messages saying which were - or asked with no answer back, so it may have moved: read it again with threads_get, or messages_get for a message, before acting on it again."New value: +"done, whole; notDone, left as it was, reason saying why; possiblyDone, moved in part - messages saying which were - or asked with no answer back, so it may have moved, which threads_get, or messages_get for a message, reads before it is acted on again."
  3. Changed2 schema fields changed
    • changedOutput schema / properties / messages / items / properties / skipped / enum
      Previous value: -[
      -  "sent",
      -  "drafts",
      -  "deleted",
      -  "queued"
      -]New value: +[
      +  "sent",
      +  "drafts",
      +  "deleted",
      +  "queued",
      +  "unsynced"
      +]
    • changedOutput schema / properties / threads / items / properties / messages / items / properties / skipped / enum
      Previous value: -[
      -  "sent",
      -  "drafts",
      -  "deleted",
      -  "queued"
      -]New value: +[
      +  "sent",
      +  "drafts",
      +  "deleted",
      +  "queued",
      +  "unsynced"
      +]
  4. Changed1 schema field changed
    • changedOutput schema / properties / notReached / description
      Previous value: -"The ids the call did not reach - its time ran out, or the mailbox refused it whole, as the thread that met the refusal says - each left untouched: make the same call again with them."New value: +"The ids the call did not reach - its time ran out, its connection to the mailbox was lost, or the mailbox refused it whole, as the thread that met the refusal says - each left untouched: make the same call again with them."
  5. Changed5 schema fields changed
    • addedInput schema / properties / ids
      Added value: +{
      +  "description": "2 to 100 threadIds - or with scope message message ids - in place of id, acted on in one call.",
      +  "items": {
      +    "description": "The provider's own identifier.",
      +    "pattern": "^[A-Za-z0-9_=-]{1,512}$",
      +    "type": "string"
      +  },
      +  "maxItems": 100,
      +  "minItems": 2,
      +  "type": "array"
      +}
    • changedInput schema / required
      Previous value: -[
      -  "mailbox",
      -  "id"
      -]New value: +[
      +  "mailbox"
      +]
    • addedOutput schema / properties / notReached
      Added value: +{
      +  "description": "The ids the call did not reach - its time ran out, or the mailbox refused it whole, as the thread that met the refusal says - each left untouched: make the same call again with them.",
      +  "items": {
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
    • addedOutput schema / properties / threads
      Added value: +{
      +  "description": "Each thread the call reached, with ids.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "id": {
      +        "type": "string"
      +      },
      +      "labelIds": {
      +        "anyOf": [
      +          {
      +            "items": {
      +              "type": "string"
      +            },
      +            "type": "array"
      +          },
      +          {
      +            "type": "null"
      +          }
      +        ]
      +      },
      +      "messages": {
      +        "items": {
      +          "additionalProperties": false,
      +          "properties": {
      +            "done": {
      +              "type": "boolean"
      +            },
      +            "id": {
      +              "type": "string"
      +            },
      +            "restoredTo": {
      +              "type": "string"
      +            },
      +            "skipped": {
      +              "enum": [
      +                "sent",
      +                "drafts",
      +                "deleted",
      +                "queued"
      +              ],
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "id",
      +            "done"
      +          ],
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "outcome": {
      +        "description": "done, whole; notDone, left as it was, reason saying why; possiblyDone, moved in part - messages saying which were - or asked with no answer back, so it may have moved: read it again with threads_get, or messages_get for a message, before acting on it again.",
      +        "enum": [
      +          "done",
      +          "notDone",
      +          "possiblyDone"
      +        ],
      +        "type": "string"
      +      },
      +      "reason": {
      +        "description": "Why it is not done, as a refusal of the whole call names it.",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "id",
      +      "outcome"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "id",
      -  "labelIds"
      -]
  6. Changed1 schema field changed
    • changedInput schema / properties / importance / description
      Previous value: -"The importance each message it reaches takes: an Outlook mailbox sets its own, and a Gmail mailbox whose provider is google marks high as important and normal or low as not. A mailbox whose provider is imap keeps none."New value: +"The importance each message it reaches takes: an Outlook mailbox sets its own, and a Gmail connected by Google sign-in marks high as important and normal or low as not. A mailbox whose provider is imap keeps none."
  7. Changed2 schema fields changed
    • addedInput schema / properties / flag
      Added value: +{
      +  "description": "On an Outlook mailbox, a follow-up flag on these days, set as adding STARRED sets one. No other mailbox keeps a date on a flag: adding STARRED flags mail there without one.",
      +  "properties": {
      +    "due": {
      +      "description": "The day it is due, as 2026-10-30.",
      +      "format": "date",
      +      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +      "type": "string"
      +    },
      +    "start": {
      +      "description": "The day it starts; today where left out.",
      +      "format": "date",
      +      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "due"
      +  ],
      +  "type": "object"
      +}
    • addedInput schema / properties / importance
      Added value: +{
      +  "description": "The importance each message it reaches takes: an Outlook mailbox sets its own, and a Gmail mailbox whose provider is google marks high as important and normal or low as not. A mailbox whose provider is imap keeps none.",
      +  "enum": [
      +    "high",
      +    "normal",
      +    "low"
      +  ],
      +  "type": "string"
      +}
  8. Changed2 schema fields changed
    • changedInput schema / properties / addLabelIds / items / pattern
      Previous value: -"^[A-Za-z0-9_-]{1,128}$"New value: +"^[A-Za-z0-9_=-]{1,512}$"
    • changedInput schema / properties / removeLabelIds / items / pattern
      Previous value: -"^[A-Za-z0-9_-]{1,128}$"New value: +"^[A-Za-z0-9_=-]{1,512}$"
  9. Changed1 schema field changed
    • addedOutput schema / properties / messages / items / properties / skipped
      Added value: +{
      +  "enum": [
      +    "sent",
      +    "drafts",
      +    "deleted",
      +    "queued"
      +  ],
      +  "type": "string"
      +}
  10. Changed2 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
  11. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare destructive=true, idempotent=true, readOnly=false, but the description goes well beyond that by explaining provider-specific label semantics for STARRED, SPAM, INBOX, TRASH, folder moves, skipped messages, partial outcomes, and untouched sent/drafts. This is rich behavioral context for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The content is a single very long run-on paragraph with repeated clauses and no structural separation, so critical rules are buried mid-sentence. It is comprehensive but poorly organized and difficult to scan.

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

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter mutation tool with nested flag fields and an output schema, the description covers provider differences, batching, result states, and skip/partial cases thoroughly. Nothing material appears missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, with descriptions for id, ids, scope, mailbox, importance, flag, and the label arrays. The description adds meaningful semantics for batch behavior (2-100 as one action), scope=message, label-source, and provider restrictions, though it does not add much beyond the schema for importance or flag.

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?

Opens with a specific verb and resource: 'Apply and remove labels on one thread, or one message of it,' and names concrete outcomes (folder, star, read/unread). It distinguishes label ids from labels_list and points to threads_archive, threads_trash, threads_untrash, threads_get, and messages_get for adjacent operations, so the agent can identify the tool.

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?

It names alternatives and exclusions: labels_list for ids, threads_archive for removing from the inbox, threads_trash and SPAM for binning, threads_untrash for restoring, plus rules for INBOX and folder moves. However, the guidance is buried in a dense paragraph rather than stated as a clear upfront when-to-use rule, and there is no concise 'use this versus X' summary.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.