sync_application

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

With no annotations provided, the description carries the full behavioral burden. It discloses that dry-run is the default, that changes are non-destructive, that pruning is never performed, and flags the confirmation requirement on the prune variant. While it doesn't detail return values or side effects of force, the key safety-relevant behaviors are well disclosed.

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 sentences, front-loaded with the purpose and safety posture. Every sentence earns its place: purpose, dry-run behavior, and the prune alternative/confirmation note. Slightly verbose in the prune clause but acceptable given the important safety distinction.

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 an output schema present and a 5-parameter schema that is reasonably self-documented, the description covers the critical behavioral dimensions: safety posture, dry-run default, and the destructive alternative. It could mention the force parameter's behavior or what the return format looks like, but the safety tradeoffs most important for agent decision-making are 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%, meaning the description should compensate for parameter documentation. However, the description does not describe any parameters beyond the dry_run/dry_run=false distinction embedded narratively. The schema itself has decent per-parameter descriptions (name, force, dry_run, instance, revision all explained), so the baseline is moderate. The description adds minimal parameter value beyond 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?

The description states a specific verb+resource (synchronize application with Git repository) and clearly distinguishes scope by noting it is non-destructive and never prunes resources. It explicitly contrasts with the Tier-3 sync_application_with_prune alternative, which differentiates it from the closest sibling.

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?

Excellent guidance: explicitly states dry-run default behavior, when to set dry_run=false to apply, that it NEVER prunes resources, and names the exact alternative tool (sync_application_with_prune) to use for pruning. This maps directly to a sibling tool and defines when-not-to-use this one.

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