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

The destructiveHint annotation already flags this as a mutating operation, so the bar is lower. The description usefully clarifies that it is a partial update rather than a full overwrite, but says nothing about reversibility, permission/plan requirements, or what happens to fields left unset beyond that one clause.

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?

Two short sentences, front-loaded with the action and field scope, followed by a compact endpoint reference. Nothing is padded, though the 'Rewardful: PUT /v1/campaigns/:id' line is informational rather than decision-relevant.

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 10 schema-documented parameters, a destructive annotation and no output schema, the description covers the essential action and partial-update behavior. Side effects on downstream artifacts (affiliate links, coupons) and the response shape are unspecified, but the structured fields carry most of the remaining burden.

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 every parameter (including the conditional 'required when reward_type is X' rules) is documented in the schema itself. The description's field list merely restates a subset of those names, adding no format, unit, or constraint detail 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?

Clear specific verb+resource ('Change a campaign's...') with an explicit enumeration of the mutable fields (name, URL, visibility, reward rule, payout minimum, coupon). The verb alone separates it from rewardful_create_campaign, rewardful_get_campaign and rewardful_list_campaigns, though no sibling is named outright.

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?

'Only the fields you pass change' communicates partial-update semantics, which tells the agent it need not supply all ten parameters. However there is no guidance on when to prefer this over create_campaign or update_affiliate, and no stated prerequisites (e.g. the Growth/Enterprise requirement that only appears in the schema).

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