unifi_console_describe_operation

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds genuinely new context by confirming no console call is made and warning that spec descriptions carry quirks and secret-bearing fields. It stops short of describing failure behavior for an unknown operation_id.

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?

Two short paragraphs, front-loaded with the action and immediately followed by the no-side-effect caveat. Enumerating the returned JSON keys is slightly redundant given an output schema exists, but the quirk warning earns its place.

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?

With an output schema present the description needn't restate return values, and annotations cover safety; what it must supply is the reason to call this before calling an operation, which it does. Only the input parameter's origin and error behavior are unaddressed.

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 description's field list ('name, in, required, description') refers to the returned parameters, not the input. It says nothing about the single input operation_id, whose meaning only comes from the schema's own description ('operationId from unifi_console_list_operations, e.g. listFirewallPoliciesWithHits'). With reported 0% schema coverage the description should have compensated for the input parameter and does not.

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: it shows one operation's parameters, request-body schema, access level and description from the spec. The line 'Does not call the console' cleanly separates it from the sibling unifi_console_call_operation, so an agent can pick the right tool without opening schemas.

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?

Gives a clear when: inspect an operation before invoking it, because spec descriptions 'often record quirks such as Read-only despite POST'. It implies the pairing with unifi_console_call_operation but never names it or states an explicit when-not, so it falls short of a full 5.

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