Get ads analytics

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

Beyond the readOnly, idempotent, and non-destructive annotations, the description adds substantial behavioral detail: synchronous execution, the 250-entity limit, default attribution windows, reporting timezone behavior, conversion_report_time options, and the caveat that HOUR granularity no longer includes conversion metrics. It also explains metric naming conventions such as _1 paid versus _2 earned.

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 front-loaded with purpose, scope, and key constraints, and the line breaks make the dense parameter guidance readable. It is necessarily detailed for a 14-parameter tool with no schema descriptions, though the long common-column list could be slightly leaner given the explicit pointer to pinterest_ads_list_metrics.

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 complex analytics tool with no output schema and no parameter descriptions, the definition supplies enough context to call it correctly: scope, required ids, date format, granularity, attribution defaults, timezone and conversion settings, column examples, and known limitations. A few optional parameters and response-shape details remain unaddressed, keeping it short of 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?

With 0% schema description coverage, the description compensates well by explaining level values, date format, granularity values, targeting_types examples and exclusions, attribution window defaults, reporting timezone choices, and column semantics. It still leaves some optional parameters such as ad_account_id and the explicit attribution window/type parameters less directly explained.

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 uses a specific verb and resource, 'Get ads metrics', and immediately states the scope: synchronous metrics for an ad account or up to 250 campaigns, ad groups, ads, or product groups. It also distinguishes the operation from report-style workflows by emphasizing 'right away (synchronous)' and 'Changes nothing'.

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 usage context by specifying synchronous retrieval, supported levels, id requirements, date formats, granularity choices, and some exclusions such as targeting_types not being for product groups. It does not explicitly compare itself with asynchronous siblings like create_report or run_report, so the when-to-use-versus-alternatives guidance is clear but not complete.

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