login_failure_rca

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

Annotations only cover readOnlyHint=true, which the [READ] tag restates. The description adds substantial behavioral context beyond that: findings carry numbers, cause and action; and critically it explains the feedTruncated return flag and that every count becomes a lower bound once max_events is hit. That truncation semantics is exactly the kind of non-obvious behavior an agent needs.

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?

Front-loaded with the [READ] tag and the one-line purpose, then clean Args and Returns sections. Every sentence adds information — the defaults, the config-source note for target, and the truncation caveat — with no filler.

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 return-value burden and does so by describing what each finding contains and the feedTruncated flag's meaning. All three parameters are documented, giving an agent everything needed to call it correctly and interpret the result.

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 0%, so the description must carry all param meaning, and it does: window_minutes (trailing analysis window, default 60), max_events (events to pull, default 500), and target (IdP target name from config; omit for default). Each parameter's purpose and default are stated, fully compensating for the empty schema descriptions.

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 (root-cause analysis) over a specific resource (the failed-auth feed) and enumerates the distinct causes it separates (brute-force spray/targeted, misconfigured client, expired-credential storm, lockout storm). This is unambiguous and distinctive, though it never names the sibling it complements (e.g. login_events for the raw feed), so sibling differentiation is left implicit.

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?

Usage is implied by the framing ('RCA over the failed-auth feed') and by the in-tool guidance to re-run with a higher max_events before concluding a threshold was not reached. However, it never states when to prefer this over alternatives like login_events (raw events), client_misconfig_audit, or user_lockout_status, nor any exclusions.

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