set_game_progress

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

With no annotations, the description carries the full burden and does so well: 'Changes only provided fields' documents patch semantics, 'Never DELETE GAME' and the exclusion list disclose a non-destructive safety profile, and 'One UPDATE GAME' signals single-write behavior. It still omits auth/permission requirements and any wait_ms/rate-limit context, so it is strong but not exhaustive.

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 core purpose is front-loaded, and each subsequent clause adds distinct information (field scope, conditional param, patch semantics, clear_fields, non-destructive guarantees). It is dense and telegraphic but not padded; a light restructure would improve flow without adding 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 an 8-param mutation tool with no annotations, the description covers scope, patch behavior, clear semantics, and destructive-safety limits, and an output schema exists so return values need not be described. Remaining gaps are the unexplained required 'slug' and the 'wait_ms' parameter, which leave it slightly short of fully self-contained.

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 0%, so the description must compensate, and it explains most of the 8 params: status, completion, the 0-100 progress bar, progress notes, clear_fields' JSON-list behavior, and the collection_id condition. However, 'slug' (the sole required param) and 'wait_ms' are left entirely unexplained, and the JSON syntax for clear_fields is only gestured at.

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 ('Set') and resource ('per-copy progress') and lists the exact fields affected (status, completion, progress bar, notes). It also carves out its scope by naming what it does NOT touch (edition, DLC, Digital Service, Acquisition Info), which distinguishes it from siblings like set_game_acquisition. An agent can tell it apart from adjacent setters without opening the schema.

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?

Gives one concrete usage condition ('collection_id required when multiple copies exist') and implies it operates on the collection edit form, but never routes the agent to alternatives such as set_game_acquisition or set_game_rating for the excluded fields. Usage context is implied rather than explicit, so it lands at minimum-viable.

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