summarize_ledger

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

With no annotations, the description carries the burden well: it discloses that output goes to a new file and is never overwritten, that `full` summaries contain whole quotes and should be kept private, and how the HTML's print style behaves (link targets shown, records not split where possible). The gap is that "levels" and "the publication check" are deferred to a sibling's description, so the agent may not see those semantics here.

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?

Four sentences, each carrying distinct information: the action, level/publication semantics, the overwrite guarantee, the privacy warning, and the PDF workflow. The core action is front-loaded and nothing is redundant.

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?

An output schema exists, so return values need not be explained, and the file-write behavior is well covered. But for a tool whose levels drive privacy and content differences, leaving `masked`, `locator`, `include_withdrawn`, and the "publication check" undefined here (relying on export_ledger's description) leaves an agent unable to choose a level confidently.

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 coverage is 0% — all four parameters have only bare titles — so the description must compensate and largely does not. It clarifies `out`'s non-overwrite behavior and names `full` as a level value, but never explains `masked` or `locator`, never mentions `include_withdrawn`, and never says what `path` points to (source ledger).

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?

States a specific verb and artifact: "Write a standalone HTML summary of the records, grouped by claim, to a new file." That is clearly distinct from add_record/get_record and even hints at grouping semantics. However, differentiation from the closest sibling (export_ledger) is only implicit via the cross-reference for levels and the publication check, rather than an explicit statement of which tool to pick.

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?

Gives real usage context: levels and the publication check behave as in `export_ledger`, `out` is never overwritten, and PDF output should be produced by printing the HTML from a browser. It also adds a handling caveat for `full` summaries. It stops short of an explicit "use this instead of export_ledger when you need a human-readable HTML artifact" routing statement.

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