diagnose_dot1x

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only, rule-based,' and explains what the tool will name and deliver, including fixes on both switch and ISE. It does not discuss failure behavior on unparseable input or limits on log size, but the core behavioral traits are disclosed.

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 compact and information-dense, front-loading the core purpose before enumerating inputs, root causes, and outputs. Every clause adds value; the final 'Read-only, rule-based' tag is a useful behavioral note without surplus wording.

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?

For a diagnostic tool with free-text log inputs, the description covers inputs, scope, root causes, and fix guidance well. An output schema exists, so return-value documentation is not the description's job. Minor gaps remain around handling malformed or empty input and when to prefer lookup_ise_failure_code for a single failure code, but the description is largely complete for correct invocation.

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 compensate. It maps the three inputs conceptually: RADIUS/ISE log, switchport config, supplicant log, and says 'any of' may be pasted. However, it does not give format hints, size expectations, or more explicit per-parameter guidance, leaving some ambiguity for an agent preparing the call.

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 a specific verb and resource: 'Diagnose a port that will not authenticate,' then details the exact inputs (RADIUS/ISE log, switchport config, supplicant log) and outputs (root cause, fix). This clearly distinguishes it from broader diagnostic or parsing siblings like check_config_compliance or extract_device_facts.

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 gives explicit context for when to use the tool: when a port will not authenticate. It also tells the agent what to paste. It does not explicitly name alternative tools or exclusion conditions, but the usage context is clear and actionable despite that.

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