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

readOnlyHint=true is consistent with a pure metadata/setup helper, so the annotations carry the safety profile. Beyond that, the description discloses what each request returns (exact request body, required parameters, notes) and the mandatory ordering before a real query, which the annotations do not say.

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 a one-line purpose then numbered steps and labeled optionals, so an agent can scan it quickly. It is slightly longer than strictly necessary, but the redundant-call warning earns its line.

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?

An output schema exists, so return shapes need not be spelled out, and the sequencing required for correct use is fully covered. A five-parameter tool with a required enum and an undocumented platform parameter is the only remaining hole.

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 0%, so the description must compensate, and it largely does: it explains each meaningful request enum value and pairs actions/brand_id/workspace_id with the requests that consume them, including example action strings. The gap is platform, which appears in no example and is left entirely undocumented.

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 states concretely that this is a planning/metadata tool: it retrieves workspace_id, brand_id, source metadata and available_actions, and returns exact request bodies via actions_details. That implicitly separates it from the execute_action sibling, which performs the actual query. The only friction is the mismatch between the tool name query_contexts and the PageSpeed-'query planning' framing, which a careful reader resolves but which could mislead at a glance.

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 gives an explicit ordered workflow: Step 1 accounts, Step 2 actions_details which is marked 'REQUIRED before querying', plus clearly labeled optional calls. It even flags that available_actions is redundant with the accounts response, so the agent knows when not to make that call.

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