backup_library

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

No annotations exist, so the description carries the full burden, and it delivers: 'read-only against Spotify' discloses the safety profile, while walk caps (SPOTIFY_MCP_FETCH_ALL_CAP, default 500), the output directory (SPOTIFY_MCP_BACKUP_DIR), and file mode 0600 disclose side effects, limits, and security handling. This goes well beyond a typical one-line backup description.

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?

Three short sentences, purpose front-loaded in the opening clause, with caps and file-location details in a compact tail. No filler, no repetition of schema content, every sentence earns its place.

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?

Covers the operational essentials — scope, safety, cap, output location, and file permissions — which is most of what an agent needs given zero required parameters. However, with no output schema it never hints at the tool's return value, and 'a local JSON file' vs 'Files land in...' leaves whether one or multiple files are written slightly ambiguous.

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 description coverage is 100%, so the schema already documents all four optional parameters, including the enum description for response_format, the dry_run preview semantics, and the max_results default. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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+resource: snapshots the ENTIRE library to a local JSON file, enumerating exact categories (liked tracks, saved albums/shows/episodes/audiobooks, followed artists, and playlists with items). The capitalized 'ENTIRE' plus the category list clearly distinguishes it from narrower export siblings like snapshot_playlist or export_playlist_json.

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 scope statement ('ENTIRE library', all categories, local JSON file) implies the use case, but it never names alternatives or exclusions. With near-identical siblings in the set (export_library_json, export_all_playlists, restore_library_snapshot, list_backups), an agent gets no explicit routing guidance for which tool to pick.

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