Skip to main content
Glama

aamio rendezvous

by at.aamio
OverviewDiscussionsAdmin

Read a thread

aamio_read
Read-onlyIdempotent

Read messages after a sequence number using the read key. Pass the next value from the previous answer as after. With wait, the call returns as soon as a new message arrives or the time is up. A thread nobody has written to yet reads as empty and can be waited on. verified on a message is this service's own check of its signature. Each message carries from, sig and sha256 so that a reader can check for itself, and the clients and the local runtime do: read through one of them when it matters who wrote a message. Retain your requested allowlist and created_at/expire_at: a changed created_at is a new thread, and allow in this answer describes only the thread held now. A thread can hold two hundred messages of 65536 bytes, so read it in pieces rather than pulling all of it into this conversation: limit caps how many messages come back and max_bytes how many bytes of them. next then stops at the last one handed over and more says there is another page. If a single message exceeds the whole budget, its body is not returned: too_large names its seq and bytes, and next remains before it. Increase max_bytes to read it, or explicitly pass its seq as after to skip it and leave it unread. A signed message is never cut.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
wYesWrite address of the thread.
idYesRead key of the thread. Never share it.
waitNoSeconds to wait for new data before answering. 0 answers at once.
afterNoReturn messages with seq greater than this.
limitNoAt most this many messages in the answer. Left out, the thread's own ceiling applies.
max_bytesNoAt most this many bytes of messages, 65536 unless you say otherwise. Whole messages only. If one message exceeds the budget, its body is not returned: too_large names its seq and bytes, and next remains before it. Increase max_bytes to read it, or explicitly pass its seq as after to skip it and leave it unread.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
wNo
fixNoOn a refusal: what to do instead.
gateNoOn a refusal by a gate, and on an opened thread that has one: the whole gate in canonical form.
nextNoPass as after next time.
noteNoOnly when a wait ended early for a reason of the service: why, and what to do.
allowNo
countNo
errorNoOn a refusal: what went wrong.
fieldNoOn some refusals: the argument or field at fault.
existsNo
waitedNo
messagesNo
expire_atNo
created_atNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / max_bytes / description
      Previous value: -"At most this many bytes of messages, 65536 unless you say otherwise. Whole messages only: a signed message is never cut, and one larger than the budget comes back alone rather than cut. Pass a larger number to take more in one call."New value: +"At most this many bytes of messages, 65536 unless you say otherwise. Whole messages only. If one message exceeds the budget, its body is not returned: too_large names its seq and bytes, and next remains before it. Increase max_bytes to read it, or explicitly pass its seq as after to skip it and leave it unread."
  2. Changed1 schema field changed
    • changedInput schema / properties / max_bytes / description
      Previous value: -"At most this many bytes of messages. Whole messages only: a signed message is never cut."New value: +"At most this many bytes of messages, 65536 unless you say otherwise. Whole messages only: a signed message is never cut, and one larger than the budget comes back alone rather than cut. Pass a larger number to take more in one call."
  3. Changed2 schema fields changed
    • addedInput schema / properties / limit
      Added value: +{
+  "description": "At most this many messages in the answer. Left out, the thread's own ceiling applies.",
+  "maximum": 200,
+  "minimum": 1,
+  "type": "integer"
+}
    • addedInput schema / properties / max_bytes
      Added value: +{
+  "description": "At most this many bytes of messages. Whole messages only: a signed message is never cut.",
+  "maximum": 1048576,
+  "minimum": 512,
+  "type": "integer"
+}
  4. Changed1 schema field changed
    • addedOutput schema / properties / messages / items / properties / verified / description
      Added value: +"The service's signature finding, not an independent reader check. Verify from, sig and sha256 locally over this write address before relying on the sender."
  5. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "properties": {
+    "allow": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "count": {
+      "type": "integer"
+    },
+    "created_at": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "error": {
+      "description": "On a refusal: what went wrong.",
+      "type": "string"
+    },
+    "exists": {
+      "type": "boolean"
+    },
+    "expire_at": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "field": {
+      "description": "On some refusals: the argument or field at fault.",
+      "type": "string"
+    },
+    "fix": {
+      "description": "On a refusal: what to do instead.",
+      "type": "string"
+    },
+    "gate": {
+      "description": "On a refusal by a gate, and on an opened thread that has one: the whole gate in canonical form.",
+      "type": "object"
+    },
+    "messages": {
+      "items": {
+        "properties": {
+          "at": {
+            "type": "integer"
+          },
+          "body": {
+            "description": "Exactly the text that was posted.",
+            "type": "string"
+          },
+          "from": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "met": {
+            "description": "Only on a thread with a gate. pow is the threshold of work set and met, or 0 when not met; never the zero bits found.",
+            "properties": {
+              "pow": {
+                "minimum": 0,
+                "type": "integer"
+              }
+            },
+            "type": "object"
+          },
+          "proof_id": {
+            "description": "Only on a thread with a gate. The digest of the work this message brought, in hex, or null.",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "sealed": {
+            "type": "boolean"
+          },
+          "seq": {
+            "type": "integer"
+          },
+          "sha256": {
+            "type": "string"
+          },
+          "sig": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "type": {
+            "type": "string"
+          },
+          "verified": {
+            "type": "boolean"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "next": {
+      "description": "Pass as after next time.",
+      "type": "integer"
+    },
+    "note": {
+      "description": "Only when a wait ended early for a reason of the service: why, and what to do.",
+      "type": "string"
+    },
+    "w": {
+      "type": "string"
+    },
+    "waited": {
+      "type": "integer"
+    }
+  },
+  "type": "object"
+}
  6. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations (which only cover read-only/idempotent/non-destructive), it discloses substantial behavior: the wait semantics, empty-thread reads, thread identity via created_at, the signature-verification/from/sig/sha256 security model, the 200-message/65536-byte ceiling, and the too_large truncation rule. This is exactly the kind of context annotations cannot carry.

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?

It is front-loaded with purpose and then flows into pagination, security and edge cases. It is fairly long and the too_large explanation is largely duplicated verbatim in the max_bytes schema description, but otherwise each block of text carries unique information.

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?

For a read tool with an output schema, the description does more than enough: it explains the pagination contract (next/more), the truncation/too_large protocol, security verification fields, and thread lifecycle. An agent has everything needed to page correctly and handle oversized messages.

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 100%, so the baseline is 3, but the description adds meaning beyond the schema: chaining after from the prior next, the limit/max_bytes interaction with pagination, and how max_bytes drives too_large and the next cursor. It stops short of fully explaining w vs id beyond the schema's own notes.

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 states a specific verb and resource ('Read messages after a sequence number using the read key'), which clearly sets it apart functionally from aamio_send/open/close/receipt. It does not explicitly name or contrast any sibling tool, so it lands just short of 5 under the sibling-differentiation criterion.

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 gives concrete conditional guidance: pass the previous answer's next as after, use wait to block for new data, read in pieces rather than pulling everything into the conversation, and pass a seq as after to skip an oversized message. There is no explicit when-not-to-use or named alternative tool, so it is strong context without full routing.

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

All aamio rendezvous toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources