Skip to main content
Glama

aamio_trace

Read-onlyIdempotent

Inspect message delivery and read receipts for a counterpart by comparing stored sha256 hashes, shapes, sealing, and seen or answered claims to diagnose missing or empty messages.

Instructions

What this runtime sent to one counterpart and what came back, as hashes and shapes, never content. For each message sent: the address, seq and sha256 the service stored, whether it was sealed and how long it was, seen_by_them when a signed message from them names that sha256 as read and opened, and answered_by_them when one answers it. A claim covers the one message it names: a message nothing names is listed in no_read_claim and is unknown, not unread. For each message received: whether it opened, which fields it had, and which of yours it answers (re) or names as read (seen). Use it when a partner says a message did not arrive or arrived empty: the sha256 is what the service stored, byte for byte, and theirs should match. Every message this runtime sends is sealed to the recipient's key, so a reader without that key sees an envelope and no text. Without who, one line per counterpart.

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_trace"
  }
}

Input Schema

NameRequiredDescriptionDefault
whoNoa partner name, a key or a write address; leave out for everyone
limitNomessages each way, newest last; 20 by default

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.6.32

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent and non-destructive, and the description adds substantial context on top: outputs are hashes and shapes and never content, sent messages are sealed to the recipient's key so a reader without that key sees only an envelope, and a message named by no claim is 'unknown, not unread'. That last point is a genuinely important interpretive distinction that no annotation could express.

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 the core statement and every sentence carries information, including the definitions of seen_by_them, answered_by_them and no_read_claim. It is a dense single block with heavy coined terminology, which makes it slower to parse than it needs to be, but there is little filler.

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, the description carries the return-shape burden and does so in detail: what is reported per sent message (address, seq, sha256, sealed flag, length, seen_by_them, answered_by_them) and per received message (whether it opened, which fields, which of yours it answers or names as read). For a two-optional-parameter read-only tool, nothing an agent needs in order to call it or interpret results is missing.

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 100% so both parameters are already documented, yet the description still adds meaning: 'Without who, one line per counterpart' clarifies the omitted-argument behavior, and the surrounding text frames the per-message semantics that limit governs. It does not add further format detail for who (name vs key vs address beyond what the schema says).

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 states a precise scope: 'what this runtime sent to one counterpart and what came back, as hashes and shapes, never content', which tells an agent this is a per-message delivery/audit trace rather than a content reader. It is clear and specific, but it never names a sibling such as the receipt or read tools, so differentiation from them must be inferred.

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 an explicit trigger: 'Use it when a partner says a message did not arrive or arrived empty', and explains why this tool answers that question (the sha256 is what the service stored). It stops short of stating when not to use it or pointing to a named alternative for content inspection.

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