Synchronize Document

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is partly covered. The description usefully adds that a two-step confirmation/token-retry flow exists, which explains the confirm_token parameter and the approval requirement. However, it never says what is actually destroyed or overwritten (local changes pushed to the central model, potential conflicts), which is the key behavioral fact for a destructive sync.

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?

It is a single sentence with no padding, which is good. But it is front-loaded with the conditional gate instead of the action, and the phrase 'for the token retry' is ambiguous without prior context about confirmationText.

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 8-parameter operation with zero schema documentation, the description is far too thin. It does not describe the effect on the central model, conflict behavior, or the meaning of the relinquish/save-local options. An output schema exists, so return values need not be explained, but the preconditions and side effects are not 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?

Schema description coverage is 0% across 8 parameters, so the description carries the full burden and fails to meet it. It alludes to the confirm-token flow, but document, comment, compact, process_id, relinquish, save_local_before, and save_local_after get no explanation anywhere. An agent must guess at relinquish semantics and the save-local flags.

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 opens with 'Synchronize only after...' which is a workflow gate rather than a statement of what the tool does. It never names the resource (the Revit document / central model) or explains what synchronizing means in this context, and it does nothing to distinguish itself from the sibling revit_save_document. The purpose is inferable only from the tool name.

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 states one explicit precondition: show confirmationText and receive explicit chat approval before retrying with a token. That is genuinely useful gating guidance, but there is no when-not guidance, no mention of alternatives such as revit_save_document, and no indication of the required document state (e.g. worksharing enabled).

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