uvcs_changeset_diff

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the trailing 'Read-only.' adds nothing and the bar for added context is lower. The one genuinely additive disclosure is '.meta pairing warnings', which tells the agent the response will surface Unity meta-file mismatch signals, though it does not say how those warnings appear or whether they affect the item list.

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?

A single sentence that front-loads the action and scope, with the meta-warning caveat and read-only note appended compactly. No filler, no restatement of the 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?

There is no output schema, but the description signals the return content (item-level change list plus .meta pairing warnings) and the schema fully covers input forms, paging limits, and combination constraints. The remaining gap is how warnings are reported and whether items are paginated vs. counted, which a one-line tool of this shape can reasonably omit.

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 every parameter (source, compareTo, maxItems) is documented inline with accepted forms, defaults, caps, and the branch/compareTo incompatibility. The description adds no syntax or semantic detail beyond the schema, so the baseline of 3 applies.

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?

The description names a specific verb ('List') and a specific resource class (items added/changed/moved/deleted in a changeset, label, shelve, or branch) plus the two-sided comparison case, which separates it from content-diff siblings like uvcs_diff_file and uvcs_revision_diff. It never names those siblings explicitly, so an agent must infer the boundary from 'items' vs. file contents.

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?

The scope statement ('in a changeset, label, shelve, or branch, or between two changesets/labels') implies when the tool applies, and the schema carries the exclusion ('Not allowed with a branch source'). However, the description offers no explicit when-to-use/when-not guidance relative to uvcs_pending_changes, uvcs_diff_file, or uvcs_changeset_analytics, leaving routing to inference.

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