compareTwoPeriods

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful details: the backward-compatible default metrics, result mode options, legacy preset string normalization, and the campaign-specific baseline explanation. However, it does not state whether the operation is read-only, how errors are handled, or what the general response structure looks like for non-campaign levels. Some transparency is present but not comprehensive.

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 a single, well-organized paragraph that front-loads the core purpose. It progressively covers periods, result selection, metrics, and campaign-specific output. Every sentence contributes new information; there is no filler. It could be broken into bullets, but the flow is logical and efficient.

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?

This is a complex tool with nested period objects, multiple modes, and a specific campaign baseline feature. The description thoroughly covers input selection and the campaign output nuance, but it does not describe the general response format (e.g., metric comparisons, percentage changes) for account, adset, or ad levels. With no output schema, this gap could leave an agent uncertain about the return structure. Adequate 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 coverage is 86%, which is high, so the baseline is 3. The description reiterates most parameter information already present in the schema (e.g., preset vs. timeRange, metrics options, resultMode). It adds minor clarifications like 'legacy preset strings are still accepted and normalized' and the backward-compatible default, but these are also implied in the schema defaults. The description adds little beyond what the schema provides.

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 ('Compare'), names the resource ('performance metrics'), and defines scope ('between two explicit periods for an account, campaign, adset, or ad'). This clearly distinguishes it from siblings like getInsights (single-period) and other ad management tools. The tool's unique purpose is unambiguous.

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 states the tool is for comparing two periods, which implies its use case. However, it does not explicitly mention alternatives or when not to use it (e.g., 'use getInsights for single-period analysis'). No exclusions are given, but the context is clear enough for an agent to infer when it applies.

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