Skip to main content
Glama

File a thread in a folder

file_conversation

Files a thread where you say: "archive" puts it away, out of the Inbox and kept for good; "trash" throws it away, where it stays readable and can be brought back; "inbox" brings it back from wherever it was; or "folder_id" files it in a folder a person made (list_folders gives them), which becomes its home. One thread sits in one place, so filing it somewhere takes it out of where it was; a reply brings a thread back to the Inbox without taking it out of its folder. This is the gesture for tidying a mailbox, and "trash" is what "delete this thread" almost always means: nothing is lost for 30 days by default, or for the retention set on the account, after which the Trash deletes it for good, and delete_conversation is the other, immediate and final thing. It does not file spam: report_spam is that gesture, because filing as spam also blocks the sender. A thread of a helpdesk queue has the Trash as its one folder: "trash" throws it away (a spam, a phishing attempt, a prospecting mail nobody answers) and "inbox" brings it back to the view its status belongs to; "archive" is refused there, closing a case being how a queue puts it away. Filing never changes where a thread STANDS: a notice thrown in the Trash is still "open", among what is left to do. Give "status" (and "deal_stage") to settle that in the same gesture, as set_conversation_status would: "trash" with "closed" tidies away what nobody answers, "archive" with "answered" or "closed" puts away an exchange that is over. The status is recorded first, so a status refused leaves the thread where it was, and a thread that then cannot be filed answers that its status was recorded and why it stayed put. To file several threads in the same place, give conversation_id the list of their ids, in ONE call rather than one call per thread: the answer then lists in "results" the outcome of each thread in the order given ("ok", with its "result" or its "error") and counts "succeeded" and "failed". Each thread passes exactly the checks it would alone, so one refused or out of reach ("not found") leaves the others done, and the call is an error only when none succeeded.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "conversation_id": "<conversation_id>"
    },
    "name": "file_conversation"
  }
}

Input Schema

NameRequiredDescriptionDefault
folderNoWhere the thread goes: "archive" to put it away, "trash" to throw it away restorably, "inbox" to bring it back. "spam" is not one of them: call report_spam, which blocks the sender too. Leave it out when you give "folder_id".
statusNoWhere the thread stands: "open" for one nobody has taken, "customer_reply" when the contact has written back, "answered" once we replied, "delivery_failed" when our reply bounced, "in_progress" while someone works on it, "closed" when it is over.
folder_idNoA folder a person made in the thread's box, by its id from list_folders, instead of "folder".
deal_stageNoWhere the thread stands in the pipeline, in your own vocabulary, up to 128 characters. An empty string clears it.
conversation_idYesThe id of the conversation, as list_conversations gives it, or a list of up to 50 ids to do the same to every one of them in a single call.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses retention behavior for trash (30 days by default or the account retention setting), that filing does not change status, that status is recorded first so a refused status leaves the thread put, that replies return a thread to the Inbox without removing it from its folder, and that helpdesk queues refuse 'archive'.

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

Conciseness3/5

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

The information is front-loaded and every paragraph contains useful content, but the description is one long, dense run-on with embedded caveats and examples. It would be easier to scan if broken into clearly separated sections for destinations, status interaction, helpdesk queues, and batch behavior.

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 a five-parameter mutation tool with no output schema and complex branching behavior across folder, status, deal_stage, and batch conversation_id, the description covers the important behavioral boundaries: retention, status-recording order, partial batch failure, helpdesk restrictions, and alternatives to disjoint tools. An agent has enough information to choose this tool and invoke it correctly.

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 100%, so the schema already documents each parameter thoroughly. The description adds meaningful interaction semantics beyond the schema: folder_id and folder are mutually exclusive, status and deal_stage can be applied in the same gesture, and conversation_id accepts a list of up to 50 ids for batched filing with per-thread outcomes in 'results' plus 'succeeded'/'failed' counts.

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?

The description states a specific verb and resource ('Files a thread') and immediately enumerates the distinct destinations: archive, trash, inbox, or a user-created folder. It distinguishes the operation from siblings like delete_conversation, report_spam, and set_conversation_status by naming those alternatives and their different outcomes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance: 'archive' for putting away, 'trash' for restorable deletion, 'inbox' for restoring, and 'folder_id' for a person-made folder from list_folders. It also names the cases where other tools are correct: report_spam for spam because it blocks the sender, and delete_conversation for immediate permanent deletion.

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.

Resources