get_mobile_issues

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

Annotations already declare read-only/idempotent/open-world, so the description wisely adds context the annotations cannot: the data source (URL Inspection), the 2023 deprecation of the Mobile Usability report, and the resulting likelihood of empty verdicts. That is exactly the kind of caveat an agent needs before trusting a null usability result.

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-loads the purpose, immediately follows with the critical deprecation caveat, then lists arguments one per line without redundancy. Every sentence earns its place and the structure matches how an agent reads a tool definition.

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?

Rich annotations and an output schema mean the description need not explain return shapes or safety; it focuses instead on the deprecation caveat and full parameter semantics. Nothing material for calling this tool correctly is missing.

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%, so the description carries the full burden and succeeds: it explains site_url's default (GSC_SITE_URL), urls (one per line, defaults to top pages), source's allowed values ('top_pages' or 'sitemap') and prerequisite (when urls is empty), limit's default, and issue_filter's substring-matching behavior.

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?

Names a specific verb and resource ('Mobile signals per URL from URL Inspection') and lists the exact fields returned (crawled-as, fetch state, mobile-usability verdict/issues). It is clearly mobile-specific, but never names the URL-inspection siblings (inspect_url_enhanced, batch_url_inspection, check_url_status) it must be chosen over.

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?

Provides a clear exclusion: the Mobile Usability report was retired in Dec 2023, so use Lighthouse/PageSpeed for layout checks instead. That is a strong when-not-to-use signal, but it stops short of saying when this tool should be preferred over the other URL-inspection tools.

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