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

Annotations only declare readOnlyHint=false, openWorldHint=false and destructiveHint=false; the description meaningfully adds that no TikTok mutation occurs, that the operation is bounded to the tenant's own entities, and that the returned approval_ref is single-use. That is real context beyond the annotations, though 'bounded' is never defined and no expiry/one-shot failure behavior is described.

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?

Three short sentences, front-loaded with the core action and the returned artifact, with no padding. The phrasing 'common-wire alias' is jargon that costs more than it communicates, but overall the density is good.

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 an 8-parameter, 7-required prepare tool with no output schema, the description covers the return artifact and the non-mutating nature, which is the most important part. It is nevertheless incomplete: the meaning of run_id, rule_id_and_version, idempotency_key and entity_refs is absent from both description and schema, and validation-failure behavior is unstated.

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 only 13% (essentially just target_value's 'Advertiser-currency units'), so the description must carry the load for run_id, idempotency_key, rule_id_and_version, connection_context and entity_refs — and it explains none of them. It only restates the unit semantics already in the schema and the adset/ad_group alias already visible in the enum, leaving seven required-or-near-required parameters uninterpretable.

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 (validate), resource (bounded tenant-owned TikTok ad-group bid change), unit semantics (advertiser-currency), and outputs a named artifact (single-use approval_ref). It also pre-empts a likely confusion by noting that 'adset' is only the wire alias, which cleanly separates it from the confirm-side siblings.

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 statement 'This tool does not mutate TikTok' implicitly positions it as the pre-step to a mutating confirm call, and the sibling list contains bid_confirm, so the prepare/confirm workflow is inferable. However, it never explicitly says when to use this versus bid_confirm, or whether an approval_ref must be consumed by a specific sibling before it expires.

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