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

Annotations only cover readOnlyHint/openWorldHint; the description goes far beyond them with error codes (date_range_incomplete, date_range_invalid, invalid_date_preset, foreign_object), the ~2,000-row cap and the warning object returned instead of a list, and the empty-insights dict with result=[] and an info explanation. It also discloses attribution settings, the UNKNOWN ranking meaning, and the conversions vs actions vs custom_conversions caveat.

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?

Purpose, sort order and ID-key framing are front-loaded, and nearly every line carries operative information. The block is dense and long with irregular indentation, and a few points (e.g. ad_id as the direct way to compare ads) are restated, costing some readability without adding 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?

For a 10-parameter analytics tool with a 0%-covered schema, the description covers time-window semantics, filtering, breakdowns, ownership constraints and the shape of degraded responses. An output schema exists, yet the metric list and ranking caveats are still explained, which is more than enough for correct invocation.

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 carries the full burden and does so for all ten parameters: since/until format and inclusive pairing, the complete date_preset value list, the allowed breakdown values, daily semantics, and the ad_id > adset_id > campaign_id precedence with the note that omitting them returns all account ads. This is exactly the compensation the 0% coverage requires.

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 opening line names a specific verb, resource and scope: per-ad Meta performance for the last N days, sorted by spend. It distinguishes itself from account-level aggregation by pointing to meta_campaign_performance totals_only=True, and it flags the IDs as the key for meta_update_ad_status. It never explicitly contrasts itself with meta_adset_performance, so the ad-vs-adset boundary is left implicit.

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?

Explicit routing is given for the main alternatives: campaign totals go to meta_campaign_performance, comparing two individual ads goes through ad_id, and daily=True plus removing today is prescribed when comparing against Google Ads numbers. Precedence rules (since/until > date_preset > days) and the warning that account-wide figures must not be read as campaign figures remove nearly all inference.

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