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

Adds real context beyond the annotations: the plan is immutable and separately confirmable, it writes a plan rather than mutating ad entities, negative targeting accepts no bid actions, and archiving is irreversible. Those are non-obvious traits that annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) do not convey. It stops short of describing the confirmation lifecycle or what the persisted plan record contains.

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?

Four short sentences, each carrying distinct information, with the core identity (immutable confirmable plan) front-loaded and the constraints (no negative bids, irreversible archive, no entity mutation) following. No filler or restatement of the title.

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?

Given an output schema exists and annotations cover the safety profile, the description supplies the essential decision information: what the tool does, that it does not mutate entities, and the irreversibility constraint. Slightly incomplete because it does not hint at the follow-up confirmation/apply step that a prepare tool necessarily requires.

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%, so the baseline would be 3, but the description still adds branch-level meaning: the positive branch handles bids/states while the negative branch is state-only with an irreversible ARCHIVED terminal value. It does not map the oneOf branch structure to targetType values (KEYWORD/TARGET vs NEGATIVE_KEYWORD/NEGATIVE_TARGET) as explicitly as the schema does.

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 (prepares) plus the exact resource (an immutable, separately confirmable Amazon Ads targeting plan) and enumerates both supported branches: positive keyword/ASIN bid or state changes and negative re-enable/archive. The phrase 'persists an internal plan without changing advertising entities' functionally separates it from apply_targeting_changes, and the positive-vs-negative scope separates it from prepare_targeting_creation.

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?

'Separately confirmable' and 'Persists an internal plan without changing advertising entities' imply the prepare-then-confirm/apply workflow, which is useful implied guidance. However, it never names the alternative calls (apply_targeting_changes, confirm_workflow_plan) or states an explicit when-to-use/when-not condition, leaving the agent to infer the routing.

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