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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations by specifying that findings are categorized by severity and that each finding names the onboarding step and entity involved.

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 front-loaded with the core purpose and then provides structured severity definitions. Every sentence earns its place: the severity taxonomy, the finding content note, and the usage trigger are all directly useful for correct invocation.

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 simple tool with one optional parameter and no output schema, the description is complete. It explains what the tool does, what findings contain, and when to call it, while annotations cover the read-only, idempotent, non-destructive behavior.

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?

The schema already documents the single optional 'level' parameter and its default, so baseline credit applies. The description adds semantic weight by defining what BLOCKER, WARNING, and INFO actually mean and what types of issues fall into each category.

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 states a specific action and resource: 'Check the manufacturer's setup for problems' and report them by severity. It defines BLOCKER, WARNING, and INFO with concrete conditions, making it clear this is a validation/linting tool rather than a describe or query tool. It also ties the purpose to setup completeness and quoting failures, which distinguishes it from siblings.

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 an explicit trigger: 'Call this first when asked whether the setup is complete or why quoting fails.' This clearly tells an agent when to use the tool, but it does not explicitly mention when not to use it or name any alternative sibling tools.

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