Audit On-Page

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

Annotations already declare readOnlyHint=true, and the description adds that the tool 'Returns a list of technical issues found', informing the agent about output shape. It also discloses the full technical scope of the audit, so the agent knows which aspects are inspected. This complements the read-only annotation without contradicting it.

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 front-loads the core purpose in the first sentence, followed by a clear enumeration of checks and exclusions. The long list of checks is warranted because it defines the audit scope. No filler or redundancy is present.

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 single-parameter tool with high schema coverage and a read-only annotation, this description is largely sufficient: it defines scope, exclusions, and return type. It does not mention how the audit handles JavaScript-rendered content or edge cases like non-HTML responses, but these are minor given the simple input and read-only safety. Overall it positions the tool well among the many sibling check tools.

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 single parameter url is already fully documented in the schema with 'The URL to audit for on-page technical issues', so schema description coverage is 100%. The description adds no additional parameter-level detail, but the schema fully covers the parameter. Baseline 3 is appropriate given the high schema coverage.

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 'Technical on-page HTML audit', a specific verb-resource pair, then enumerates exactly which elements are checked (title, meta description, canonical, robots, lang, headings, images alt, OG, Twitter Card, structured data). It explicitly lists what it does NOT analyze (keywords, rankings, backlinks, traffic), which distinguishes it from analytics-focused tools. This makes the tool's purpose unmistakable among 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 clearly implies when to use this tool: when a technical on-page HTML audit covering the listed elements is needed. It explicitly excludes keyword/ranking/backlink/traffic analysis and directs users to Semrush for those. However, it does not name sibling tools or specify when to choose this over check_structured_data or check_accessibility for narrower checks.

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