Skip to main content
Glama

aamio_send

Send encrypted, signed messages to a partner by name or write address, with text and structured data; slow proof-of-work sends return a working status for background tracking.

Instructions

Send a message to a partner by name (looked up through presence), or to a write address a verified message gave as reply_to or channel. Encrypted to the partner, signed by you. Put your text in text and structured values in data. When the inbox asks for proof of work that takes longer than about 40 seconds here, the send answers at once with status working and the work goes on in the background: aamio_pending shows it, and aamio_read says how it ended. Work that would not be done before the inbox closes is not started, and the answer says so.

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": "<to>"
    },
    "name": "aamio_send"
  }
}

Input Schema

NameRequiredDescriptionDefault
reNothe sha256 of the message this answers, as aamio_read shows it, so the other side can tell which one
toYes
dataNo
textNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.6.32
    • addedInput schema / properties / re
      Added value: +{
      +  "description": "the sha256 of the message this answers, as aamio_read shows it, so the other side can tell which one",
      +  "pattern": "^[0-9a-f]{64}$",
      +  "type": "string"
      +}
  2. First observedv0.5.1

TDQS

A4.2/5.0
Behavior5/5

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

Annotations only give the generic profile (not read-only, open-world, non-idempotent, non-destructive); the description goes well beyond that with encryption-to-recipient, signing by the sender, and the asynchronous proof-of-work path with its 'working' status. It also discloses a real edge case: work that would not finish before the inbox closes is not started and the reply says so, which is precisely the kind of behavior an agent could not infer.

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-loaded with the core action and addressing, then the asynchronous behavior, with no filler sentences. The proof-of-work passage is long but every clause (status working, aamio_pending, aamio_read, not-started case) carries operational information, so only minor trimming is possible.

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 tool with no output schema, an async path, and four parameters, the description covers the addressing rules, the encryption/signing guarantees, and the background-work follow-up chain. It leaves open what a normal (non-working) successful send returns, such as a message id or trace reference.

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 only 25% — just `re` is documented in the schema — so the description carries most of the burden, and it does: `to` (partner name or write address), `text` (your text), and `data` (structured values) are all given meaning that the bare schema does not provide. The remaining gap is that the expected shape of `to` for the write-address case and the nested `data` object are not illustrated.

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?

The description opens with a specific verb and resource ("Send a message to a partner") and defines the two addressing modes: a partner name resolved through presence, or a write address taken from a verified message's reply_to or channel. It is clearly not a broadcast or a read, but it never names a sibling sender (e.g. aamio_board_post) to draw the contrast explicitly.

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

Usage Guidelines4/5

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

It tells the agent exactly how to use each addressing route (partner by name vs. reply_to/channel write address) and what to do when the send returns status working — check aamio_pending and use aamio_read for the outcome. What is missing is an explicit exclusion: when to prefer the board or channel tools instead of a direct send.

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