run_gaql

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

With no annotations provided, the description carries the behavioral disclosure burden. It does well by describing the tool as a read, noting that results are returned in chosen formats, and that queries are 'passed through faithfully,' implying no internal filtering or transformation. It stops short of mentioning pagination, error behavior, or rate limits, but the core behaviors are transparent.

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 wasted words. The core action, scope, output formats, and pass-through nature are all front-loaded, and the 'workhorse read' phrasing is efficient and informative.

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 tool with 5 parameters, no annotations, no output schema, and zero schema description coverage, the description provides the essential query and format semantics but leaves pagination, customer scoping, and explicit sibling routing unaddressed. It is usable but not fully complete.

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 must compensate. It explains the query parameter as a raw GAQL query and clarifies that format accepts json, table, or csv, but it says nothing about page_size, page_token, or customer_id. These parameters remain semantically vague aside from their names, leaving a meaningful gap for an agent selecting values.

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 a specific verb ('Execute'), the resource ('raw GAQL query'), and the deliverable (rows in json, table, or csv). It also frames itself as the 'workhorse read' for any resource or field, which clearly distinguishes it from the specialized sibling read tools.

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?

The description clearly implies when to use this tool: when you need a raw GAQL query across any resource or field, as opposed to the pre-built specialized tools. It does not explicitly name alternatives or state when not to use it, but the 'any resource, any field' framing provides solid contextual guidance.

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