nucleo-quality-check

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, yet the description still adds real behavior: acknowledged issues 'do not block', and content without postId is validated inside the layouts of postType. That explains a non-obvious evaluation-context dependency the annotations cannot convey. It stops short of saying what 'block' means operationally or whether the check mutates anything, hence not a 5.

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?

Three sentences, front-loaded with what the tool produces and then the input variants; there is no filler. The middle sentence is dense and nests several clauses, but every sentence carries information an agent needs.

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 five-parameter tool with a nested acknowledge object and no output schema, the description covers inputs well but says nothing about the shape of the report, issue severity, or what the return value looks like. The rule exempting return-value explanation applies only when an output schema exists, and here none does, leaving a meaningful gap.

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?

With 60% schema coverage, the description compensates where the schema is silent: acknowledge has no schema description at all, and the text supplies its effect ('Issues acknowledged with acknowledge do not block'), while postType's default and layout semantics are restated as behavior rather than type. The postId/url/document alternatives are also framed functionally, adding meaning beyond parameter names.

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 names a specific artifact (a quality report covering SEO, accessibility and performance) and enumerates the two input modes: a saved document identified by postId or url, or an unsaved document object. It is clear what the tool returns, but it never mentions the sibling nucleo-quality-scan, so an agent cannot tell from this text how it differs from that similarly named tool.

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 subject matter ('Quality report ... of a saved document'), and the postType sentence implies it applies to not-yet-saved content, but there is no explicit when-to-use / when-not-to-use statement and no named alternative. The reference to doc-create describes parallel layout behavior, not an alternative tool to pick instead, so routing guidance is left to inference.

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