get_alarms

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

Annotations provide readOnlyHint=true, and the description reinforces it by saying 'Read-only operation.' Beyond that, it adds useful context: the tool lists 'unacknowledged/active alarms with severity and message' and scopes the query to a site and optional device. It doesn't describe pagination or rate limits, but for a simple read-only tool the added context is meaningfully helpful.

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 well-structured and front-loaded: core purpose first, then read-only clarification, then routing to alternatives, then args. It is slightly redundant because 'Read-only operation' duplicates the readOnlyHint annotation and the Args section duplicates the schema, but the overall length is reasonable and every substantive sentence 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?

There is no output schema, so the description carries the burden of explaining return content; it does so by saying the tool lists 'unacknowledged/active alarms with severity and message.' It also covers when to use it and what to do afterward. Minor gaps remain: it doesn't specify the full alarm object structure, ordering, or empty-result behavior, but these are acceptable for a simple, low-complexity read-only tool.

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 description coverage is 100%, and the schema already fully describes both 'site' and 'device' parameters. The description's Args section simply repeats the schema text verbatim ('Site to query. Defaults to "default"' and 'Optional console/device name...'), adding no new meaning. Baseline 3 is appropriate because the schema does the heavy lifting.

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 opens with 'Return the currently active alarms (faults and warnings) for a site,' which names a specific verb, resource, and scope. It distinguishes itself from siblings by explicitly contrasting with get_recent_events for non-alarm activity. This leaves no ambiguity about what the tool does.

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 states when to use the tool ('so you can see what needs attention') and explicitly names alternatives with conditions: use get_recent_events for a broad event feed, archive_all_alarms once handled, or analyze_network_issues for consolidated interpretation. This is model usage guidance.

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