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

Annotations only declare it is a non-read-only, non-destructive, non-idempotent write to a closed domain; the description adds real behavioral context beyond that: no send, budget, price or page change, approval requests can be recorded without execution, paid-revenue requests require Owner approval, and set_weekly_goal is now a no-op returning goal_period_required. It does not cover idempotency (annotations say false) or what a successful pause/resume returns, which keeps it from a 5.

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?

Effectively a single dense paragraph with the primary action front-loaded and every subsequent clause carrying a distinct constraint (scope limits, deprecation notice, approval rule, permission). It borders on overstuffed, mixing scope, deprecation and auth in one block, but little is redundant.

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 non-idempotent mutation with six parameters, no output schema and zero schema description coverage, the description covers side-effect boundaries and permissions well but leaves the meaning of goalKey/goalValue and approvalKind implicit and never states what a successful call returns. Adequate to invoke safely, not 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 description coverage is 0%, so the description must carry meaning, and it partially does: it clarifies 'one demand channel', that goal requests must not invent a period, and that indefinite baselines differ from bounded business goals. However channel, goalKey, goalValue, approvalKind and note semantics are left to the self-describing enum values, and no parameter is named or explained directly.

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 opens with a specific verb and scope: 'Pause or resume preparation of one demand channel in the next daily run using the same setting as the UI.' The 'preparation' qualifier sharply distinguishes it from provider-side campaign controls, though the later clauses about set_weekly_goal and request_approval make the overall purpose broader than the opening sentence suggests.

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?

It states explicit exclusions ('does not pause or start provider campaigns, existing publications or separate reminder/sending workflows, and does not enable a policy-disabled channel') and names the correct alternative for goal-setting ('directs the caller to prepare_business_goal with explicit startsOn/deadlineOn'), plus the prerequisite 'Requires marketing:prepare.' This is exactly the when/when-not/alternative guidance an agent needs.

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