obs_hotkey_trigger

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

With no annotations provided, the description fully bears the transparency burden. It discloses destructive potential (StopStreaming, ForceStopStreaming), no undo/confirmation, refusal to reject any name, duplicate-name ambiguity, and that success means 'name accepted' not 'effect produced'. It also advises verifying outcomes. This is thorough and honest.

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?

Despite being long, every sentence carries critical information: purpose, examples, danger warnings, alternatives, and return semantics. Structurally it is well-organized into clear paragraphs (function, danger, alternatives, verification). No wasted words; density is high and appropriate for a dangerous 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?

The tool has no output schema and no annotations, yet the description covers all necessary context: how to obtain valid names, destructive consequences, duplicate registration pitfalls, and the need to verify effects. It also provides integration with sibling tools (obs_hotkey_list) and alternative APIs. The description is complete for an agent to use this tool safely.

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 the schema already thoroughly describes both parameters, including case-sensitivity and context discovery caveats. The description adds marginal value beyond schema—it primarily repeats schema details—but it does reinforce the 'exact name from obs_hotkey_list' requirement and the advice to omit contextName unless plugin docs provide one. Baseline 3 is appropriate.

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 clearly states the tool's purpose: 'Fire an OBS hotkey action by name', specifies it's for invoking plugin features without a dedicated request, and provides concrete examples (VerticalCanvasDock*, SwitcherHotkey). It distinguishes from sibling tools like obs_hotkey_list (which lists hotkeys) and obs_hotkey_key (which sends key presses).

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 explicitly says 'DO NOT USE IT AS A SHORTCUT FOR A REAL REQUEST' and lists specific alternatives like SetInputMute, SetSceneItemEnabled, SetCurrentProgramScene. It also instructs to get names from obs_hotkey_list and cautions about dangerous names. This is exemplary guidance for when to use and when not to use the tool.

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