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

Beyond the annotations, the description discloses the two most decision-relevant traits: the plan is immutable and separately confirmable (so state is persisted now, but live entities are untouched), and the scope explicitly excludes advertising entities. This meaningfully supplements destructiveHint=false by explaining why the write is non-destructive. It does not cover failure/validation behavior or batch limits.

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 tight sentences: what it does, what it mutates, and what it explicitly does not touch. The scope boundary is front-loaded and nothing is repeated from the title or schema.

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 prepare-step tool with an output schema (so return values need no explanation) and heavily documented nested parameters, the definition covers purpose, persistence semantics, and scope boundaries. The notable gap is the absence of a named confirmation/apply follow-up and any mention of how a prepared plan is retrieved or how long it lives.

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?

The description adds no parameter-level meaning beyond the schema, and the top-level "parameters" wrapper carries no description (0% reported coverage). However, the nested properties are richly self-documenting — portfolioId canonicality, name preservation on omission, NO_CAP/DATE_RANGE/MONTHLY_RECURRING merge semantics — so the schema itself does the work and a baseline 3 is appropriate.

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 names a specific verb chain ("prepares and persists") and a precise resource scope ("portfolio names or budgets"), and explicitly bounds it with "Does not change advertising entities", which separates it from the many prepare_*_changes tools for campaigns, ads, and targeting. It stops short of naming prepare_portfolio_creation or apply_portfolio_changes as the adjacent alternatives, so the create-vs-change distinction must be inferred from the schema's required portfolioId.

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" implies a two-step prepare-then-confirm flow, which is real usage guidance, but the description never names confirm_workflow_plan or apply_portfolio_changes as the next step, nor states when to prefer this over prepare_portfolio_creation. Usage is implied by the annotation/workflow rather than stated.

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