skip_sync_run

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

Beyond destructiveHint=true, the description details the permanent, irreversible nature: 'this is PERMANENT, not a deferral' and explains the resulting state where skipped migrations stay in the repo but are absent from the live database, with nothing reporting the divergence afterward. It also discloses API behavior (400 unless acknowledged is true), adding real context the annotations do not convey.

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 purpose is stated in the first sentence, and subsequent sentences—permanence warning, transient-failure reasoning, acknowledgment workflow—each add a distinct fact an agent needs before invoking a destructive operation. No filler or repetition undermines the structure.

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 sync action, the description covers what happens to failed jobs, the run state, downstream sync behavior, the warning about divergence, the alternative, and the required acknowledgment flow. With an output schema present and annotations already recording destructiveness, nothing essential is missing for safe invocation.

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 schema already documents all three parameters, but the description adds operational meaning for acknowledged: it must be sent only after the user has seen the consequence and explicitly approved, and it cannot be used merely to clear the error. It also clarifies that runId refers to a FAILED run, tying the parameter to a precondition.

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 the specific verb and resource: 'Skip all failed jobs in a connected-project sync run, marking them completed with skipped=true.' It also scopes the operation to a FAILED run and names the sibling alternative, retry_sync_run, so an agent can distinguish this tool from its siblings without opening their schemas.

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 explicitly instructs 'Prefer retry_sync_run' and explains why most failures are transient, giving the agent a clear decision rule for when not to use this tool. It also prescribes the acknowledgment workflow—show the consequence, get explicit approval, re-send—and warns 'Never set acknowledged just to clear the error.'

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