scrobble_tracks

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

Annotations already convey that this is a non-read-only, non-destructive, idempotent, open-world operation. The description adds value beyond that: it discloses the authentication requirement and two concrete server-side behaviors (rejection of far-future timestamps and the half-track/four-minute play rule). It doesn't mention partial-batch failure behavior or rate limits, but for a write tool with annotations covering the safety profile, the added context is meaningful.

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 tight and front-loaded: an opening purpose line, a one-line auth prerequisite, then a structured Args block that documents the single parameter. Every sentence earns its place — there is no boilerplate, no schema restating, and no filler. The structure mirrors the single-parameter shape of the tool.

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?

Given the tool's real complexity (one array parameter with seven sub-fields) and the nearly empty input schema, the description carries a heavy burden and meets it well. It covers invocation limits, required elements, defaults, optional elements, and server validation rules, and an output schema exists so return values needn't be documented. Minor gaps remain — behavior on partially invalid batches and rate limits — but nothing an agent needs to construct a correct call is missing.

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% — the tracks parameter is an array of objects with additionalProperties: true, providing virtually no structure. The description fully compensates: it documents the 50-play limit, the required per-item fields (artist, track), the default for timestamp (now), and the six optional fields (album, albumArtist, mbid, duration, trackNumber). This is exactly the semantic load a description must carry when the schema is empty, and it does so completely.

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?

"Scrobble one or more plays" uses the domain-specific verb 'scrobble' (submit play data), which is unambiguous and distinct from every sibling, including the closest alternative update_now_playing (which reports a currently playing track without finalizing it). The resource (plays) and action are both specified crisply in the opening line.

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 provides clear contextual guidance: it states the authentication prerequisite and gives an explicit eligibility rule ("Scrobble only what was really played", with the half-track/four-minute threshold and server rejection of future timestamps). It does not explicitly name alternatives such as update_now_playing or state when NOT to use this tool, but the usage context is otherwise unambiguous.

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