hreflang_audit

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

No annotations are provided, so the description carries the burden and largely meets it: it discloses that no authentication is required, that the operation is a fetch/validate (non-destructive), that validation logic comes from a cited source, and that the tool intentionally does not follow alternates. The verdict vocabulary (valid | issues_found | no_hreflang | fetch_error) foreshadows failure modes, though the fetch_error conditions themselves are not described.

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?

Front-loaded with the core purpose, then a scannable list of checks, a scope caveat, provenance, and the verdict set. Efficient overall; the source-attribution line is defensible for trust but is not load-bearing for an agent deciding whether to call the tool.

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 presence of an output schema means return values need not be explained, and the description sensibly adds only the verdict vocabulary. Combined with the disclosed checks, scope limitation, and no-auth note, an agent has nearly everything needed; the only gap is parameter format guidance, which is not covered anywhere.

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 0% for the single 'url' parameter, so the description must compensate. "Fetch a URL" implies the parameter is the page under audit, but it says nothing about expected format (absolute vs relative, scheme handling), which matters given the tool flags mixed HTTP/HTTPS. Adequate but thin for a low-coverage schema.

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?

Opens with a precise verb+resource statement ("Fetch a URL and validate its hreflang implementation") and then enumerates the exact checks performed. The enumeration makes it plainly distinct from neighbouring audit tools such as page_technical_audit, heading_audit, and internal_links_audit, which share the 'audit' family name but cover different surfaces.

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 scope boundary is explicit: "Single-page audit: does not follow each alternate URL to verify bidirectional return tags," which tells the agent where this tool stops. It stops short of naming an alternative tool or the condition under which a deeper crawl-level hreflang check should be used instead, so it is clear context without explicit routing.

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