google ads run readonly rpc

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by stating the operation is an enum, arbitrary paths are impossible, and all mutations/uploads are blocked—details beyond the generic read-only annotation and useful for safe invocation.

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?

Two sentences with no fluff: the first leads with the tool's role and scope, the second adds critical constraints. Information is front-loaded and every sentence contributes meaning.

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?

Given the tool's complexity (30 enum operations, nested request body) and rich annotations/output schema, the description covers the key differentiator (services outside GAQL), safety constraints (read-only, enum-limited), and tersely enumerates service categories. It does not need to explain return values because an output schema exists, though it could offer slightly more guidance on when the customerId is needed.

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 100% for all parameters (operation enum, request, customerId), so the schema already documents parameter meaning. The description adds context that the operation is an enum and constrained, but no parameter-specific semantics beyond that, matching the baseline for high schema coverage.

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 clearly identifies the tool as an 'advanced read-only escape hatch' for specific allowlisted Google Ads services 'outside GAQL', listing example service categories. It distinguishes itself from GAQL-based siblings and avoids tautology by naming the resource and scope.

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 clear context: use for services outside GAQL and only for read-only operations. It also implicitly excludes mutations/uploads and arbitrary paths. However, it does not explicitly name an alternative tool for GAQL queries or list when-not-to-use scenarios, leaving some inference to the agent.

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