uvcs_checkin_prepare

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

Despite annotations already declaring readOnly/idempotent/non-destructive, the description adds substantial non-obvious behavior: the token is short-lived, private files are never selected (except a new parent folder surfaced under dependencies), and Unity .meta partners are auto-included for every selected asset. These inclusion/exclusion rules directly affect what the agent shows the user before confirming.

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: purpose and output first, then scoping rules, then the review-before-confirm instruction. Every clause carries actionable information; nothing restates the tool name or wasted boilerplate.

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 correctly covers the important return facts (token, change list, dependencies) and the .meta/private-file rules that shape that return. It does not say what the returned change entries actually contain or how to handle an expired token, which are minor residual gaps.

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%, so both parameters are already documented and the baseline is 3. The description goes beyond it by spelling out the recursive 'at or below those paths' scope and the default all-pending behavior when paths is omitted, plus the implicit .meta expansion the caller cannot see from the schema.

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+resource ('Prepare a checkin') plus its distinctive output ('short-lived confirmation token'), which separates it from uvcs_checkin_confirm and from the read-only uvcs_pending_changes sibling. An agent can identify the two-step prepare/confirm pattern without opening either 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?

Gives clear selection rules for the two modes (no paths = all tracked pending changes; with paths = that subtree) and an explicit workflow instruction: review the returned changes with the user before confirming. It stops short of naming uvcs_checkin_confirm as the next call and passing the token, so it is clear context rather than full when/when-not routing.

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