Chatway Live Chat

Assign Conversation

assign-conversation

Destructive

Assign or unassign an agent on one or more Chatway conversations. Identify the agent by UUID or an unambiguous name/email query and send all conversation UUIDs in one call. Set unassign to true to remove the agent; otherwise the agent is assigned. Conversations already in the requested state are left unchanged. Calls with more than one conversation require user confirmation; a single conversation is changed immediately. Use list-agents only when an agent_query match is ambiguous.

Input Schema

Name	Required	Description
`agent_id`	No	Agent UUID to assign or unassign. Required unless agent_query is provided.
`unassign`	No	Set to true to remove the agent from the conversations. Defaults to false, which assigns the agent.
`agent_query`	No	Agent name or email to resolve (e.g. "Nibir"). Required unless agent_id is provided. Use list-agents if the match is ambiguous.
`conversation_ids`	Yes	Conversation UUIDs to assign, from 1 to 30.
`confirmation_token`	No	Only for calls with more than one conversation: required after the confirmation challenge. Ask the user to approve before calling again with this token.

Output Schema

Name	Required	Description
`agent`	No
`queued`	No	True when several conversations were queued as background jobs.
`message`	No	Message describing the action or its result.
`agent_id`	No	UUID of the agent that was assigned or unassigned.
`ambiguous`	No	True when agent_query matched several agents; pick one from candidates.
`candidates`	No	Agents matching an ambiguous agent_query.
`affected_count`	No	Number of records the action will change.
`confirmation_token`	No	Pass back as confirmation_token after the user approves.
`expires_in_seconds`	No	How long the confirmation token stays valid.
`confirmation_required`	No	True when the user must approve before the action runs.
`queued_conversation_ids`	No	Conversation UUIDs queued for the action.
`skipped_conversation_ids`	No	Conversation UUIDs that were skipped.
`assigned_conversation_ids`	No	Conversations the agent was assigned to.
`unchanged_conversation_ids`	No	Conversations already in the requested state; nothing changed.
`unassigned_conversation_ids`	No	Conversations the agent was removed from.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedNov 6, 2026

changedInput schema / properties / confirmation_token / description

Previous value: -"Required after the confirmation challenge. Ask the user to approve before calling again with this token."New value: +"Only for calls with more than one conversation: required after the confirmation challenge. Ask the user to approve before calling again with this token."

addedInput schema / properties / unassign

Added value: +{
+  "description": "Set to true to remove the agent from the conversations. Defaults to false, which assigns the agent.",
+  "type": "boolean"
+}

changedOutput schema / properties / agent_id / description

Previous value: -"UUID of the assigned agent."New value: +"UUID of the agent that was assigned or unassigned."

addedOutput schema / properties / assigned_conversation_ids / description
```
Added value: +"Conversations the agent was assigned to."
```

addedOutput schema / properties / unassigned_conversation_ids

Added value: +{
+  "description": "Conversations the agent was removed from.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedOutput schema / properties / unchanged_conversation_ids

Added value: +{
+  "description": "Conversations already in the requested state; nothing changed.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Changed1 schema field changedNov 4, 2026

changedInput schema / properties / conversation_ids / description

Previous value: -"Conversation UUIDs to assign, from 1 to 100."New value: +"Conversation UUIDs to assign, from 1 to 30."

Changed2 schema fields changedOct 15, 2026

changedInput schema / properties / conversation_ids / description

Previous value: -"Conversation UUIDs to assign."New value: +"Conversation UUIDs to assign, from 1 to 100."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "affected_count": {
+      "description": "Number of records the action will change.",
+      "type": "integer"
+    },
+    "agent": {
+      "properties": {
+        "email": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "id": {
+          "description": "Agent UUID.",
+          "type": "string"
+        },
+        "name": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "type": "object"
+    },
+    "agent_id": {
+      "description": "UUID of the assigned agent.",
+      "type": "string"
+    },
+    "ambiguous": {
+      "description": "True when agent_query matched several agents; pick one from candidates.",
+      "type": "boolean"
+    },
+    "assigned_conversation_ids": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "candidates": {
+      "description": "Agents matching an ambiguous agent_query.",
+      "items": {
+        "properties": {
+          "email": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "description": "Agent UUID.",
+            "type": "string"
+          },
+          "name": {
+            "type": [
+              "string",
+              "null"
+            ]
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "confirmation_required": {
+      "description": "True when the user must approve before the action runs.",
+      "type": "boolean"
+    },
+    "confirmation_token": {
+      "description": "Pass back as confirmation_token after the user approves.",
+      "type": "string"
+    },
+    "expires_in_seconds": {
+      "description": "How long the confirmation token stays valid.",
+      "type": "integer"
+    },
+    "message": {
+      "description": "Message describing the action or its result.",
+      "type": "string"
+    },
+    "queued": {
+      "description": "True when several conversations were queued as background jobs.",
+      "type": "boolean"
+    },
+    "queued_conversation_ids": {
+      "description": "Conversation UUIDs queued for the action.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "skipped_conversation_ids": {
+      "description": "Conversation UUIDs that were skipped.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

First observedOct 15, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Beyond the annotations it discloses three non-obvious behaviors: no-ops for conversations already in the requested state, a confirmation-token gate for multi-conversation calls versus immediate execution for a single conversation, and name/email resolution with an ambiguity fallback. It does not say whether the assigned agent is notified, what happens if an agent is already assigned to some of the listed conversations, or why the tool is marked non-idempotent despite the no-op guarantee — a mild tension worth noting, though not a contradiction.

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

Conciseness5/5

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

Four sentences, front-loaded with the action, then identity resolution, then the no-op rule, then the confirmation/alternative rules. No sentence is redundant with the title, schema, or annotations, and nothing is buried.

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

Completeness4/5

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

With a full input schema, an output schema, and destructive/idempotency annotations already present, the description covers the risky parts an agent must know: the confirmation challenge, the batching limit context, and the ambiguity fallback. It stops short of describing permission requirements or side effects on the affected agents, which is the main remaining gap for a destructive mutation.

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 baseline is 3; the description still adds value by explaining that agent identity can be supplied as UUID or as a name/email query (with an ambiguity escape hatch) and by instructing the caller to batch all conversation UUIDs into one call rather than looping. The confirmation_token flow is also framed in terms of the call sequence, not just its type.

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 first sentence gives a specific verb pair (assign/unassign), the resource (agent on Chatway conversations), and the cardinality (one or more). It is immediately distinguishable from siblings like handoff-to-human, resolve-conversation, and list-agents, which is reinforced by the explicit routing note for list-agents.

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 states both branches of use (default assign vs. `unassign: true`), the exact condition that should route the agent elsewhere ("Use `list-agents` only when an `agent_query` match is ambiguous"), and the multi-conversation confirmation workflow. The only unstated alternative would be handoff-to-human, but the assign/unassign framing already separates these.

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

All Chatway Live Chat 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.

Resources

Need Help?