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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the safety profile is covered; the description usefully adds what content is captured. It does not say whether a second call supersedes or appends to an existing snapshot, how long the snapshot lives, or that state_key lets you target a particular working-state entry — the kind of context annotations cannot convey.

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?

Two sentences, zero waste, with the capture contents front-loaded ahead of the trigger condition. Nothing is repeated from the name or 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?

Annotation coverage plus an output schema means the description need not restate safety or return shape; all parameters are optional with defaults, so the tool is callable with no arguments.

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 100% with per-parameter descriptions and defaults for all 9 optional parameters, so the schema does the heavy lifting. The description's mention of TODOs, pending decisions and recent events implicitly maps to reminder_limit, decision_limit and timeline_limit, but says nothing about scope, bucket, session_id, ttl_seconds or metadata_json beyond the schema text.

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 (save) and enumerates the resource contents it captures: active state, recent events, TODOs, pending decisions. This tells an agent it is a composite snapshot rather than a single-key write like update_state or remember, but it never names those siblings or restore_restart_snapshot to sharpen the boundary.

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?

'Relevant before handoff or when context may be lost' gives a concrete trigger condition for use. It stops short of when-not guidance or naming restore_restart_snapshot as the counterpart that reads the snapshot back, so the agent must infer the save/restore pairing from names alone.

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