Skip to main content
Glama

Agent Books: one agent's payments and receipts for a period, signed and logged (free)

agent_books
Read-onlyIdempotent

Use this when someone needs a record they can hand to an accountant, an auditor, a platform or a counterparty: what one registration paid and received on Base in a closed month (period=YYYY-MM) or since its first event (period=to-date, the default). Returns counted payments (count, USD, what left the agent's control, what went into its own positions, payees, split by token, ten largest payees), what was left out and why (routing hops, own transfers, payments before registration), counted receipts (count, USD, senders, the part from wallets of other registered agents), detections logged in the period and transfers of the registration. The statement is signed with Ed25519, its hash is a leaf of our signed statement log and a daily Base transaction commits to that log; the answer says how to check each step without trusting us. One statement per agent, period and day; the answer's permalink returns that same statement on any later day. A record of observed facts under agent.books.v1: not an audit, not an opinion, says nothing about who owns the agent, about tax, or about safety.

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": {
      "agent": "<agent>"
    },
    "name": "agent_books"
  }
}

Input Schema

NameRequiredDescriptionDefault
agentYesAgent token id, act_8453_N, slug or bound wallet
periodNoYYYY-MM for a closed UTC month, or to-date (default)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.3/5.0
Behavior5/5

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

Annotations declare read-only, idempotent, non-destructive, closed-world, so safety is already covered; the description still adds a great deal beyond them. It discloses the Ed25519 signature, the statement-log leaf hash, the daily Base commitment, and how each step can be verified without trusting the provider. It also states determinism (one statement per agent, period and day; stable permalink), which is exactly the behavioral context an agent needs for a financial record.

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 "Use this when" condition, and every sentence carries content (scope, return contents, verification chain, determinism, disclaimers). The cost is density: one very long run-on sentence with nested parenthetical lists of counted items strains readability, so it is efficient but not clean.

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?

There is no output schema, so the description must describe the return payload, and it does: counted payments, exclusions and why, counted receipts, detections, registration transfers, plus signature and verification steps. For a reporting/compliance tool, nothing an agent needs in order to call it and interpret the result 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 the baseline is 3. The description goes beyond the schema by interpreting period values: YYYY-MM means a closed UTC month, to-date means since the registration's first event and is the default. That resolves the ambiguity of choosing a period value, though it adds nothing further about the agent identifier beyond the schema's token/act_/slug/wallet list.

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?

States a specific verb+resource+scope: what one registration paid and received on Base, for a closed month or since its first event. The scope and content are unambiguous. It does not differentiate itself from the similarly named sibling agent_statement (or agent_record), so an agent must infer which produces the signed statement vs. other record types.

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?

"Use this when someone needs a record they can hand to an accountant, an auditor, a platform or a counterparty" gives a concrete use context. The closing sentence adds useful exclustions (not an audit, not an opinion, not about ownership, tax, or safety). It stops short of naming an alternative tool or an explicit when-not condition, so a 4 rather than a 5.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.