ghl_affiliate_update_suspension

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

Goes well beyond the annotations by disclosing the finance side effects (pending/denied payouts, commissions and transactions are cancelled or restored), the required Sub-Account token, and the write OAuth scope. The description implies meaningful financial mutation while annotations set destructiveHint=false, but since the description makes clear the cancellation is reversible via reinstatement, the annotation is defensible and this is not scored as a contradiction.

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 key action and its consequences are front-loaded in the first two sentences, followed by endpoint and auth metadata. The endpoint/version/source line is boilerplate but compact; nothing is padded.

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 mutation tool with no output schema, the description covers side effects, reversibility, auth token requirements and the OAuth scope, which is what an agent needs to decide and invoke correctly. Missing only return shape and idempotency confirmation, which annotations partly supply.

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 the description's explanation of suspension semantics largely duplicates the isSuspended property description in the schema. Baseline 3 is appropriate when the schema already documents every parameter.

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 pair of actions (suspend/reinstate) on a precise resource (an affiliate on a campaign), and the campaign-scoping distinguishes it from sibling tools like ghl_affiliate_update_status or ghl_affiliate_update_customer_state which operate on different scopes. An agent can tell what it does without opening the schema.

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?

Describes the concrete effects of each mode (suspending cancels payouts; reinstating returns them to pending), which gives a clear picture of when each mode applies. It does not however explicitly exclude or name the alternative affiliate-status tools, so the agent must infer that this is campaign-scoped rather than a general status change.

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