reset_vcenter_alarm

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses the crucial gotcha: vSphere has no per-alarm clear, so this tool clears ALL triggered alarms matching the entity type and status. It also discloses the return value's shape (a dict with a 'scope' field). This is significant behavioral context that the annotations do not provide, making the 'blast radius' explicit and reducing the risk of unintended side effects.

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 front-loaded with a clear [WRITE] tag and a one-sentence purpose. Every subsequent sentence adds essential usage or behavioral information: when to use, the alternative, the parameter source, the critical gotcha, and the return value. There is no fluff or redundancy; each line 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?

Despite lacking an output schema, the description explains what the tool returns ('a dict whose 'scope' field states exactly what was cleared'). It covers the core workflow (fetch parameters from list_vcenter_alarms), the safety caveat (blast radius), and the conceptual difference from acknowledge_vcenter_alarm. For a tool with modest complexity and rich annotations, this description is sufficient for an agent to call it correctly.

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 input schema already provides 100% parameter description coverage, including where alarm_name comes from (list_vcenter_alarms output) and what entity_name means. The description's instruction to 'Get entity_name and alarm_name from list_vcenter_alarms first' restates what the schema already says for alarm_name, adding no new semantic meaning to the parameters. It is useful as a usage ordering cue, but not as parameter semantics, so the baseline of 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 states a specific verb and resource ('Clear triggered vCenter alarms back to normal state') and differentiates from the sibling tool by explicitly naming acknowledge_vcenter_alarm as the alternative for merely marking an alarm seen. This makes the tool's purpose unambiguous and clearly distinguishes it from closely related operations.

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 provides explicit when-to-use guidance ('Use this after resolving the underlying issue'), identifies the alternative (acknowledge_vcenter_alarm), and instructs the agent to obtain parameters from list_vcenter_alarms first. It also flags a critical prerequisite by advising to confirm the blast radius with the user. This is exactly the practical routing information an agent needs.

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