Content refresh candidates (decaying pages)

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, so the safety profile is covered. The description adds the selection logic: period-over-period decline, staleness via sitemap lastmod, and lost queries. It doesn't mention output structure or behavior when sitemapUrl is missing, but that is a minor gap given the strong annotation coverage.

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?

Four short sentences, each earning its place: plain definition, detection mechanism, usage vs sibling, and concrete rewrite actions. There is no filler or repetition despite the first and second sentences being closely related.

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 read-only analysis tool with no output schema, the description clarifies what kind of results to expect (declining stale pages plus the queries they lost), the core input semantics, and the decision context. It omits explicit return fields and details on default date ranges, but an agent can reasonably infer the output and invoke the tool correctly.

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 coverage is only 33% (siteUrl, staleDays, and sitemapUrl have descriptions). The description gives context that maps to the period parameters ('between two periods') and to minPreviousClicks ('clicks or impressions dropped'), but top, the date-string params, and minPreviousClicks are not explicitly explained. It partially compensates for low coverage but doesn't fully document the remaining parameters.

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 starts with a plain-language definition ('Pages that used to perform and no longer do') and then states a specific verb and resource: 'Finds pages whose clicks or impressions dropped between two periods and that have not been updated recently (sitemap lastmod), with the queries they lost the most on.' It also differentiates itself from gsc_opportunities, so an agent can tell them apart without opening the schema.

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?

It explicitly names the alternative and the decision rule: 'Use it for deciding what to rewrite; gsc_opportunities is for what to push over the line.' This gives clear when-to-use versus when-to-use-other guidance. It also adds actionable next steps for candidates, making the intended workflow concrete.

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