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

Goes well past the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) by disclosing that the plan is immutable and persisted, that ARCHIVED preserves ranking history and the resulting state is NOT_TRACKED rather than an ARCHIVED state, that removing the last keyword drops the target from its tracking list, and that ACTIVE only resumes system-paused collection after package and quota checks. It also disclaims Amazon Catalog access, which matters for a non-open-world tool.

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?

Front-loaded with the core action and scope, then bounded by a compact set of 'does not' exclusions that each remove a real ambiguity. It is dense and mostly waste-free, though the repeated negation clauses read as somewhat clipped and could be merged into one boundary sentence.

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, full annotation coverage, and a fully described nested schema, the description supplies exactly the missing layer: the prepare/review/confirm/execute lifecycle, the prerequisite capability and quota check, and the state semantics of the two allowed changes. Nothing needed to select or invoke the tool correctly is absent.

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 single top-level parameter is a deeply documented nested object, so the baseline is 3. The description adds semantics the schema does not: the operation only mutates already-existing tracking entries and works against the account's existing tracking, which tells the agent items must reference tracked keywords rather than new ones.

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 precise verb+resource ('Prepares and persists an immutable keyword-rank tracking change plan') and immediately bounds the operation to status updates ACTIVE/ARCHIVED on existing tracking. Explicitly negates the neighboring capabilities ('Does not create tracking', 'Does not apply tracking changes'), so an agent can separate it from prepare_keyword_rank_tracking_creation and apply_keyword_rank_tracking_changes without consulting schemas.

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 flow is spelled out: prepare -> explicit customer review -> approval -> confirm -> matching execution tool, plus the precondition to query capabilities and quotas first. Exclusions route the agent away from creation and application. Slight deduction because the alternative tools are described by negation ('matching execution tool') rather than named outright.

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