ad_sync_replication

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

No annotations are provided, so the description carries the full behavioral burden and delivers only the word [WRITE]. It does not disclose that the operation forces directory replication (potentially bandwidth/impact heavy), what confirmation_token does, or that dry_run exists as a safety valve. The [WRITE] marker is the only real signal beyond the name.

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 short sentence with the category tags and write marker front-loaded, so nothing is wasted. But the concision comes from omission rather than discipline — the sentence is too thin to be actionable.

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 mutation tool with no annotations, a confirmation-token parameter, and an output schema, the description should at minimum explain the dry-run/confirm sequence and the targeting rule. It leaves all of that to the agent's guesswork; only the presence of an output schema saves it from a 1.

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?

All five parameters (all_dcs, dry_run, target_dc, correlation_id, confirmation_token) have 0% schema description coverage, and the description adds no meaning for any of them. The mutual exclusivity implied by all_dcs vs target_dc, and the confirm-token flow required before a real run, are completely undocumented.

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 verb+resource is identifiable ('request replication synchronization'), and the bracketed tags place it in the replication/diagnostics family. However, it never states what is actually synchronized (a specific DC, the whole domain, inbound vs outbound) nor distinguishes it from the read-only siblings such as ad_get_replication_status or ad_get_replication_partners that dominate the same namespace.

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 / when-not-to-use guidance at all. An agent cannot tell whether this should be called proactively as remediation after ad_get_replication_failures, or only on explicit operator request, and the presence of a confirmation_token suggests a guarded workflow that is left entirely unexplained.

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