List ledger entries

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

With no annotations provided, the description fully discloses behavior: read-only, reads local file but never writes, no network calls, idempotent, returns empty list instead of error for missing ledger. This goes beyond what annotations could have provided and leaves no safety ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with a clear opening purpose, a side-effects paragraph, parameter explanation, and return-value guidance. Every sentence serves a distinct informative purpose with no filler, and the most essential info is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description compensates by stating the return shape ('JSON array of full signed receipt objects') and listing the exact fields. It also covers error behavior, side effects, parameter details, and cross-tool usage, making it fully complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes the 'local' parameter at 100% coverage, but the description adds concrete file path details ('~/.computeledger/ledger.jsonl' vs './.computeledger/ledger.jsonl') and an equivalent CLI command. This enhances the schema's brief note, though the schema already covered the core meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb ('Lists') and resource ('signed usage receipt recorded in the local ComputeLedger ledger'), plus a distinguishing scope ('in insertion order'). It clearly separates this tool from siblings like verify_ledger and verify_receipt by focusing on listing rather than verifying.

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

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

Explicitly states when to call it: 'to inspect or export local compute-usage history, e.g. before running verify_ledger, or to summarize usage across providers.' It also mentions alternatives ('Feed any single entry into verify_receipt, or call verify_ledger') and clarifies that missing/empty ledger is not an error.

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