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

Adds substantial behavior beyond the annotations: all items apply as one change reverted by a single undo (atomicity), stale items are returned in `stale` and skipped unless forced, and it explicitly notes no AI and no credits are consumed. This goes well past the destructiveHint=true annotation.

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?

Dense but front-loaded: purpose first, then per-item overrides, then stale/force semantics, then cost. Every sentence carries distinct information with no filler.

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 3-parameter mutation tool with an output schema, the description covers the essentials an agent needs: atomic undo, stale handling, override mechanics, and the no-AI/no-credit cost. Return values are deferred to the output schema, which is appropriate.

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 coverage is 67%, and the description adds real meaning: `fields` applies only some proposed keys while `values` overrides with your own, and both the top-level and per-item force flags govern stale items. The individual value keys and item id format remain schema-only, but the field/value distinction is clarified.

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?

Specific verb (Apply) plus resource (suggestions) and the id provenance (a run's saved_suggestions or suggestions_list), which cleanly separates it from suggestions_reject. An agent can tell what it does without opening the schema.

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?

It states where the required ids come from and explains force/stale conditions, giving clear context for when this tool applies. It does not explicitly name suggestions_reject as the alternative nor spell out when-not to use, so it stops short of full routing guidance.

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