Plan a Meta budget change

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'nothing is written'. Beyond that it discloses non-obvious behavior: policy caps (max daily budget in the client's currency, +20% per 24h), an out-of-band human approval requirement, and that rollback restores the previous budget. That is real context an agent cannot get from the annotations.

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 'PLAN (nothing is written)' framing is front-loaded and the whole definition is two dense sentences with no filler. It is slightly overloaded by the inline CLI reference, but every clause carries operative information.

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 no-write planning tool with no output schema and full schema coverage, the description covers the safety profile, financial constraints, approval flow, and reversibility. The only real omission is what the plan produces and how to consume it (plan_get/plan_list/meta_apply), which is a minor gap given those siblings exist.

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 description coverage is 100% and all four parameters are documented in the schema itself (enum for level, minor-unit explanation for daily_budget_minor, client_id defaulting behavior). The description adds no syntax or format detail beyond what the schema already carries, so the baseline of 3 applies.

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?

States a specific verb and resource ('change the daily budget of a Meta campaign or ad set') and immediately qualifies it with 'PLAN (nothing is written)'. That qualifier is exactly the axis that separates this tool from meta_apply and from the gads/openai_ads budget-change siblings, so an agent can route without opening schemas.

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?

Clearly establishes the planning context, the approval gate ('applied only after a human approval out of band'), and the rollback path, which tells the agent when this is the right stage to call. It stops short of naming the follow-up siblings (meta_apply, plan_get) explicitly, so it is strong context rather than full routing guidance.

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