reconnect_obs

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

No annotations are provided, so the description carries the full burden. 'Try to reconnect' suggests a potentially mutating/connection-changing operation but doesn't disclose what happens on success/failure, whether it interrupts ongoing operations, whether it's idempotent, or if it requires any special state. The description adds minimal behavioral context beyond what the name alone implies. It also doesn't clarify if reconnection could disrupt active sessions or lose data.

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?

Single concise sentence with no filler. The phrase 'using current configuration' earns its place by explaining why no parameters are needed. Could arguably benefit from a brief note on when to invoke, but for its length it's efficient and front-loaded with the action.

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 zero-parameter, no-output-schema tool, the description is minimally adequate but lacks depth. It doesn't explain what the reconnect attempt does in practical terms (e.g., does it block until success/failure?), what the return value indicates, or how an agent should respond to success vs. failure. Given the sibling get_obs_health exists, it would be valuable to note the relationship (e.g., check health before/after reconnect).

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?

The tool has 0 parameters with 100% schema coverage (an empty object schema), so there's nothing for the description to compensate for. The phrase 'using current configuration' clarifies that no parameters are needed because the tool relies on stored/persisted configuration, which adds meaning beyond the empty schema. Baseline 4 for a zero-parameter tool 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 states a specific verb+resource ('Try to reconnect to OBS WebSocket') with a clear qualifier ('using current configuration'). It clearly distinguishes from siblings like get_obs_health (which checks status) versus this which actively reconnects. Slightly ambiguous whether this establishes a new connection or re-establishes a dropped one, but the purpose is clear.

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 implies usage context (when connection is down, attempt to reconnect), but provides no explicit guidance on when NOT to use it or alternatives. It doesn't state whether this is a recovery action after failures, a startup action, or how it relates to get_obs_health as a diagnostic precursor. There's no explicit event-when-to-use guidance beyond the implied 'try to reconnect' context.

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