opn_toggle_alias

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

With no annotations, the description carries full burden. It explains toggle behavior ('flips the current state'), notes no savepoint protection, and describes return format. Lacks details on side effects (e.g., immediate effect vs. apply) and error handling, but adequate for a simple toggle.

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?

Six sentences, each with distinct value: purpose, usage context, behavior, savepoint note, prerequisite, and return value. No redundancy or fluff; front-loaded with core function.

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?

Covers purpose, usage, behavior, prerequisite, and output. Missing explicit error scenarios or confirmation of immediate effect, but sufficiently complete for a single-parameter toggle tool with no output schema provided in structured data.

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 has 0% description coverage for the uuid parameter. Description compensates by explaining how to obtain the UUID ('Use opn_list_firewall_aliases first'). While it doesn't specify format or constraints, the guidance is valuable and clarifies the parameter's purpose.

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 starts with a clear verb+resource: 'Toggle a firewall alias's enabled/disabled state.' It uniquely identifies the tool's function among siblings (e.g., opn_toggle_firewall_rule for rules, other alias tools for add/delete/update).

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 explicit when-to-use: 'temporarily disable an alias without deleting it, or re-enable a previously disabled alias.' Includes a prerequisite: 'Use opn_list_firewall_aliases first to find the UUID.' Does not explicitly mention when not to use, but context implies alternatives for other operations.

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