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

Annotations already establish readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real behavioral context beyond that: a not-found error when no analysis exists within max_age_days, the deliberate refusal to refresh because it would consume LLM credit, and https:// normalization of the URL.

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 purpose, then return payload, then error/credit behavior, then args — a logical order with no filler. It is longer than strictly necessary, but each block carries distinct information.

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 usefully enumerates the returned payload (diagnosis, citation verdict, checks, schema, queries, facts, entities, bot visibility) and covers the error case and credit rationale. Nothing an agent needs to call this 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 coverage is only 25%, but the description compensates by documenting three of four parameters: brand_id (required), url (required, with normalization and the fallback lookup workflow), and max_age_days (1-365, default 30). The undocumented user_intent is already described in the schema, so coverage is effectively complete.

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?

States a specific verb and resource ('Get the cached deep analysis for a single URL') and pins the scope with 'cached' and 'single URL'. This cleanly separates it from list_page_analyses (which lists many) and run_diagnosis (which produces a fresh analysis), so an agent can choose 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?

Gives explicit routing: if the URL is unknown, call list_page_analyses with the same brand_id and use a returned URL rather than guessing, and it clarifies that fresh analyses come from the dashboard rather than this call. The only gap is that it never names the run_diagnosis sibling as the programmatic path to a fresh analysis.

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