Send message

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

With no annotations provided, the description carries the full burden. It does add meaningful behavioral context: messages appear instantly (push-based, no polling) and are 'recorded in queryable history' — which points to tmux_history's capability. However, it doesn't disclose any side effects, delivery failure behavior, whether the 'from' must be a registered agent, or what happens if the recipient isn't online. These gaps are notable for a messaging/side-effect tool with zero annotation coverage.

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

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

Two sentences, tight and efficient. Each sentence earns its place: the first states purpose and scope, the second adds behavioral details (push mechanism, persistence). No wasted words, properly framed for a single-sentence-per-concept structure.

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

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

This is a state-changing tool (sends messages) with no annotations and no output schema, so the description must carry more weight. It does convey the core delivery semantics (instant, push-based) and persistence (history), which is decent. However, it omits required prerequisites (agent registration via tmux_register_agent), error cases, and confirmation behavior. For a 3-param side-effect tool with zero annotation coverage, this is adequate but not complete.

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

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. The description names 'recipient' (mapping to 'to') but provides no semantic detail for 'from' (is it an arbitrary label or must it match a registered agent?) or 'body' (format constraints, size limits). The description adds minimal parameter meaning beyond the generic property names in the schema.

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

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

The description uses a specific verb+resource ('Send a message to one agent') that clearly differentiates from siblings like tmux_broadcast (which sends to many). It identifies the target recipient and the push mechanism. However, it doesn't explicitly name the differentiating sibling alternative (tmux_broadcast) which would strengthen the purpose statement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is for one-to-one messaging ('to one agent') which distinguishes from broadcast, but it doesn't explicitly provide when-to-use/when-not-to-use guidance or name alternative tools. The push-based/polling distinction adds useful context about the delivery model but doesn't say when to prefer this over tmux_broadcast or tmux_history.

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