google_ads_search_fields

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

With no annotations, the description carries the transparency burden and does disclose that the tool is 'Read-only.' It also describes the live nature of the catalog and its role before raw GAQL queries. However, it does not mention behavior such as pagination, how results are returned, or interaction between the raw query parameter and structured filters, despite the presence of pageToken, pageSize, and query parameters.

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?

The description is two sentences with no filler: a front-loaded action sentence followed by one clarifying scope sentence. Every phrase adds information about what the catalog contains and when to use the tool.

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 8 parameters, no annotations, and no output schema, the description provides useful high-level context and a clear workflow placement. However, it does not describe the return value shape, pagination behavior, or the relationship between the query parameter and the structural filters, leaving meaningful gaps an agent would need to infer from the schema alone.

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 only 25% across 8 parameters, so the description needed to compensate, but it does not explain most parameters. It mentions categories like 'resource, attribute, segment, metric' and 'selectable-with compatibility,' which hint at category and selectable, but sortable, filterable, pageToken, and the interaction between query and structured filters remain unexplained in the description.

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 specific verb and resource: 'Search Google's live GoogleAdsField catalog.' It further enumerates the exact kinds of entities discovered (resource, attribute, segment, metric, enum value, selectable-with compatibility) and explicitly ties it to use before a raw GAQL query. This clearly distinguishes it from siblings like google_ads_run_gaql.

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?

'Read-only and useful before a raw GAQL query' gives a clear usage context and signals that this is a discovery step rather than a query execution tool. It does not explicitly name alternatives or exclusions, but the contrast with raw GAQL query execution is clear from the sibling set and the wording.

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