save_scene

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

With no annotations provided, the description carries the full disclosure burden. It usefully reveals that this is a local sidecar file write rather than a live Spotify API mutation, and specifies exactly which fields get persisted. However, it does not disclose overwrite semantics on name collision, whether the device is validated at save time, or whether any Spotify-side effect occurs.

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?

A single 25-word sentence that front-loads the verb and core concept, then packs the field composition and the concrete file path into parentheses without waste. Every phrase earns its place and the most decision-relevant details (what is saved, where it goes) appear first.

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 7-parameter write tool with no annotations and no output schema, the description covers the core invoke-time facts: required name is implied by 'named', the optional fields are enumerated, and the persistence target is given. What's missing is overwrite behavior, the relationship to apply_scene/list_scenes/delete_scene, and any sense of the return value. The schema covers paramter semantics well, but the description alone doesn't fully prepare an agent for edge cases like re-saving an existing name.

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 7 parameters thoroughly with types, ranges, enums, and examples. The description adds marginal value by grouping the fields ('device + volume + shuffle/repeat + optional context') and signposting context as optional, which matches the schema's required-only-name rule. This is the expected baseline-3 scenario where the schema does the heavy lifting.

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 states a specific verb ('Save'), a concrete resource ('named playback scene'), enumerates its contents (device + volume + shuffle/repeat + optional context), and names the storage location (~/.spotify-mcp/scenes.json). This is clear and makes the scene concept tangible, though it does not explicitly distinguish itself from the closely named sibling save_playback_state.

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 gives no guidance on when to use this tool versus alternatives such as save_playback_state, apply_scene, or list_scenes. There is no mention of prerequisites, when a scene is appropriate, or which sibling performs the inverse operation. The usage context is only implied by the word 'save'.

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