acronis_fetch_alerts_grouped_per_customer

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered and the description owes no contradiction. It adds no behavioral context whatsoever though: nothing about how alerts are grouped or ordered in the response, how many customers can be passed at once, or how dismissed alerts behave by default despite show_deleted flags existing.

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?

A single short sentence with no wasted words, but its brevity comes at the cost of meaning rather than from efficiency. It is front-loaded with the verb but never gets to the grouping behavior that the name promises.

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?

The tool takes a nested query object with roughly eighteen filter fields, has no output schema, and returns customer-grouped results, yet the description explains neither the grouping shape nor defaults. For a tool of this complexity, one sentence that echoes the name is not enough for an agent to call it confidently.

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 nested query object documents all filters (id, type, severity, created_at operators, show_deleted, etc.), so the schema carries the semantics. The description contributes nothing about the required customer_id array being the grouping key, so baseline 3 applies.

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 the verb and resource ("Fetches alerts") and the scoping ("of the specified customers"), but omits the defining trait in the tool name: that results are grouped per customer. Siblings like acronis_fetch_all_alerts, acronis_fetch_alerts_grouped_by_scope, and acronis_fetch_alert_counts_per_customer are not distinguished, so the agent cannot tell from the text what makes this fetch different.

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?

No when-to-use guidance and no named alternative. The agent is not told to prefer this over acronis_fetch_all_alerts when a per-customer breakdown is needed, nor when the other grouped-scope tool is more appropriate. Only implicit usage can be inferred from the tool name.

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