Cooper Email

Assign or claim a thread

cooper_assign_thread

Idempotent

Use this when a triage agent should hand a thread to a named assignee, or a worker should take an exclusive claim so another worker does not reply to the same thread. Requires auth. Same permission as updating thread labels. Inputs: inbox_id (required; inbox id, username, or email), thread_id (required), assignee (required; 1–64 characters: letters, digits, and . _ @ + : -), note (optional string of at most 500 characters; omit it to keep the current note; null clears it), lease_seconds (optional integer from 30 to 86400; when set, claimed_until is now plus that many seconds and the claim is exclusive), force (optional boolean, default false; true overwrites another assignee's active claim). The same assignee can renew its claim. A renew does not emit thread.assigned. A different assignee while an active claim is held returns HTTP 409 thread_claimed with assignee and claimed_until. Without lease_seconds the assignment is not exclusive and claimed_until is null. Returns {assignment:{object:"thread_assignment", inbox_id, thread_id, assignee, note, claimed_until, claim_active, assigned_at, updated_at}}. Unknown thread returns HTTP 404 thread_not_found. Another account's inbox returns inbox_not_found. Invalid fields return invalid_assignee, invalid_note, invalid_lease, or invalid_force.

Input Schema

Name	Required	Description
`note`	No	Optional note, at most 500 characters. Omit to keep the current note. Null clears it.
`force`	No	When true, overwrite another assignee's active claim. Default false.
`assignee`	Yes	Handle for the owner of this thread. 1–64 characters: letters, digits, and . _ @ + : -.
`inbox_id`	Yes	Inbox id (inb_…), username, or full email address owned by this key
`thread_id`	Yes	Thread id (thr_…) to assign
`lease_seconds`	No	When set, this is an exclusive claim until now plus this many seconds (30–86400). Omit for a plain assignment.

Output Schema

Name	Required	Description	Default
`assignment`	No	{object: thread_assignment, inbox_id, thread_id, assignee, note, claimed_until, claim_active, assigned_at, updated_at}.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "The new assignment.",
+  "properties": {
+    "assignment": {
+      "description": "{object: thread_assignment, inbox_id, thread_id, assignee, note, claimed_until, claim_active, assigned_at, updated_at}."
+    }
+  },
+  "type": "object"
+}

AddedOct 24, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Much richer than the annotations: it discloses auth and permission requirements, renew semantics, that a renew emits no thread.assigned event, the 409 thread_claimed conflict shape with assignee/claimed_until, and the non-exclusive default when lease_seconds is omitted. These are exactly the mutation traits the readOnly/idempotent hints cannot convey, though the return contract is largely duplicated from the output schema.

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 lead sentence is well front-loaded with the trigger scenario, but the 'Inputs:' block restates nearly every schema constraint verbatim (assignee charset, note limit, lease range, force default), which is redundant with structured fields. The tail of the paragraph is a dense run-on of error codes and a return shape that the output schema already covers.

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 mutation tool with six parameters, the description covers authentication, conflict behavior, renewal, error codes (thread_claimed, thread_not_found, inbox_not_found, invalid_*), and the default non-exclusive case. Nothing an agent needs to invoke it safely is missing, even though the output schema makes the return-value sentence optional.

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 already 100%, so the baseline is 3, but the description adds real semantics: lease_seconds makes the claim exclusive and sets claimed_until to now plus the lease, force overwrites another assignee's active claim, and omitting note preserves while null clears it. The character-class and range repetitions add little beyond the schema.

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 names a specific verb pair and resource ('hand a thread to a named assignee', 'take an exclusive claim') and gives the operational distinction between a plain assignment and an exclusive lease. An agent can distinguish this from cooper_update_thread or cooper_unassign_thread without inspecting schemas.

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 states the two concrete situations that call for this tool (triage handoff, worker exclusive claim so another worker doesn't double-reply), which is strong when-to-use guidance. It does not explicitly mention alternatives such as cooper_unassign_thread or cooper_update_thread, so routing against siblings is left partly to inference.

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

All Cooper Email tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.