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

Annotations only cover the safety profile (not read-only, not idempotent, not destructive). The description goes well beyond that: it discloses a throughput constraint (at most a share of free sandbox capacity per call), partial-execution semantics with a `deferred` bucket to be retried, and an explicit `skipped` bucket with reasons. That is exactly the kind of capacity/rate-limit and failure-mode context annotations cannot express.

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, front-loaded with what the tool does before moving to the deferred/skipped semantics. No filler; each sentence carries information about execution behavior. Slightly dense but well ordered.

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?

With no output schema, the description helpfully explains the shape of the result (deferred vs skipped with reasons), which is what an agent needs to drive the retry loop. It stops short of quantifying the capacity share or saying how to detect that started runs have finished, so an agent must infer the polling step.

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 all three parameters (including both enums) are documented in the schema, so the baseline of 3 applies. The description adds no syntax or format detail beyond the schema — it mentions processes generically but never explains `kind` or `transformation_aggressiveness`.

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 and resource ('Start snapshot generation for many v2 clarity processes') and the scope ('current team'). The word 'many'/bulk distinguishes it in spirit from the single-process sibling generateClarityProcessSnapshot, but the description never names that alternative, so differentiation is inferred rather than explicit.

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 gives real operational guidance on the retry loop ('the rest come back in `deferred` and should be sent again once some of the started runs finish'), which is genuinely useful. However it never states when to use this bulk tool versus generateClarityProcessSnapshot for a single process, or any precondition about sandbox capacity being available.

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