Save Super Source Look

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

Annotations already declare a non-destructive, idempotent, non-read-only write, and the description adds genuinely new context: the file location (~/.atem-mcp/looks/), JSON format, and persistence across server restarts. The notable gap is overwrite semantics — with idempotentHint=true, an agent needs to know whether reusing an existing name silently replaces a saved look, and the description never says so.

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 core action, then persistence/location facts, then args and examples. The Args section largely mirrors the schema, but each entry carries extra detail (filename rules, naming examples) and the whole block is short with no filler.

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 no-output-schema write tool the description covers what state is captured, where it lands, and that it survives restarts. It is short of complete only on the overwrite/collision behavior and on what the agent gets back on success, both of which matter for confirming the save went through.

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 100%, so baseline is 3, but the description goes beyond it by spelling out filename character constraints (alphanumeric, dashes, underscores) and giving realistic name/description examples that convey naming conventions and intended granularity. ssrcId is only restated from the schema, so the value added is uneven but real.

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: snapshot the current Super Source state (box positions/sources, art, border) and persist it as a named look. That is clearly distinct from the sibling persistence tools (atem_list_looks, atem_load_look, atem_delete_look) and from the atem_set_supersource_* mutators, so an agent can select it 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?

Provides concrete invocation examples ("Save this look as podcast4") and implies the workflow via the phrase "can be recalled later," which points at atem_load_look. It does not explicitly name the alternatives or state the when-not case (e.g., when to prefer configuring boxes live via atem_set_supersource_box instead), so it is clear context rather than full routing guidance.

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