obs_raw

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal the raw, direct-by-name nature of the request invocation, but it omits warnings about potentially destructive or state-changing actions, authentication requirements, error handling, or the fact that raw payloads may be unvalidated. The 'ESCAPE HATCH' label hints at advanced use but does not explicitly disclose risks.

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 description is three short, purposeful sentences: a label, a definition, and a pointer to the protocol reference. It is front-loaded with the 'ESCAPE HATCH' tag and contains no filler or redundant information.

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 generic raw pass-through tool with two parameters, no output schema, and no annotations, the description covers the essential context: what it is, what it does, its scope relative to sibling tools, and where to find request names. It does not elaborate on response formats or validation, but for an escape hatch that intentionally mirrors arbitrary protocol requests, the description is reasonably complete.

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%: requestType includes examples ('GetHotkeyList', 'TriggerHotkeyByName') and requestData is described as 'Payload for that request.' The tool description adds the notion of a 'raw payload' and 'by name,' but it does not provide additional per-parameter semantics or request-specific structure beyond what the schema already offers, matching the baseline when schema coverage is high.

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 defines the tool as an 'ESCAPE HATCH' that can 'call any obs-websocket v5 request directly by name with a raw payload.' It explicitly states the scope (any request) and distinguishes itself from siblings by covering 'everything the wrapped tools do not, including plugin-provided vendor requests.'

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 implicitly provides usage guidance by stating it covers 'everything the wrapped tools do not,' indicating the user should use the wrapped tools for typical operations and turn to obs_raw for anything else. It also directs users to 'the obs-websocket protocol reference for request names,' but does not explicitly enumerate when-not-to-use cases or list alternative tools.

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