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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: what is returned (official name, description, where the code is logged, an investigation page when available) and that the tool is free with no API key required.

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?

It is a single dense paragraph that front-loads purpose before formats and return values, with no filler sentences. The long parenthetical code examples cost some readability, but each one demonstrates a distinct accepted input shape rather than repeating itself.

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?

With one required parameter, no output schema, and full schema coverage, this description carries everything an agent needs: what it does, the input formats it accepts, and what comes back. There is no output schema to explain, and the description still summarizes the return payload.

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 coverage is 100%, so the baseline is 3. The description still adds meaningful semantics beyond the schema's one-liner by spelling out the accepted formats: prefixed or bare AADSTS numbers, hex with or without 0x, decimal and negative-decimal forms, official constant names, whole pasted messages, and free-text keywords.

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 leads with a specific verb and resource: 'Explains Microsoft authentication error codes from Microsoft's official tables.' It then enumerates the exact code families covered (Entra ID AADSTS, NTSTATUS, Kerberos, official names), which makes it unmistakable versus siblings like search_reference or explain_log_record.

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?

It gives concrete input strategies: 'Paste a whole error message or event to find every code in it, or give words to search names and descriptions.' That is clear when-to-use guidance. It stops short of naming alternatives or exclusions (e.g., when to prefer explain_log_record or search_reference), so it doesn't reach a 5.

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