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

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds meaningful behavior beyond that: data comes from the daily pull and can be up to a day old, accounts without campaigns return empty lists, and never-pulled campaigns have latest: null. It also states the paid_media section must be in scope. These details materially help the agent interpret results correctly.

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 the core resource and metrics, then covers edge cases, scope requirements, and data freshness in a compact sequence. Every sentence carries useful information and none is redundant with the annotations or schema. It is appropriately sized for the tool's complexity.

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?

With no output schema, the description carries the full burden of explaining the return shape, and it does so thoroughly: accounts, campaigns, metric names, rolling window, pull date, and null behavior are all specified. It also covers the scope prerequisite and data staleness. An agent has everything needed to call and interpret this tool correctly.

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?

The schema covers the single optional platform parameter fully with an enum and a description ('Limit to one platform'), so the description does not need to add much. It mentions the platform examples Reddit Ads and LinkedIn Ads, which map to the enum values, but provides no extra semantic detail beyond the schema. Baseline 3 is appropriate given 100% schema description 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 names the resource ('connected paid-media accounts') and specifies exactly what is returned: campaigns with latest impressions, clicks, spend, and pull date over a 30-day window. It also handles edge cases like accounts with no campaigns and campaigns never pulled, making the tool's purpose unmistakable. The current-snapshot framing distinguishes it from the sibling get_paid_media_history.

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 gives clear usage context by framing the data as the most recent pulled metrics and noting the paid_media section scope requirement. It does not explicitly name an alternative such as get_paid_media_history or state when not to use this tool, but the current-snapshot language implies the distinction. This is clear context without an explicit exclusion.

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