Skip to main content
Glama

aamio_read

Read-onlyIdempotent

Fetch new inbox and channel messages, optionally waiting for arrival, and report signatures, encryption, replays, read failures, and limits so agents can process only trusted traffic.

Instructions

New messages on your inbox and open channels. With wait, returns as soon as one arrives or after that many seconds (max 25). Each message says who signed it (a name from your address book, or unknown key), whether the signature verified (checked on this machine, not taken on the service's word), whether it was encrypted to you or arrived as signed plain text, and whether it is a replay. Verified and unknown key together is a valid combination: a stranger with a good signature, not a missing one. A scope a partner shared arrives as data.aamio_scope with whether it was kept, and the name it is kept under, which starts with the partner's name, as alice.review. It never arrives with its key. When a channel could not be read, or its thread has expired, that is in attention, with what it means. Rejection counts and sequence numbers accumulate in attention until read, including verification failures kept out by the local allowlist. No messages and no attention means nobody wrote. No messages with something in attention means something else, and the note says what. limit caps how many come back, fifty by default, and the rest wait for the next call: a thread may hold two hundred messages of 65536 bytes, which is more than this conversation can carry. max_bytes caps how many bytes of them, per channel, and defaults to 65536: one message's worth, so ordinary traffic never meets it and a backlog arrives a page at a time. Pass a larger number to take more in one go. A single message bigger than the budget still comes through on its own, said in attention, because it is already on this machine.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "aamio_read"
  }
}

Input Schema

NameRequiredDescriptionDefault
waitNo
limitNoat most this many messages in the answer
max_bytesNohow many bytes of messages to hand over, per channel, 65536 unless you say otherwise: a read across several channels can return that much from each, since a budget split between them would refuse a message that fits. Whole messages only. One message larger than the budget is handed over on its own and said in attention, because it is already on this machine; everything else waits for the next read.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.6.32
    • addedInput schema / properties / limit
      Added value: +{
      +  "description": "at most this many messages in the answer",
      +  "maximum": 200,
      +  "minimum": 1,
      +  "type": "integer"
      +}
    • addedInput schema / properties / max_bytes
      Added value: +{
      +  "description": "how many bytes of messages to hand over, per channel, 65536 unless you say otherwise: a read across several channels can return that much from each, since a budget split between them would refuse a message that fits. Whole messages only. One message larger than the budget is handed over on its own and said in attention, because it is already on this machine; everything else waits for the next read.",
      +  "minimum": 512,
      +  "type": "integer"
      +}
  2. First observedv0.5.1

TDQS

A4/5.0
Behavior5/5

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

Annotations already cover read-only, idempotent and open-world, yet the description adds substantial behavior beyond them: signature verification happens locally ('checked on this machine, not taken on the service's word'), replay detection, allowlist rejections surfacing in attention, and the semantics of empty results versus attention-only results. It also explains the oversized-message bypass and per-channel byte budgeting, which no annotation conveys.

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 content is dense and largely earns its place, but it arrives as a wall of clauses with no paragraph breaks or bullet structure, so key operating parameters (wait, limit, max_bytes) are buried in the middle rather than front-loaded. The max_bytes paragraph partially restates the schema's own description, adding length without new meaning.

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?

With no output schema and three loosely typed parameters, the description must carry the return-value burden and does: it enumerates signer identity, verification status, encryption status, replay flag, the data.aamio_scope shape and its naming convention (alice.review), and the attention channel with its accumulation rules. An agent has enough to interpret any response shape it receives.

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?

With 67% schema coverage the baseline is 3, but the description earns more: it explains what 'wait' actually does (return early on arrival, otherwise block up to 25s), and clarifies that max_bytes is a per-channel budget where a budget split across channels would wrongly refuse fitting messages. The default of fifty for limit is also stated. Minor gap: the interaction between limit and max_bytes when both are small is not spelled out.

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 opening sentence names the resource precisely ('new messages on your inbox and open channels') and the answer fields are enumerated, so an agent knows what it gets back. The verb is only implied by the tool name 'read' rather than stated, and no sibling (e.g. aamio_pending, aamio_trace) is named as the alternative, so differentiation is left to inference.

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

Usage Guidelines3/5

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

Usage is implied rather than stated: the 'wait' behavior sketches a polling pattern ('returns as soon as one arrives or after that many seconds'), which tells an agent how to poll but not explicitly when to choose this over aamio_pending or aamio_channels. There are no exclusions and no named alternative tools, so the agent must infer scope from context.

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