mutation_log_export

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

Annotations are absent, so the description carries the full burden, and it delivers key behavioral facts: it is non-destructive ('Render'), reads a local JSONL file only, and makes 'zero API calls' — implying no auth, no rate limits, and no network failure modes. It does not explain how it relates to the undo/backup mutation system, but the core safety and execution profile is disclosed.

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?

Two front-loaded sentences totaling roughly 29 words. The first defines what and how, the second defines scope and side-effect profile; no filler and no repetition of schema content.

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?

For a simple read/report tool with no annotations and no output schema, the description covers source, formats, filters, and local-only behavior. It falls short on the unbacked 'uri-filtered' claim and on how the report output maps to the response_format parameter, leaving some agent-facing ambiguity.

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 80% with solid descriptions for from/to, format, max_results, and response_format, so the schema already carries the parameter meaning. The description's 'date/uri-filtered' confirms the date range but claims a uri filter with no corresponding parameter in the schema, and it doesn't clarify how the format (csv/markdown) and response_format (concise/detailed/json) enums interact.

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 resource — 'Render the JSONL mutation history' — plus output formats (CSV or markdown) and filters (date/uri). 'Local file only, zero API calls' distinguishes it from the many Spotify-API-backed export/search siblings, and 'audit trail' positions it beside undo/verify tools rather than competing with them.

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?

The description implies when this applies ('Local file only, zero API calls' → offline audit of the mutation log), but names no alternatives or exclusions. With a large sibling set including history_search, export_listening_history, undo_mutation, and receipt_lookup, explicit routing ('use X when you want Y') would meaningfully help an agent choose correctly.

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