bi_explain_alert_chain

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

The readOnlyHint annotation already signals a safe read operation, so the bar for extra disclosure is lower. The description adds meaningful behavioral context beyond that: it returns raw facts for simple matches and leaves verdicts to the caller, it cross-references a ±2-minute log window, and it is Admin-gated via the log cmd. It does not contradict the readOnlyHint, and the only minor gap is the absence of explicit failure behavior, but the added context is strong.

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 a single dense paragraph but front-loads the key usage ('Use after bi_list_alerts') and continues with concrete details in order of importance. It earns its length by explaining complex return semantics and an important cost wrinkle. It is longer than minimal, but for a tool with this analytical complexity, the length is justified; a small structural improvement would be bullet points, so not a perfect 5.

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 covers what the tool returns, how to use it, the interpretation policy for simple matches, the time window of the log cross-reference, and the cost/privilege caveat. For a tool this complex, the description is unusually complete: an agent could decide to call it without needing to open the schema, and would know what to do with the response.

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%, so the schema already documents all four parameters. The description adds value by clarifying that 'path' comes specifically from bi_list_alerts and noting the cost trade-off for max_alert_age_h. It connects parameters to real usage, going slightly beyond bare schema entries, though it could have precisely linked 'camera' and 'path' examples to the decoded output.

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 clearly identifies the tool as an alert-chain explainer that decodes what actions fired on a specific alert, with a specific verb ('explain'), a specific resource (alert action chain), and a concrete workflow context ('Use after bi_list_alerts'). It distinguishes itself from siblings by emphasizing decoded filters, comparator verdicts, and log cross-referencing, which none of the sibling names or descriptions suggest.

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 explicitly states when to use it: after bi_list_alerts, and exactly what to pass: the alert's path from that response. It also gives a clear exclusion for simple filter matches (caller decides FIRED vs SUPPRESSED) and a warning about admin-gating and log cost for older alerts. This is actionable guidance with no ambiguity.

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