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

Annotations already declare destructive=true and idempotent=true, yet the description still adds real behavior: 'Every field is checked before anything is written' signals that invalid fields abort ahead of any mutation, and 'rating (stars, null clears)' documents a non-obvious write semantic that no annotation conveys. It stops short of saying whether partial failures roll back or whether changes are recoverable, but the added value beyond the annotations is genuine.

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 purpose is front-loaded in the first clause and every subsequent clause carries information (target → selector → permitted fields), with no filler. The single dense semicolon-separated block makes it slower to parse than it needs to be, but 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?

For an 8-parameter destructive write with a nested object and no output schema, the definition covers the field vocabulary well and discloses the null-clears and validate-before-write behavior. It leaves out error/atomicity semantics, whether updates can be undone, and why an agent would pick this over the specialized setters, which are meaningful gaps for a mutation tool.

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?

With 88% schema coverage the baseline is 3, and the description goes beyond it by binding each scope parameter to its target (media_type/item_id/title to item, list to list, shelf to shelf, entry_id to shelf_entry) and, more importantly, by enumerating the valid field keys for the free-form 'fields' object per target — the schema only supplies an example. The lists are prefixed 'fields like', so they are indicative rather than exhaustive.

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 and resource ('Change named fields in one call') and then enumerates the five target scopes with the exact fields each accepts, so an agent knows precisely what it operates on. It never distinguishes this generic tool from the many single-field siblings (set_rating, set_progress, set_priority, set_headline), so the boundary is only inferable from the enumeration, not stated.

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?

'Change named fields in one call' implies a batching role and 'describe lists them all' points to a sibling for field discovery, which is useful routing. There is no explicit when-to-use / when-not-to-use guidance and no pointer to the specialized setters, so an agent must infer that this is the multi-field alternative rather than reading it.

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