image_audit

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds little beyond the schema: it does not disclose that pages are fetched live, how long a 10-page audit takes, or what happens when check_files triggers up to 30 header requests per page. The 30-per-page fetch detail lives in the schema, not the description.

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?

A single dense sentence that front-loads the purpose and then lists checks in a compact comma-separated form. No filler or repetition, though the run-on enumeration makes it slightly harder to scan than a short lead sentence plus bullets.

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?

With no output schema, the description should clarify what an agent gets back (per-page findings? issue counts? severity?) and should cover the two undocumented tuning parameters. It defines the audit scope well but leaves output shape and threshold semantics unaddressed for a tool that takes four parameters.

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?

Only 'urls' and 'check_files' carry schema descriptions (50% coverage), leaving large_kb and max_images undocumented in both places. The description mentions 'file size' and 'broken images' but never explains that large_kb is a size threshold (default 300 KB) or that max_images caps images analyzed per page, so it does not compensate for the coverage gap.

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 verb and resource ('Image SEO audit of pages') and enumerates the concrete checks performed: alt text, file names, width/height, lazy loading, formats, file size, broken images, og:image, structured data. This is clearly distinguishable from siblings like pagespeed_audit or inspect_url. It stops short of explicitly naming the nearest sibling, so it does not reach a 5.

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 only implied by the enumerated checks – an agent can infer it is for image-level SEO review of a set of pages. There is no statement of when to prefer this over pagespeed_audit or inspect_url, and no mention of prerequisites or cost implications of auditing multiple URLs.

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