snap_spend_pacing

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

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description's "(read-only)" adds nothing. What it does add is genuine behavioral context: results are limited to ACTIVE ad squads, statuses are a fixed enumerated set, month mode adds projection and required daily spend, and day boundaries follow SNAP_REPORT_UTC_OFFSET. It says nothing about performance, pagination, or behavior when no active squads exist.

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?

Front-loaded with the guiding question, then cleanly partitioned into "Today:" and "This month:" clauses. Dense and largely waste-free, though the telegraphic style ("the most it could spend") is slightly less precise than a short explicit label would be.

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 does the heavy lifting by sketching both output modes, the status enum, and the timezone convention, which is enough for an agent to call it correctly with the single optional parameter. Remaining gaps (currency handling, empty-account behavior, whether month mode works without spend history) are modest.

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 100% and describes monthly_budget as the planned monthly spend in account currency. The description goes beyond that by explaining the effect of supplying it: the response gains an over/under verdict and the daily spend needed to land on budget, which tells an agent why and when to pass it rather than just what it is.

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?

A clear question-shaped statement of purpose ("Is spend on track?") followed by concrete scope: today's per-ACTIVE-ad-squad spend vs daily budget, and month-to-date/projection figures. The enumerated status vocabulary (AHEAD, BEHIND, NOT_SPENDING, etc.) makes the tool's output identity unmistakable and clearly distinct from a generic reporting or budget-advice sibling.

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 makes the use case clear (checking pacing against budget, read-only) and implicitly scopes the invocation by noting that month-level over/under analysis only appears when monthly_budget is supplied. It stops short of naming when to prefer a sibling such as a budget-advice tool or when this tool is not appropriate.

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