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

Annotations declare the safety profile (not read-only, not idempotent, not destructive), and the description adds real substance beyond them: recursive add semantics, the .meta companion file behavior for Unity assets, and a mandatory human-approval gate before execution. It stops short of covering failure modes or whether a consumed token can be reused, so not a 5.

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 short sentences, front-loaded with what the operation does before the procedural constraint. 'Requires prepare/confirm' and 'Confirms and executes a prepared operation' partially restate each other, a small redundancy but not enough to obscure the message.

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 two-parameter confirm tool with no output schema, this covers scope, the Unity side effect, the prepare dependency, and the approval gate — everything needed to invoke it safely. What the call returns on success is left unstated, a minor gap given no output schema exists to compensate.

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 the schema already explains that token comes from uvcs_add_prepare and that confirmPhrase must be exactly 'confirm uvcs add'. The description only broadly gestures at 'the prepared payload' and the prepared operation, adding no semantics beyond the schema. Baseline 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?

States a specific verb and resource ('Add a path to Plastic SCM / UVCS version control recursively') plus the Unity-specific side effect of adding the matching .meta file. The second sentence makes clear this is the confirm half of a prepare/confirm pair, which distinguishes it from uvcs_add_prepare 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?

Explicit timing constraint: 'Call only after the user has reviewed the prepared payload and explicitly approved this exact operation,' plus 'Requires prepare/confirm.' The precondition is unambiguous, though it never names uvcs_add_prepare as the required predecessor tool — that link is only inferable from the token parameter's schema description.

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

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

Annotations declare readOnlyHint/idempotentHint/non-destructive, which fits a prepare step that only mints a token. The description adds genuinely useful behavior beyond that: recursion into the path, automatic addition of matching .meta files for Unity assets, and the short-lived token return contract. It stops short of stating token lifetime or what the confirm call expects.

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 short sentences, front-loaded with the action and scope, then side effects, then the prepare/confirm contract. No filler.

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 one-parameter, non-destructive prepare tool with no output schema, this covers action, scope, side effects, and the token workflow. Only minor gaps remain around token expiry and already-versioned paths.

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?

The single parameter is fully documented in the schema (100% coverage), so the baseline is 3. The description adds real meaning by implying itemPath may point at a directory that is traversed recursively and may trigger sibling .meta additions.

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 concrete verb and resource ('Add a path to Plastic SCM / UVCS version control') plus the recursive scope and the Unity .meta side effect. It differentiates itself from the confirm sibling by naming the prepare/confirm pairing, though it never names uvcs_add_confirm outright.

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?

'Requires prepare/confirm' tells the agent this is the first half of a two-step flow and that the returned token feeds a later call. There is no explicit when-not guidance (e.g. what to do if the path is already versioned or already pending add).

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that by noting the read-only nature again and, more importantly, that binary files cannot be annotated, which prevents a class of invalid calls.

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 short, front-loaded sentences with no waste. The core operation is stated first, followed by the binary-file caveat and the read-only status.

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 four-parameter read-only operation with no output schema and fully documented parameters, the description covers the essential purpose and key limitation. It could more explicitly route the agent away from sibling history/diff tools, but nothing critical for correct invocation is missing.

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%, so the definitions for filePath, maxLines, revision, and startLine already carry parameter meaning. The description does not add syntax or format guidance beyond the schema, such as how revision strings interact with blame, so it meets the baseline rather than exceeding it.

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 states a specific verb and resource: it shows who last changed each line of a text file and in which changeset, clearly identifying this as a blame operation. The parenthetical '(blame)' reinforces the exact concept, making it distinguishable from sibling tools like uvcs_file_history or uvcs_diff_file.

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 description gives an important usage constraint: binary files cannot be annotated. However, it does not explicitly say when to use this tool versus siblings such as uvcs_file_history or uvcs_diff_file, leaving the agent to infer that this is for per-line authorship rather than general history or diffs.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds meaningful behavioral context beyond that: the required human-review/approval gate before execution. It does not detail exact side effects of branch creation, but with annotations present this is a solid addition.

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 short sentences, front-loaded with the purpose and then the prerequisite. Slight redundancy between 'Requires prepare/confirm' and 'Confirms and executes a prepared operation,' but overall low waste.

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?

A mutation/confirm tool with no output schema and full schema coverage. The description supplies the missing behavioral gate (prepare + explicit user approval) that an agent needs to invoke it correctly, leaving only minor detail about side effects unstated.

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% and both parameters (token, confirmPhrase) are documented in the schema, so the baseline is 3. The description adds no parameter-specific detail about token lifecycle or the exact confirmPhrase beyond what the schema already states.

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 (create branch from a changeset or label) and clarifies it is the confirm step that 'executes a prepared operation.' Sibling differentiation from uvcs_branch_create_prepare is implied via 'Requires prepare/confirm' rather than named outright, but the schema token reference makes the pairing clear.

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?

Explicit precondition: 'Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.' This is a clear gate that tells the agent when this tool is eligible, though it does not explicitly name the prepare tool to call first.

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

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

Adds context beyond the annotations: the operation is split into prepare and confirm, and this call returns a short-lived confirmation token, explaining both the non-mutating nature of this step and the expiry window the agent must respect. It does not state what happens on confirm, what invalidates the token, or permission requirements, keeping it below a 5.

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 short sentences, front-loaded with the action, then the workflow constraint, then the return value. No filler and nothing an agent must read past to understand the call.

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 return value (a short-lived token) and the follow-up step, which is the essential missing piece for a prepare/confirm pair. Gaps remain around source-spec precedence and failure behavior, but those are secondary for a simple four-parameter tool.

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% and all four parameters carry their own descriptions with examples, so the schema is doing the heavy lifting. The description's phrase "from a changeset or label" loosely maps to fromChangeset/fromLabel but adds no syntax, precedence, or exclusivity rules beyond 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 and resource ("Create a Plastic SCM / UVCS branch") plus the two supported sources (changeset or label), which an agent can distinguish from sibling listing tools like uvcs_branch_list. It stops short of naming uvcs_branch_create_confirm explicitly, relying on the phrase "Requires prepare/confirm" to imply the pairing.

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?

"Requires prepare/confirm" tells the agent this is phase one of a two-step flow, which is real usage guidance. However, it gives no exclusions or prerequisites (branch must not already exist, permissions needed) and never says whether fromLabel and fromChangeset are mutually exclusive or which to prefer when both are available.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond restating the name — no info on what 'branch information' contains, whether it requires a workspace, or what happens when no branch is checked out.

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 short sentence with no waste and the resource front-loaded. It is efficient but borders on under-specification rather than genuine conciseness.

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 zero-parameter, no-output-schema read tool the description is adequate to call it, but it never indicates what fields 'branch information' returns (name, changeset, parent) or any precondition, leaving the agent to discover the payload empirically.

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?

The tool takes zero parameters, so there is nothing for the description to document; baseline is 4. No parameter semantics are needed or missing.

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 ('Return current branch information'), so the agent knows this is a read of branch metadata. However, it never distinguishes itself from sibling tools like uvcs_branch_list or uvcs_workspace_status, leaving the agent to infer which one surfaces the current branch.

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?

There is no guidance on when to call this versus uvcs_branch_list, uvcs_workspace_status, or uvcs_branch_safety_report. The description gives no context or exclusions, only the bare statement of what it returns.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety needs no restatement. The description adds value beyond them by disclosing result ordering and the per-branch fields returned, though it omits pagination/truncation behavior (the 50-default cap lives only in the schema).

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 tight sentences; the core action and result shape come first, and the read-only note closes it out. No filler or redundancy.

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 appropriately enumerates the returned fields, and the fully documented parameters cover the input side. The only gap is noting that results are capped/paginated, which matters for a list tool with a 500 max.

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%, with each of the five parameters documented including the YYYY-MM-DD format and the 1-500 range. The description adds no parameter meaning of its own, 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 and resource (list branches) and adds concrete detail about ordering ('newest first') and returned fields (owner, parent, head changeset, comment). It does not explicitly differentiate itself from the nearby sibling uvcs_branch_info, so it stops short of a 5.

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?

Nothing in the text says when to call this rather than uvcs_branch_info or the branch_create tools; the only usage signal is 'Read-only.' The filtering options (owner, since, parent, nameLike) exist only in the schema, so the agent must infer that this is the discovery/filter tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the description's 'Read-only helper' framing is largely redundant. It adds the useful behavioral cue that this is a pre-flight aggregate check, but says nothing about output shape, freshness, or cost beyond what the schema and annotations provide.

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 front-loaded sentence with zero filler: it names the nature of the tool, the data it returns, and the trigger condition in order of importance.

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 zero-required-parameter read-only reporting tool with strong annotations, the description conveys enough: it enumerates what is reported and when to invoke it. No output schema exists, and the description only sketches the return contents, so it is complete enough but not exhaustive.

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% and both parameters are fully documented (default branch, 1-50 changeset range). The description reinforces which data is inspected but adds no format or semantics beyond the schema, so baseline 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?

States a specific verb ('reports') with three concrete resources (current branch, pending changes, recent changesets) and frames it as a read-only safety helper. It distinguishes the aggregate nature implicitly, though it never names the closely related siblings (uvcs_branch_info, uvcs_pending_changes) that cover the same data individually.

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 a clear usage context: 'before risky branch, merge, or cleanup work' - an agent knows when to reach for it. It stops short of naming alternatives or exclusions, so it is clear context but not full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so "Read-only" adds nothing. No context is supplied about result shape, whether results are aggregated/summarized, ordering, or what happens when no filter is given (all changesets?), which is exactly the kind of behavior an agent needs here.

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 short sentences, front-loaded with the filter scope, with no padding. The only waste is the redundant "Read-only" clause already covered by annotations.

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, so the description must convey what "analyze" returns, and it does not — an agent cannot tell whether it receives counts/aggregates or changeset records, nor how pagination via maxResults is reflected. For a 6-parameter analytics tool this is a material gap.

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%, so every parameter is already documented, and the description merely echoes four of the six filters (owner, date range, branch, comment) while omitting maxResults. Baseline 3 applies since the schema carries the semantic load.

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?

It names a verb ("Analyze") and a resource ("changesets") plus the filterable dimensions, so the general domain is clear. But "analyze" is vague — it does not say whether the result is an aggregate/statistics report or a filtered list of changesets, and nothing distinguishes it from data-returning siblings like uvcs_changeset_diff or uvcs_file_history.

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 description gives no guidance on when to pick this tool over the many other changeset/history/diff siblings, and no prerequisites or exclusions. "Read-only" is a safety trait, not a usage rule.

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

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.

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the mutating, non-repeatable nature is known from structured data. The description adds the human-approval gate and the fact that all tracked pending changes may be swept in, but says nothing about token lifetime, whether the checkin is reversible, or what a failed confirmation returns.

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, no filler, with the operation described first and the critical safety gate immediately after. Nothing here is redundant with the title or schema.

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 two-parameter confirmation tool with full schema coverage and no output schema, the description covers the operation, its scope, and the approval prerequisite. The main residual gap is error/expiry behavior for the token, which matters slightly for a non-idempotent mutation.

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 both parameters (token, confirmPhrase) are documented in the schema, including the exact phrase string. The description adds no parameter-level meaning beyond that, 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?

Specific verb + resource ("Run a prepared checkin") with the scope spelled out as all tracked pending changes or the selected paths, and it ties itself to the uvcs_checkin_prepare output. It is distinguishable from the prepare sibling by the word "prepared" and by actually executing, though it never names the sibling explicitly.

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?

"Call only after the user has reviewed the prepared payload and explicitly approved this exact operation" is an explicit precondition and a clear gating rule, which is unusually good. It stops short of stating the failure path (e.g. what to do if no prepare token exists) but the when-to-use condition is unambiguous.

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

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.

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the bar is lower, but the description still adds real value: the lock-conflict refusal behavior, the lock.conf rule dependency, and the exact approval precondition. It stops short of saying whether a token is single-use or what happens on repeat confirmation, which would fully close the gap.

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?

The core purpose is front-loaded in the first sentence and the locking rationale follows. There is mild redundancy between 'Requires prepare/confirm' and 'Confirms and executes a prepared operation,' but no sentence is wasted.

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 two fully documented parameters, no output schema, and annotations covering the safety profile, the description covers workflow, failure mode, and approval gating well. Only the post-confirmation return/state outcome is left unstated, a minor gap for a confirm tool.

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%, including the exact confirm-phrase string and the token's origin, so the schema carries the parameter burden. The description reinforces the prepare-token workflow but adds no format or validation detail beyond the schema, which is the expected baseline.

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 (check out files) plus the concrete effect of taking an exclusive lock under lock.conf, and explains why teams use it (protecting scenes, prefabs, binary assets). This distinguishes it clearly from uvcs_checkout_prepare, which only stages the operation.

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?

Explicitly states the prepare/confirm dependency and the precondition that the user must have reviewed the prepared payload and approved this exact operation. It also names when the tool fails (files locked by someone else are refused), so the agent knows the refusal path.

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

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

The description adds real behavioral detail beyond the schema: exclusive lock acquisition under lock.conf, refusal of files locked by others, and a short-lived token return. However, it asserts that this tool "takes the exclusive lock so nobody else can check them out or check in changes," which is a server-state mutation while annotations declare readOnlyHint=true; the prepare/confirm framing leaves it unclear whether the lock lands here or at confirm, and that ambiguity is itself undisclosed.

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?

Front-loads the action in the first sentence and keeps each following sentence on a distinct point (lock semantics, refusal, token). The aside about protecting scenes and prefabs is helpful color but slightly expendable.

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 usefully discloses the return value (a short-lived confirmation token) and the locking side effects. Remaining gaps are token lifetime and whether a single conflicting path fails the whole batch — meaningful for a 200-path, multi-file operation.

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% and the single `paths` parameter already documents the workspace-relative format with an example. The description adds nothing about batching, the 200-item cap, or how partial lock conflicts across a path list are resolved, so it does not go beyond 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 concrete verb and resource ("Check out files before editing them") and describes the lock-rule consequence, which separates it from read-only siblings like uvcs_locks or uvcs_pending_changes. The mention of "Requires prepare/confirm" and a confirmation token signals it is the first phase of a pair, but it never names uvcs_checkout_confirm explicitly as the completion step.

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 a clear trigger ("before editing them") and a clear failure condition ("Files locked by someone else are refused"), plus the lock.conf context that explains when the lock behavior applies at all. It stops short of naming alternatives or stating what to do after refusal (e.g. use uvcs_release_checkout_prepare, or ask the lock owner).

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description reinforces this by saying it never deletes branches or changesets, but it adds no further behavioral detail such as permissions, pagination, or selection criteria.

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?

The description is two short sentences with the core purpose front-loaded. There is no wasted wording, and the safety clarification is concise.

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 simple read-only listing tool with full schema coverage and clear annotations, the description provides enough context to call it correctly. It could still improve by describing what makes a branch a cleanup candidate or how results are ordered.

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%, so both parameters are already documented in the input schema. The description does not add meaning beyond the schema for patterns or maxResults, which is acceptable given the full coverage baseline.

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 states a specific verb and resource: it lists temporary/agent branch cleanup candidates. It is clear what the tool does, but it does not differentiate itself from sibling tools such as uvcs_branch_list or uvcs_branch_safety_report.

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 phrase 'for manual review' implies when the tool is useful, but there is no explicit guidance on when to use it instead of alternatives. It also does not state exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's own 'Read-only' merely repeats structured data. It does add one genuine behavioral fact not in the annotations — truncation above 200000 characters — but omits any error or permission behavior for a pending-file diff.

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 compact sentences, front-loaded with the core comparison and followed by the truncation caveat. The only waste is the trailing 'Read-only', which duplicates the annotation; otherwise every sentence carries information.

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 read-only diff tool with no output schema, the description identifies the two versions being compared and the truncation limit, which is enough to call it correctly. It could mention output format (unified diff text) more explicitly, but nothing critical is missing.

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%: both filePath (path relative to UVCS_WORKSPACE of a file with a pending change) and context (0-20 unchanged lines, default 3) are fully documented in the schema. The description adds no parameter detail beyond what the schema already conveys, 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?

States a specific verb (return a unified line diff) and resource (one pending file), and defines scope precisely as the workspace revision versus the file on disk. It does not name the sibling diff tools (uvcs_changeset_diff, uvcs_revision_diff), so an agent must infer the distinction from the scope wording rather than being explicitly routed.

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 phrase 'one pending file' implies usage and the comparison pair tells the agent what this diff covers, but no when/when-not or named alternatives are provided. With near-identical siblings like uvcs_revision_diff and uvcs_changeset_diff present, guidance on when to prefer this tool is implied rather than stated.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds the scope of checks (CM, workspace, MCP configuration) but does not explain what the diagnostic reports, whether it suggests fixes, or what a failed check looks like.

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 front-loaded sentence with no filler. The checked areas are listed directly.

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 zero-parameter diagnostic with no output schema, the description is minimally adequate but incomplete. It does not say what the "check" produces, how failures are surfaced, or how it differs from sibling status tools.

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?

This tool has zero parameters, so there are no parameter semantics to explain. The baseline for a zero-parameter tool 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?

Uses a clear verb ("Check") and names the resources being checked (CM, workspace, and UVCS MCP configuration). It is understandable, but it does not differentiate this diagnostic tool from sibling status/check tools such as uvcs_setup_status or uvcs_workspace_status.

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 description does not say when this tool should be used instead of the many workspace/status/policy/check siblings. A user must infer that "doctor" means diagnostics or preflight validation.

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

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

Annotations already cover the safety profile, so the description adds real value beyond them: newest-first ordering, the exact fields returned, and a non-obvious caveat that dates follow the cm client locale format because cm history has no date format option. It does not say whether maxResults truncation is signalled or how directories recurse.

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 tight sentences: the core action and returned fields come first, then the date-format caveat and safety note. No filler, every clause carries information.

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 two-parameter read tool with no output schema, the description covers ordering, return fields, and a date-format gotcha that would otherwise cause misinterpretation. That is enough for an agent to call it and read results correctly.

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% and both parameters carry descriptions including the 1-500 range and default of 50, so the schema does the heavy lifting. The description adds no parameter-level detail beyond implying that a path may point at a file or directory.

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 ('List the revisions of a file or directory') and enumerates the returned fields (changeset, branch, date, owner, comment). However, it never distinguishes itself from close siblings like uvcs_annotate, uvcs_diff_file, or uvcs_revision_diff, which all operate on file history.

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?

There is no explicit when-to-use guidance and no mention of alternatives, despite a dense cluster of history-related siblings (uvcs_annotate for line-level authorship, uvcs_diff_file for content comparison). 'Read-only' restates the annotation rather than offering routing advice.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false; the description adds meaningful context beyond them – the approval gate and the token-based handoff from prepare. It does not say what happens if the token is reused/expired or what the result looks like, which leaves some behavioral gaps.

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 short sentences, front-loaded with purpose before the condition. Minor redundancy between 'Requires prepare/confirm' and 'Confirms and executes a prepared operation', but no filler.

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 two-parameter confirmation tool with no output schema, the description covers the critical precondition and approval requirement. It omits what the tool returns and error behavior (expired/stale token, duplicate confirm), which is a modest gap for a non-idempotent mutation.

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% and both parameters are fully documented, including the exact confirmPhrase string. The description adds no parameter-level detail beyond the prepare/confirm flow, so the baseline 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?

States a specific verb and resource (create a label on a changeset) and clarifies its role as the confirm half of a two-step flow. It is distinguishable from the many siblings, and the prepare sibling it pairs with is named in the schema. It stops just short of explicitly naming the prepare tool in the description text.

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?

'Requires prepare/confirm' and 'Call only after the user has reviewed the prepared payload and explicitly approved this exact operation' give an explicit precondition and exclusion. An agent knows it must not call this without a prepared token and user approval.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful context that this is a prepare step returning a short-lived confirmation token, but it does not clarify token lifetime or explicitly state that the label is not created until confirm is called.

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 short sentences, front-loaded with the operation and then the workflow constraint. It is efficient, though the first sentence could more precisely describe this as the prepare step rather than the overall create operation.

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?

The tool has no output schema, and the description mentions only that a short-lived token is returned. It does not explain how that token should be used, how long it lasts, or what the confirm step expects, leaving meaningful workflow context incomplete.

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 the schema already documents label, target, and comment with examples. The description adds no parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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: create a Plastic SCM / UVCS label on a changeset. The purpose is clear, but it does not explicitly distinguish this prepare tool from the sibling uvcs_label_create_confirm, beyond mentioning that prepare/confirm is required.

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 phrase 'Requires prepare/confirm' implies a two-step workflow, and the token return hints that a confirm step follows. However, it never explicitly says when to use this tool versus uvcs_label_create_confirm or what to do with the token next.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so 'Read-only' in the description is a restatement rather than new information. It does add the sort order ('newest first') and the projected fields, but says nothing about pagination, empty-result behavior, or how maxResults interacts with the ordering.

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 front-loaded sentence plus a short clause; nothing is buried and there is no preamble. The trailing 'Read-only.' earns little since annotations already say it, a minor redundancy.

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?

All parameters are optional and fully described in the schema, safety is covered by annotations, and with no output schema the description usefully enumerates the returned fields. Only the pagination/result-limit behavior is left implicit, which keeps it short of a 5.

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% – each of the five optional filters (owner, since, branch, nameLike, maxResults) is documented in the schema with format and bounds. The description adds no filter semantics of its own, so the baseline 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?

States a specific verb and resource ('List labels') plus the ordering ('newest first') and the fields surfaced (labeled changeset, branch, owner, comment). The 'list' verb and the uvcs_label_create_prepare/confirm siblings make the read-vs-write split obvious without naming an alternative.

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?

No statement of when to reach for this versus alternatives such as uvcs_branch_list or uvcs_changeset_analytics, and no prerequisites or exclusions. The only signal is the generic 'List' verb; an agent must infer the discovery use case entirely.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: the unfiltered call fans out across all repositories on the server, which is a meaningfully broader and heavier operation than the path-filtered case. It stops short of describing result shape or performance limits.

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 filler, and the broad default behavior is front-loaded ahead of the narrowing option. Every clause carries information an agent needs.

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 zero-required-param read-only list tool with a fully documented schema and safe annotations, this is nearly complete. The only shortfall is that no output schema exists and the description doesn't hint at how lock entries are structured or ordered.

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 both `paths` and `scope` documented inline including the enum meanings, so the baseline is 3. The description reinforces that paths are relative to the current workspace and are optional, but adds nothing about `scope` beyond what the schema already states.

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 ('List exclusive locks') and even names the underlying command (cm lock list). The two operating modes — server-wide listing vs. workspace-file checking — are spelled out, so the agent knows exactly what it gets back.

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 description gives a clear selection rule: omit paths to enumerate every repository on the server, pass paths to target specific files in this workspace. It doesn't name any alternative tool or exclusion, but there is no sibling lock tool to route away from, so context is adequate.

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

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

Adds substantial context beyond the destructive/readOnly annotations: refusal conditions (pending changes, conflicts), the fact that the merge result stays pending until a checkin, the prepare/confirm workflow, and the human-approval requirement. These are exactly the operational traits an agent needs before a destructive mutation.

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?

Front-loads the merge action and refusal conditions well, but the closing sentences are partly redundant ('Requires prepare/confirm' then 'Confirms and executes a prepared operation'), costing a little efficiency.

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, non-idempotent mutation with no output schema, the description covers prerequisites, refusal states, and approval gating. It only omits what the confirmation returns, which is minor.

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 token and confirmPhrase are already documented in the schema (including the exact phrase requirement). The description references the prepare/confirm pairing but adds no syntax or format detail beyond the schema, so the baseline 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?

States a specific verb (merge) and resource (branch/changeset/label into the current workspace branch), then clarifies it confirms and executes a prepared operation. An agent can distinguish it from uvcs_merge_prepare and uvcs_merge_preview without opening any 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?

Explicitly gates invocation: 'Call only after the user has reviewed the prepared payload and explicitly approved this exact operation,' plus the prerequisite of prepare/confirm. It also names when-not (refused on tracked pending changes or conflicts) and routes conflict resolution to the UVCS client.

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

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

The description describes a state-changing merge whose result 'stays pending until a checkin', which is a workspace mutation, yet annotations declare readOnlyHint=true. That is a direct safety-profile contradiction. The useful details about refusals and the short-lived token cannot offset the contradictory read-only claim.

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 the action and immediately followed by the refusal conditions and the mutation lifecycle. No filler, and each sentence contributes a distinct fact.

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?

No output schema exists, and the description does disclose the return value (a short-lived confirmation token), plus preconditions and the pending-until-checkin lifecycle. It is almost complete, but the ambiguity it creates about whether prepare itself writes to the workspace undercuts the safety picture.

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%, and the schema already documents both parameters with concrete examples (/main/task, cs:94, lb:LABEL). The description adds no parameter-level meaning beyond that, so the baseline 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?

Specific verb (merge) plus precise resource set (branch/changeset/label) and destination (current workspace branch), which plainly distinguishes it from uvcs_merge_preview (dry run) and uvcs_merge_confirm (completion).

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?

Explicit preconditions: refuses while tracked pending changes exist, refuses on conflicts (resolve in the UVCS client), and requires the prepare/confirm flow. It gives clear when-to-use context and when-not, but does not explicitly name uvcs_merge_preview as the recommended prior step.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds real behavioral context by stating 'without changing anything' and explaining that providing a destination changes where the preview is computed (on the server for that branch). It does not discuss permissions, rate limits, or output pagination, but with annotations covering safety this is a meaningful addition.

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?

The description is three tight sentences with zero filler: it front-loads the read-only preview purpose, then details the destination behavior. Every sentence earns its place.

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, so the description usefully enumerates the categories of preview results. Annotations cover the safety profile and the schema covers all parameters completely. The only minor gap is the lack of explicit guidance on how this tool relates to merge_prepare and merge_confirm.

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%, so the baseline is 3. The description adds value beyond the schema for the 'destination' parameter by explaining that its presence shifts preview computation to the server for that branch, which is not explicit in the schema's own description.

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 uses a specific verb and resource ('Preview a merge') and immediately enumerates the three categories of output (files taken from source, added/moved/deleted items, conflicts). This distinguishes it from the merge_prepare and merge_confirm siblings without needing to name them.

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 clarifies the effect of supplying or omitting 'destination' (workspace branch vs server-side computation), which is useful usage context. However, it never explicitly says when to use this preview versus uvcs_merge_prepare or uvcs_merge_confirm, leaving the alternative-routing guidance implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds only that output is derived from workspace style rules; it says nothing about what happens when rules are missing or unconfigured, which matters for a preview tool.

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 front-loaded sentence with no filler. The purpose, both output forms and the rule source are all conveyed in twelve words.

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?

No output schema exists, so the description should ideally say what a 'preview' returns (a formatted name/message string) and whether it fails when no style rules are configured. It covers the core action but leaves the agent guessing about result shape and failure modes.

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%, including an enum on 'kind' and per-field descriptions for 'type', 'title', 'summary' and 'baseBranch'. The description adds no semantics beyond the schema, so the baseline of 3 applies — notably it doesn't clarify how 'title' vs 'summary' map to branch vs checkin kinds, which the description could have disambiguated.

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 ('Preview') with two concrete resources ('branch name', 'checkin message') and names the source of truth ('workspace style rules'). This clearly separates it from mutation siblings like uvcs_branch_create_prepare or uvcs_checkin_prepare, though it doesn't explicitly name those siblings.

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 word 'Preview' implies a dry-run before an actual create/checkin, but there is no explicit 'use this before X' guidance, no mention of prerequisites (style rules configured via uvcs_style_setup_check), and no named alternative. Usage is inferable but not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the useful detail that output mirrors `cm status`, but says nothing about result shape, ordering, or whether paths are workspace-relative or absolute.

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 short sentence with the key information front-loaded and no filler. It is arguably over-terse rather than padded, but nothing in it is wasted.

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 no-param, annotation-covered read tool this is borderline adequate, but with no output schema the description should say at least what 'full pending changes' contains (modified/added/private files, etc.). That gap leaves the agent guessing about the payload.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline applies. No misleading parameter language is present.

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 ('Return') and resource ('full pending changes'), and names the underlying source ('cm status'), so the agent knows exactly what data comes back. It does not, however, differentiate itself from adjacent read tools like uvcs_workspace_status or uvcs_changeset_diff.

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?

There is no statement of when to reach for this tool versus the many sibling status/diff tools, and no prerequisites or exclusions are given. The agent must infer usage purely from the tool name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered structurally. The description adds value by enumerating what policy information is shown, but it does not explain the return format or whether results are computed live versus cached.

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 front-loaded sentence with no wasted words. The listed outputs are the core information and are presented directly.

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 zero-parameter, read-only status tool with no output schema, the description gives enough about what is reported for an agent to decide to call it. It could be more complete by saying when to prefer it over related status tools, but the core return content is covered.

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?

The tool takes zero parameters, so there are no parameter semantics to clarify; the baseline of 4 applies. The description does not need to add parameter detail.

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 uses a specific verb ('Show') and enumerates the policy facets returned—workspace identity, safety profile, allowlists, write limits, mass-work guidance—so an agent can tell this is a policy-introspection tool rather than a general workspace status tool. It does not explicitly name or differentiate from siblings like uvcs_workspace_status or uvcs_setup_status, so it falls short of a 5.

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?

There is no explicit when-to-use guidance, no prerequisites, and no alternatives named. An agent can infer that this is useful before write operations because it reports write limits and mass-work guidance, but that inference is not stated.

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

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

With destructiveHint=false already declared, the description usefully adds that locks are released and that modified files retain their checkout and edits, plus the approval-gate requirement. That is real behavioral context an agent could not infer from the annotations. It does not cover the response shape, but no output schema exists and the safety profile is adequately conveyed.

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?

Front-loads the core effect (release unchanged checkouts) before the constraints, which is the right ordering. Slightly redundant: "Requires prepare/confirm. Confirms and executes a prepared operation" repeats the same idea twice, costing a sentence.

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 two-parameter mutating tool with full schema coverage and no output schema, the description covers effect, safety, and the approval precondition. It omits only the return/result behavior, which is a minor gap.

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%, so both token and confirmPhrase are already documented, including the literal confirm phrase. The description only implicitly reinforces the token concept via "prepared payload" and "prepared operation," adding little beyond the schema. Baseline 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?

States a specific verb (release) and resource (checkouts and their locks) with a clear scope qualifier: only files whose content did not change. It contrasts with the modified-file case, which makes the operation's boundary legible. It does not name the explicit sibling (uvcs_release_checkout_prepare) to route against, so it falls just short of a 5.

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?

Explicitly states the precondition: "Requires prepare/confirm" and "Call only after the user has reviewed the prepared payload and explicitly approved this exact operation." That is a concrete gate an agent can act on. It stops short of naming alternatives beyond the modified-files note and gives no explicit "do not call when…" guidance.

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

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

Discloses the two-phase requirement and that the call returns a short-lived confirmation token — context not present in annotations. It also scopes the effect to unmodified files. It does not clarify that the prepare step itself performs no state change, which would resolve the apparent tension with readOnlyHint=true given the imperative 'Release checkouts' phrasing.

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 with the effect stated first and the workflow/token notes after; no filler. Slight redundancy between the opening claim and the modified-files caveat could be merged, but nothing is wasted.

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 one-parameter prepare tool with no output schema, the description covers effect, safety scoping, workflow prerequisite, and return value. Missing only the explicit note that no repository change occurs until confirm.

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 a single well-documented 'paths' parameter, so the schema carries the semantics. The description adds nothing about path format, workspace root, or the 200-item cap, so baseline 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?

States a specific operation: release checkouts and locks, but only for files whose content did not change, and spells out the contrasting behavior for modified files. An agent can tell this apart from sibling prepare/confirm pairs without opening the 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?

Makes the prepare/confirm workflow explicit and redirects the agent for modified files ('check those in or undo them'), which is genuine routing guidance. It never names the confirm sibling directly (uvcs_release_checkout_confirm) or states exclusions such as what happens with files checked out by another user.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so 'Read-only' is largely redundant. The one piece of added context is that planning is driven by workspace style rules, but the description never explains what the plan contains or how it feeds the confirm siblings.

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 compact sentence with the key qualifier ('Read-only') front-loaded at the end of the sentence rather than buried. No wasted clauses, though it is arguably too terse for the tool's role.

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, so the description is the only place an agent could learn what a 'plan' returns (branch name, label, comment text, version). That return shape is left entirely unspecified, which is a meaningful gap for a planning tool.

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%, so all four parameters are already documented, including the releaseType enum and the currentVersion/releaseVersion fallback logic. The description only echoes the major/minor/patch bump concept and adds no format or interplay detail beyond 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 (plan) and concrete outputs (release branch, label, comments) plus the source of the rules (workspace style rules). It does not, however, distinguish itself from close siblings like uvcs_branch_create_prepare, uvcs_label_create_prepare, or uvcs_release_checkout_prepare, which an agent must choose between.

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?

No statement of when to call this versus the many adjacent prepare/confirm tools, nor any prerequisite (e.g., that style rules must be initialized first). 'Read-only' hints it is a preview step, but the agent must infer that.

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

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

Annotations already cover read-only/idempotent/non-destructive, so repeating "Read-only" earns no credit. The genuinely valuable addition is the truncation rule (output > 200000 chars is truncated) and the statement that the result is a unified line diff, which tells the agent what to expect from the return payload.

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 short sentences, front-loaded with the core verb and resource, then the mode variant, then the one non-obvious operational constraint (truncation). No filler.

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 adequately covers the return shape (unified line diff) and its size limit. The remaining gap is disambiguation from the three similarly named diff siblings, which matters for correct tool selection in this crowded namespace.

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%, so baseline is 3. The description's parameter-related statements (omit `to` to compare against the workspace, use `changeset` to see a changeset's change) restate what the schema already documents verbatim, adding no syntax or semantics beyond it.

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 ("Return a unified line diff of one text file") and enumerates both comparison modes (revision-to-revision, revision-to-workspace). It does not distinguish itself from the near-identically named siblings uvcs_diff_file and uvcs_changeset_diff, leaving the agent to guess which diff tool to pick.

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?

"Omit to compare with the file in the workspace" and "Pass changeset to see what that changeset changed" give mode-level guidance. However, there is no explicit when-not and no routing to the obviously overlapping siblings (uvcs_diff_file, uvcs_changeset_diff), so the agent must infer which of the three to call.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered without the description. The phrase 'in one place' adds a small amount of value by implying a single consolidated read rather than multiple calls, but nothing is said about what the result contains or whether it evaluates compliance versus merely reporting configuration.

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 short sentence with no filler, and the scope-defining content ('safety policy', 'naming setup') is front-loaded rather than buried. Nothing in the sentence could be removed without losing information.

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 parameters, no output schema and full annotation coverage, the description covers the minimum. However, since no output schema exists, the description is the only place an agent could learn whether the response is a pass/fail summary, a list of configured values, or a diff against defaults, and it does not say.

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?

The tool takes zero parameters, so the schema carries no semantics to explain and the baseline of 4 applies. The description does not need to compensate for any coverage gap.

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 states a concrete verb ('Show') and a concrete resource ('safety policy and branch/checkin/release naming setup'), and 'in one place' signals it is an aggregating view rather than a mutator. It does not, however, distinguish itself from the closely related siblings uvcs_policy_status and uvcs_style_setup_check, which appear to cover overlapping territory.

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?

There is no statement of when this should be called, when it should not, or which sibling to use instead. Given that uvcs_policy_status and uvcs_name_preview exist alongside it, an agent has no guidance on why it would pick this aggregate view over those narrower tools.

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

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

Annotations already signal a non-read-only, non-idempotent, non-destructive write; the description adds that it writes a specific config file and requires human approval of the prepared payload before execution. It doesn't state whether the token is single-use, what happens on a stale token, or what success returns — modest gaps for a mutation tool that gives the agent useful operational safety context.

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?

Front-loaded with the concrete effect and file path; three short sentences with no filler. 'Requires prepare/confirm' and 'Confirms and executes a prepared operation' overlap somewhat, so one sentence could be trimmed.

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 two-parameter, two-phase confirm step with no output schema, the agent knows what it creates, the prerequisite, and the approval requirement. The only real omission is post-execution behavior (return value, failure modes on a stale token), which is minor at this complexity.

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% and both parameters are documented there, including the exact confirmPhrase literal and the token's source. The description adds no further semantics about token lifetime or format, so the schema does all the work per baseline.

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?

Names a specific verb and resource (creates .uvcs-mcp/style.json) and enumerates its contents: branch naming, checkin message, release conventions. The prepare/confirm framing also distinguishes it from the prepare sibling, though 'Create' versus 'confirms and executes' leaves slight ambiguity about whether this call or the prepare call actually writes the file.

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?

Explicit precondition: 'Requires prepare/confirm' and 'Call only after the user has reviewed the prepared payload and explicitly approved this exact operation' — a clear gate that tells the agent when not to call. The paired prepare tool is named only indirectly ('Requires prepare/confirm') rather than by its tool name, which lives in the schema instead.

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

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

The description says the tool creates a file and exposes an `overwrite` parameter for replacing an existing style.json, while annotations declare readOnlyHint=true and destructiveHint=false. The write/possible-destruction claim conflicts directly with the read-only annotation, and no permission or side-effect detail resolves the inconsistency.

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 short sentences, front-loaded with the action and artifact, then workflow, then return value. No filler, though the middle 'Requires prepare/confirm' sentence could be folded in.

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?

Usefully discloses the short-lived confirmation token since there is no output schema, and flags the prepare/confirm pairing. But for a file-writing tool with no annotations support, it omits where the file is written, what happens to an existing file without overwrite=true, and whether the token is consumed by uvcs_style_init_confirm.

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%, so all five parameters (including the preset enum and overwrite warning) are already documented at field level. The description adds only an aggregate view of what the config covers, not parameter-specific meaning beyond 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 and artifact (create .uvcs-mcp/style.json) plus the contents it encodes (branch naming, checkin message, release conventions). This clearly separates it from siblings like uvcs_style_rules (read rules), uvcs_style_setup_check (diagnose), and uvcs_style_init_confirm (apply).

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?

'Requires prepare/confirm' signals the two-step workflow and implies this tool is the first step, which is useful routing. However, it never says when to call this versus uvcs_style_setup_check or uvcs_style_rules, nor gives conditions for choosing a preset or deciding to overwrite.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the returned content concerns workspace naming and release style rules, but says nothing about the shape or volume of the response beyond that.

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 front-loaded sentence with no wasted words. Perfectly sized for a simple, zero-argument read tool.

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 zero-param read-only tool with annotations covering safety and no output schema, the description identifies the returned subject area. It could say more about what the rules consist of, but it is adequate given the tool's simplicity.

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?

The tool takes zero parameters, so the baseline is 4 and no parameter semantics are needed. The description correctly implies a parameterless read.

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 ('Return') and resource ('workspace naming and release style rules'), so an agent knows it retrieves style configuration. However, it does not distinguish itself from near-neighbors like uvcs_style_setup_check and uvcs_name_preview, which could also surface style-related information.

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?

There is no guidance on when to call this versus the style_init or setup_check siblings, and no prerequisites or exclusions are mentioned. The agent must infer usage from the name alone.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the pre-branch gating behavior and the missing-rules escalation path, but it does not explain what the check returns or what happens when rules already exist.

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, front-loaded with the purpose and followed by the conditional next action. There is no redundant or wasted text.

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 zero-parameter read-only check, the description covers when to run it and what to do if rules are missing. However, there is no output schema and the description does not explain the return shape or how 'missing' is represented, leaving a meaningful gap for interpreting results.

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?

This tool has zero parameters, which is the baseline 4 case. There are no parameter semantics for the description to clarify, and the schema is empty.

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 states a specific verb and resource: check whether workspace naming/checkin/release style rules exist. It is clear what the tool does, but it does not explicitly distinguish itself from the sibling uvcs_style_rules tool, so it falls short of a 5.

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 a clear usage context: run this before branch work, and if rules are missing, ask the user to create them. It does not name alternatives or when-not-to-use conditions, but the timing and follow-up action are explicit.

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

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

Annotations already flag destructiveHint=true and idempotentHint=false, so mutation risk is declared. The description adds real value beyond that: the pending-changes refusal rule and the human-approval gate before execution. It stops short of describing the outcome of a successful switch (what state changes, what the response returns), which is the only notable gap.

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 short sentences, front-loaded with the action and followed by preconditions and the approval gate. There is mild redundancy between 'Switch the workspace...' and 'Confirms and executes a prepared operation,' but nothing that materially dilutes the guidance.

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 two-step confirm tool with no output schema, the description covers the action, the prerequisite prepare step, the blocking condition, and the approval requirement an agent must satisfy before calling. Nothing essential to correct invocation is missing.

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%, with both token and confirmPhrase fully documented in-schema. The description only implies the token chaining via 'Requires prepare/confirm' and adds no new detail about the token or the exact confirmPhrase, so baseline 3 is right.

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 ('Switch the workspace to a branch, changeset, or label') and then clarifies that this tool is the confirm/execute half of a two-step flow. That distinguishes it cleanly from the sibling uvcs_switch_workspace_prepare without needing the 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 explicit preconditions: 'Requires prepare/confirm' and 'Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.' It also names a blocking condition ('Refused while tracked pending changes exist'), so the agent knows when the call will fail rather than be executed.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so the bar is lower, yet the description adds substantive behavior: a refusal condition, a mandatory confirm follow-up, and that the call returns a short-lived confirmation token rather than performing the switch. It stops short of saying how long the token lives or what happens if it expires.

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 short sentences, front-loaded with the action, then precondition, then workflow/return. No filler, and each sentence contributes a distinct fact an agent needs.

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 single-parameter prepare tool with no output schema, the description covers what it does, the blocking condition, the confirm handoff, and the token return. Remaining gaps — token lifetime and whether confirm re-takes the same target — are minor but real.

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% and the schema already supplies example syntax (/main/task, cs:92, lb:LABEL). The description's 'branch, changeset, or label' informally names those same categories, adding only marginal semantic value over the structured field — baseline 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?

States a specific verb (switch) and resource (workspace) with the three target kinds (branch, changeset, label), which maps directly to the sole parameter. It signals the prepare/confirm pairing rather than naming teammates like uvcs_checkout_prepare or uvcs_update_workspace_prepare, so sibling differentiation is only partial.

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?

Provides a real precondition ('Refused while tracked pending changes exist') and the two-step prepare/confirm requirement, which is genuine usage context. However, it never says when an agent should pick this over the similarly named uvcs_checkout_prepare or uvcs_update_workspace_prepare, and offers no exclusion rule beyond the pending-changes block.

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

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

Annotations already flag destructiveHint=true, idempotentHint=false, readOnlyHint=false, but the description adds the crucial context that the effect is irreversible and gated on human approval of the exact prepared payload. It does not spell out what specifically gets discarded beyond 'pending changes', which keeps it from a 5.

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 short sentences, front-loaded with the effect and irreversibility before the gating requirement. There is mild redundancy between 'Requires prepare/confirm' and 'Confirms and executes a prepared operation', which costs a point but costs nothing important.

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 two-parameter, fully-schema-documented destructive confirm tool with no output schema, the description supplies effect, scope, irreversibility, and the approval gate. Only the concrete consequence of an accidental call (what state is lost) is left implicit.

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 both parameters (token, confirmPhrase) are documented in the schema, including the exact literal for confirmPhrase. The description adds no parameter-level detail, so the baseline 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?

Names a specific verb and resource ('Irreversibly undo pending changes for one path') and scopes it to a single path within the selected workspace. The phrase 'Confirms and executes a prepared operation' separates it from the prepare sibling without the agent needing to open the 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?

States explicit preconditions (requires prepare/confirm, user must have reviewed the payload and approved this exact operation) and an explicit exclusion (workspace-root undo is forbidden). That covers when to call, when not to call, and the sibling it depends on.

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

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

The description does add valuable context beyond the schema (irreversibility, root-path prohibition, token return), which is normally creditable. However, it claims this call irreversibly undoes changes while annotations declare readOnlyHint=true and destructiveHint=false; the description's framing makes the tool look destructive when the prepare step is not, creating a direct conflict with the structured safety signals.

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 short sentences, each carrying a distinct fact (action, scope restriction, workflow requirement, return value). The destructive consequence is front-loaded, which is exactly right for a high-risk operation.

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 should clarify the token's use and lifetime and that uvcs_undo_confirm performs the actual undo; it only says "short-lived confirmation token." The core risk facts are present, but the handoff to the confirm step and the token contract remain underspecified for a destructive workflow.

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%, so both itemPath and recursive are already fully documented in the schema. The description's "one path" and "workspace-root undo is forbidden" restate the schema's itemPath constraint without adding syntax, format, or recursive-handling detail, so baseline 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?

States a specific verb and resource ("undo pending changes") plus the scope restriction ("for one path inside the selected workspace"). It signals the prepare/confirm pairing, though it never names the sibling uvcs_undo_confirm by name, so the agent must infer which tool completes the operation.

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?

"Workspace-root undo is forbidden" and "Requires prepare/confirm" give real invocation constraints, but the description never says when to choose undo over alternatives such as uvcs_revision_diff or uvcs_checkout, nor what to do with the token afterwards. Usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered. The description adds only the workspace scope and mismatch category; it does not say whether it scans read-only, returns a list, or what 'common' mismatches include.

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?

One short sentence with no filler; purpose and scope are front-loaded. Every word earns its place.

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 zero-parameter, read-only diagnostic with full annotation coverage and no output schema, the description gives enough to select and invoke it. It leaves the exact return shape and definition of 'common mismatches' implicit, but nothing critical is missing for this simple tool.

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?

The tool takes zero parameters, so the baseline is 4; there are no parameter semantics to document and the description does not need to compensate for schema gaps.

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 ('Detect') and a precise resource ('common Unity asset/.meta mismatches') scoped to the workspace. This distinguishes it from general diagnostics siblings such as uvcs_doctor, though it does not explicitly name any alternative.

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 no explicit when-to-use guidance, no prerequisites, and no alternatives. Usage is only implied by the diagnostic purpose.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is known. The description adds real value beyond that: it discloses the failure mode ('Local edits to files changed upstream can produce merge conflicts') and imposes a human-approval gate. It stops short of saying what state the workspace is left in if a conflict occurs, which keeps it from a 5.

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?

Front-loaded with the operation and four short sentences with no filler. Minor redundancy between 'Requires prepare/confirm' and 'Confirms and executes a prepared operation', which say nearly the same thing.

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 mutation with no output schema, the description covers the precondition, the risk, and the approval requirement. What happens on conflict or partial failure is not described, but nothing essential to correct invocation is missing.

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% and both parameters are fully documented there, including the exact confirm phrase. The description adds no syntax or format detail beyond the schema, so this sits at the baseline.

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 ('Update the workspace to the latest changeset of its branch') and situates it in the prepare/confirm pair, so it is clearly distinguishable from uvcs_update_workspace_prepare and from the other *_confirm siblings.

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?

Explicit sequencing ('Requires prepare/confirm'), explicit precondition ('Call only after the user has reviewed the prepared payload and explicitly approved this exact operation'), and the token parameter ties it to the prepare call. No inference needed about when this is safe to invoke.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and the description is consistent with them: this prepare step returns a token instead of applying the update. Beyond that, it adds real behavioral value: it warns about merge conflicts and says the token is short-lived. It does not say what happens to the token if it expires before confirm.

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 short sentences, front-loaded with the action, followed by the risk, then the protocol. Every sentence earns its place with no filler.

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 are no parameters and no output schema; the description states the return value is a confirmation token and flags the main hazard, so an agent has enough to call it and chain into confirm. Minor gaps remain: token lifetime and how the token is supplied to the confirm call.

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?

There are zero parameters and the input schema confirms an empty object, so there is nothing for the description to document. The baseline of 4 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?

States a specific verb and resource: it updates the workspace to the latest changeset of its branch. The phrase "Requires prepare/confirm. Returns a short-lived confirmation token" makes clear this is the first half of a two-step flow, which distinguishes it from uvcs_update_workspace_confirm, though the sibling is never named explicitly.

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 the operational context needed for caution: local edits to upstream-changed files can cause merge conflicts. It also implies the required follow-up, the confirm call, through the prepare/confirm statement. It does not compare against alternatives such as switch_workspace or merge, so it stays below a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description is consistent with a safe read. The only additional trait is that output is 'concise'; it does not describe scope, return format, or prerequisites. With annotations covering safety, this modest addition is adequate for a 3.

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?

The single sentence is front-loaded and has no wasted words. Its terseness contributes to under-specification, but the conciseness dimension itself is strong.

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 should at least indicate what 'workspace status' includes; it does not. The many sibling status and diagnostic tools also make the lack of scope and differentiation a material gap for selection.

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?

The tool has zero parameters and 100% schema coverage, so there are no parameter meanings for the description to clarify. The baseline for zero-parameter tools 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 and resource: returning workspace status. It is clear enough to identify the action, but it does not differentiate this summary from sibling status/inspection tools such as uvcs_pending_changes, uvcs_branch_info, or uvcs_policy_status.

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?

There is no when-to-use or when-not-to-use guidance and no alternative named. An agent must infer that this is the general workspace status check rather than one of the several specialized status siblings.

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