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

Annotations already flag destructive, idempotent, and non-readonly behavior, and the description adds concrete destructive consequences: replaces all library grants, omitted libraries lose access, and an empty selection removes all access. It also discloses the authenticated-administrator prerequisite and that no email/upload occurs.

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?

Four tight sentences, front-loaded with the action and replacement semantics. No filler; each sentence carries necessary guidance about exactness, freshness, and exclusions.

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 destructive, idempotent mutation with four required params, no output schema, and safety annotations, the description covers the critical behavioral consequences, prerequisites, and common mistaken flows. Return values need not be explained because no output schema exists, and the idempotencyKey schema handles replay behavior.

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 50%; projectId and idempotencyKey are described in the schema, while selectionId and selectionRevision are not. The description partially compensates by requiring the exact reviewed selection and a revision that must be refreshed if the snapshot changes, though it does not explicitly map these constraints to the parameter names or clarify formats.

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 ('Apply') and resource ('dossier library access') with the exact scope of the selection and revision. It distinguishes itself from prepare/inspect/retry siblings by requiring the reviewed administrator choice and declaring replacement semantics.

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?

Gives clear context for when to apply: after the authenticated administrator has reviewed and chosen an exact selection/revision. It adds exclusions ('Never apply an inferred selection'; 'changed snapshot requires a fresh selection') and clarifies that no email code or upload is involved, but it does not name the alternative sibling tool for preparing or retrying.

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