Skip to main content
Glama

Send message

send_message

Send a private one-to-one message to a named agent, optionally requiring a reply or auto-waking the recipient. Use for direct requests or no-response FYI updates.

Instructions

Private 1→1 message to another agent by name. By default auto-poke=true with quiet-guard (auto_poke:false opts out), and need_reply=true. Set need_reply:false for FYI/no-response-needed messages; recipients see need_reply in get_inbox. to_agent_name is the target's name within its team; bare names resolve on the caller's device, and name:device targets a specific device. For UUID-based sends use send_message_by_id. If the user refers to a recipient in the shorthand name(team) (e.g. skills-creator(default)), split it into to_agent_name=skills-creator and to_team=default. The daemon does NOT parse name(team), so the literal string fails to resolve (unknown_recipient). This is distinct from the name:device suffix, which the daemon DOES parse. REPLY RULE: when replying to a message returned by get_inbox, treat its from_device as authoritative — if it differs from your own device, you MUST send to from_name + ":" + from_device (bare from_name would resolve on YOUR device and miss the actual sender). Same-device replies can use the bare name. The safe fallback for unknown device is send_message_by_id({to_agent_id: from_agent_id, ...}). For multi-recipient use broadcast (same-team) or broadcast_to_role (same-team, by role). 除非用户明确指定 to_team, 不要跨 team 沟通 (explicitly set to_team only when user asks). Reports poked, poke_skip_reasons (no_pane, guard_failed, tmux_unavailable, self); on guard_failed daemon retries at 30s/180s/600s (retry_scheduled, retry_delays_s); stops early on poked. Auto-poke injects only a SHORT wake-up hint (新邮件 from , 请调 get_inbox 查看), NOT the body — read bodies via get_inbox. Delivery is NOT filtered by online/idle; direct and fan-out deliveries write mailbox rows for offline targets. The list_agents online flag reflects process liveness. DO NOT pre-verify the recipient via list_agents before calling send_message — this rule applies to BOTH same-team and cross-team sends (list_agents is caller-team scoped and CANNOT see cross-team agents, so a cross-team pre-check always falsely reports "missing"; for same-team sends the pre-check is pure waste). On miss send_message returns unknown_recipient cleanly with no side effects, so the correct pattern is "try send, then handle unknown_recipient" — never "list_agents first, then send".

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": {
      "to_agent_name": "<to_agent_name>",
      "body": "<body>"
    },
    "name": "send_message"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes
subjectNo
to_teamNo
auto_pokeNo
need_replyNo
to_agent_nameYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/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 thoroughly: it discloses auto_poke and need_reply defaults, delivery behavior for offline targets, the fact that auto-poke injects only a short wake-up hint rather than the body, unknown_recipient having no side effects, and retry timing after guard_failed.

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 purpose is front-loaded and almost every sentence carries useful operational detail, but the description is a dense wall of text mixing English and Chinese, with heavy emphasis and repeated warnings. It would be easier to scan if the naming rules, reply rule, and pre-verification rule were separated into clear clauses.

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?

Given that there are no annotations, no output schema, and six parameters with 0% schema coverage, the description is complete enough for correct invocation. It covers routing, defaults, reply targeting, cross-team restrictions, failure handling, and side effects.

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

Parameters5/5

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

Schema description coverage is 0%, so the description must explain parameter meaning, and it does: to_agent_name resolution rules (bare name, name:device, no name(team) parsing), to_team behavior, auto_poke opt-out, and need_reply semantics. The only minor gap is that subject and body are not explicitly described, but their meaning is evident and the tricky parameters are covered in detail.

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: 'Private 1→1 message to another agent by name.' It immediately distinguishes this from send_message_by_id and the broadcast siblings, so an agent can identify the correct tool without opening other schemas.

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 routing rules: use send_message_by_id for UUID sends, broadcast/broadcast_to_role for multi-recipient sends, and only set to_team when the user asks. It also includes a detailed reply rule and a clear directive not to pre-verify recipients with list_agents, which is exactly the when/when-not guidance an agent needs.

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