audit_seo_issues

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 does convey that the tool is a detection/analysis operation (not a mutation) and enumerates covered issue types. However, it does not state whether it runs a new scan, reuses a previous session, or has side effects/rate limits, leaving some behavioral ambiguity.

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 a single front-loaded sentence that immediately states the tool's purpose and lists concrete error types. The enumeration is long but contains no filler words; it could be slightly more structured by category, but overall it is efficient.

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?

The tool is moderately complex with 3 optional parameters and no output schema. The description thoroughly defines what issues are detected, but it does not describe the return format, how filters map to the listed issue categories, or the dependence on an existing scan session. Given the absence of an output schema, more context about expected results would improve completeness.

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 100%, with clear descriptions for sessionId, filterCategory, and filterSeverity. The tool description adds no extra parameter-level meaning beyond those fields, so the baseline score of 3 is appropriate.

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 uses a specific verb ('Phát hiện' - detect) and a concrete resource: comprehensive on-page and technical SEO errors, with a detailed list including 404, 410, redirects, title issues, thin content, etc. This clearly differentiates it from siblings like crawl_website or export_crawl_report, which perform crawling/reporting rather than auditing.

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 provides no guidance on when to use this tool versus alternatives, nor any prerequisite such as running crawl_website first. The sessionId parameter hints at prior scans, but the description itself never states that a crawl must exist or that this tool should be used specifically for issue detection after a crawl.

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