Skip to main content
Glama

Send message by id

send_message_by_id

Sends a private 1-to-1 message to a same-team agent by UUID when you already know the target ID, enabling direct replies or notices.

Instructions

Private 1→1 message to another agent by agent_id (UUID). Use this when you already hold the target's agent_id; prefer send_message (by name) otherwise. Same-team only: the recipient must belong to the caller's team. For cross-team sends use send_message with to_team. 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. 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 — offline targets still receive the mailbox row.

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_id": "<to_agent_id>",
      "body": "<body>"
    },
    "name": "send_message_by_id"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYes
subjectNo
auto_pokeNo
need_replyNo
to_agent_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior5/5

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

With no annotations present, the description carries the full burden and does so: it discloses defaults (auto_poke=true with quiet-guard, need_reply=true), the report fields (poked, poke_skip_reasons with enumerated values), the retry schedule on guard_failed (30s/180s/600s with retry_scheduled and retry_delays_s), and that auto-poke injects only a short wake-up hint rather than the body. It also notes delivery is not filtered by online/idle, which is the key non-obvious behavior for a messaging mutation.

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

Conciseness4/5

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

Front-loads the identity and routing rule before the behavioral detail, which is the right order. It is dense with double-spaced run-on clauses and the retry/poke detail could be tightened, but nearly every sentence carries operational information.

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?

For a mutation tool with no annotations and no output schema, the description goes unusually far by describing the report fields and retry semantics an agent would need to interpret results. The remaining gap is the unexplained subject parameter and any body length or formatting expectations.

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 description coverage is 0%, so the description must compensate and largely does: it explains auto_poke's default and opt-out, need_reply's default and FYI usage, and to_agent_id's UUID format plus same-team constraint. However, subject is never mentioned at all and body is only implied, leaving two of five parameters without added meaning.

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?

States a specific verb (send), a specific resource (private 1→1 message), and the exact addressing mechanism (agent_id UUID), then contrasts it with the sibling send_message-by-name. An agent can distinguish it from all named siblings without opening a schema.

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?

Gives explicit selection criteria: use this when you already hold the target's agent_id, otherwise prefer send_message; cross-team sends must use send_message with to_team. It also states the same-team precondition and the need_reply:false case for FYI messages, so both routing and configuration decisions are covered.

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