Skip to main content
Glama
Sign In

Dock

by ai.trydock
OverviewDiscussionsAdmin

send_message

Send a direct message to another agent or human in the messaging substrate. Wires through cue.dock.svc, the same path the /live UI uses, so the recipient sees this message in their drawer (and, once they have a Dock-connected agent worker running, their agent harness's inbox). Address format is <agent_slug>@<user_slug>: flint@socrates targets the flint agent owned by user socrates; self@<user_slug> targets a human's synthetic self-agent (use this to message a human directly when you don't know which of their agents to ping). Use this to message a HUMAN (self@<user_slug>); to reach an agent use message_teammate (send_message refuses agent recipients — see below). Don't use it as a chat-ops side-channel for things that belong in workspace events. Sender identity follows the caller: agent callers send AS themselves, user callers send AS their self-agent (self@<their_slug>). Body cap is 32,000 chars. Returns { messageId, threadId, to } on success. IMPORTANT: this tool QUEUES a message to the recipient's inbox — it does NOT wake or run a recipient agent. To actually reach an AGENT (deliver AND wake it), use message_teammate. send_message to an agent is REFUSED with an error (code -32602) — it would only file to their inbox without a wake, so the message would strand unacted-on. Use send_message ONLY for humans (self@<user_slug>) or when you deliberately want a human inbox drop without a wake. The recipient is resolved against the substrate's identity space, NOT against your accessible workspace set, this is messaging, not workspace write access. Pre-cue.dock.svc-deploy environments return cue_not_configured (caller treats as 'messaging not deployed yet').

Input Schema

NameRequiredDescriptionDefault
toYesRecipient address in the form `<agent_slug>@<user_slug>`. Examples: `flint@socrates` (agent), `self@govind` (human's self-agent — use to DM a person directly). You may also pass an agent's stable id (`agt_...`) exactly as returned in `address_book`'s `agentId`. PREFER the id: an address is derived from the agent's slug, which does not follow a rename, so an address built from an agent's current display name can fail to resolve. The id never changes.
bodyYesMessage text. Plain string, 1-32000 chars. `@<slug>` mentions inside the body CC the named agent on the message.
replyToNoOptional cue message id to thread under. When set, the recipient's drawer renders this as a reply with an inline parent-preview. Get the id from a prior `send_message` response or from the recipient's inbox listing.
send_atNoOptional ISO-8601 UTC timestamp to schedule the message for future delivery (e.g. `2026-06-04T15:00:00Z`). Omit to send now. A past timestamp is treated as send-now. Honored only where scheduled send is enabled; otherwise ignored. `scheduled_at` is accepted as an alias.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / to / description
      Previous value: -"Recipient address in the form `<agent_slug>@<user_slug>`. Examples: `flint@socrates` (agent), `self@govind` (human's self-agent — use to DM a person directly). You may also pass an agent's stable id (`agt_...`) exactly as returned in `address_book`'s `agentId`. PREFER the id: an address is derived from the agent's slug, which does not follow a rename, so an address built from a teammate's current display name can fail to resolve. The id never changes."New value: +"Recipient address in the form `<agent_slug>@<user_slug>`. Examples: `flint@socrates` (agent), `self@govind` (human's self-agent — use to DM a person directly). You may also pass an agent's stable id (`agt_...`) exactly as returned in `address_book`'s `agentId`. PREFER the id: an address is derived from the agent's slug, which does not follow a rename, so an address built from an agent's current display name can fail to resolve. The id never changes."
  2. Changed1 schema field changed
    • changedInput schema / properties / to / description
      Previous value: -"Recipient address in the form `<agent_slug>@<user_slug>`. Examples: `flint@socrates` (agent), `self@govind` (human's self-agent — use to DM a person directly)."New value: +"Recipient address in the form `<agent_slug>@<user_slug>`. Examples: `flint@socrates` (agent), `self@govind` (human's self-agent — use to DM a person directly). You may also pass an agent's stable id (`agt_...`) exactly as returned in `address_book`'s `agentId`. PREFER the id: an address is derived from the agent's slug, which does not follow a rename, so an address built from a teammate's current display name can fail to resolve. The id never changes."
  3. Changed1 schema field changed
    • addedInput schema / properties / send_at
      Added value: +{
+  "description": "Optional ISO-8601 UTC timestamp to schedule the message for future delivery (e.g. `2026-06-04T15:00:00Z`). Omit to send now. A past timestamp is treated as send-now. Honored only where scheduled send is enabled; otherwise ignored. `scheduled_at` is accepted as an alias.",
+  "type": "string"
+}
  4. Added

TDQS

A4.4/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 burden and delivers: 32,000-char body cap, queue-not-wake semantics, the -32602 refusal for agent recipients, sender-identity resolution, identity-space vs workspace-scope distinction, and the cue_not_configured failure mode. It also states the return shape.

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 queue-vs-wake distinction and the message_teammate redirect are restated three or four times, and the opening 'another agent or human' framing is immediately retracted. The core facts are front-loaded but the piece is padded and repetitive.

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 4-param mutation tool with no annotations and no output schema, the description covers invocation, addressing, failure modes, deployment caveats, and the return value. Nothing an agent needs to call it correctly is missing.

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 baseline is 3; the description adds genuine semantic framing on top by explaining the self-agent concept and the human-vs-agent addressing distinction, though the terse `<agent_slug>@<user_slug>` mechanics largely duplicate the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb+resource ('Send a direct message') and names the recipient substrate. It explicitly distinguishes itself from `message_teammate`, but the opening line 'to another agent or human' is contradicted later when it says agent recipients are REFUSED, creating a slightly muddy first impression before the correction lands.

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?

Explicit when-to-use (humans via self@<user_slug>) and when-not (agents, which belong on message_teammate; chat-ops side-channels). It names the alternative tool and the exact condition selecting it, plus the consequence of misusing it (error -32602).

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

All Dock toolsInspect
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