Audit content quality

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces 'Read-only' in plain terms. It adds value by specifying that the tool 'names the issues and the IDs' — a concrete output behavior beyond what annotations state — and by listing the exact problem categories it checks. This goes beyond the annotations without contradicting them.

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 moderately long but well-structured: it front-loads the core purpose, lists concrete checks, and concludes with the read-only note and fix guidance. Every sentence contributes — the issue list is dense but informative, and the pointer to mutation tools is a helpful addition. Could be slightly tightened, but no waste exists.

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 read-only audit tool, the description adequately conveys what it does and what it returns (issue names and IDs). It lacks an output schema, but the description's statement that it 'names the issues and the IDs' suffices for an agent to understand the result. Parameter defaults and limits are covered by the schema, so nothing critical is missing. Slight omission: it does not mention whether output is a list or how pagination works, but given the 'sweep' metaphor and limit parameter, this is likely reasonable.

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 input schema covers 100% of parameters with descriptive comments (e.g., 'Content type to audit', 'How many items to examine'), so the schema already documents semantics. The description does not add parameter-specific guidance, such as explaining the interplay between status and limit or the meaning of thin_content_words. Since schema coverage is complete, a score of 3 is appropriate — the description adds no extra value here.

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 ('sweep') and resource ('a content type'), then enumerates the exact checks performed (SEO titles, H1s, thin content, etc.), making the scope unmistakable. It also names the follow-up tools (bulk_update_content, update_content) and explicitly states it is read-only, distinguishing it from the mutation siblings in the list. Clear, specific, and differentiates adequately.

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 implicitly defines the usage scenario: use it to identify content issues, then apply fixes via bulk_update_content or update_content. It does not explicitly state when not to use it (e.g., for media, which has a separate audit_media tool), but the context is clear and the differentiation from mutation tools is explicit. This is sufficient guidance for an agent deciding to invoke it.

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