Save the show file

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 unusually well: it discloses the destructive overwrite condition, the dialog-open refusal, name truncation by UTF-8 byte length with pre-send refusal, which confirmation prompt it answers, and the exact verification criteria (file timestamp from this save plus console naming it current). It also states the result payload (size, time) and a bridge version requirement.

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?

Front-loaded with the primary action and default, then layered constraints, verification, and prerequisites in a logical order with no filler. Some sentences are densely packed (the SaveShow/confirmation sentence requires a second read), which costs a point 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 a four-parameter mutation tool with no annotations and no output schema, the description supplies everything an agent needs: naming rules, overwrite risk, dialog-state prerequisite, confirmation handling, verification logic, and what the result contains. No material gap remains for correct invocation.

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 75%, and the description compensates for the gap: 'exclusive' has no schema description but the prose states it is required, and 'name' gains the 32-character limit, byte-counting rule for non-ASCII, and pre-validation behavior. Only timeout_ms is left to the schema, and the description adds no failure/timeout semantics of its own.

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 and resource ('Save the show') plus the two scoping modes (current name default vs. a new name that becomes current). It is clearly distinguishable from the file-listing sibling gma3_show_files, which it names as a separate step.

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 concrete preconditions and routing: use gma3_show_files first to inspect files, requires exclusive: true, and it will refuse while a dialog is open or when colliding with another show's file unless overwrite: true. It stops short of an explicit 'do not use this when…' statement or naming a rename-only alternative, so it is strong but not a full when/when-not map.

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