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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It thoroughly explains the internal call to sync_from_main, the two-parent merge commit creation, the newest-wins conflict resolution heuristic, and the reporting of every decision. It even illustrates why this matters with a real-world example and the merge-base pitfall. This is exemplary transparency for a tool with no annotations.

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 long but every sentence earns its place. It opens with the core purpose, then usage triggers, then critical behavioral details, and ends with a who-needs-this note and a dry_run tip. The structure front-loads the essential usage decision and builds context logically. There is no filler or repetition, making it dense but perfectly scannable.

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 tool with no output schema and a complex operation (branch reconciliation), the description covers all necessary aspects: what it does, when to use it, how it resolves conflicts, why it behaves that way, and how to test it safely. It even explains the broader scenario of tenants needing this. An agent has enough to call it correctly and interpret the reported decisions. 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 coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds specific context for dry_run: 'Pass dry_run:true to see the decisions before writing anything.' This goes beyond the schema's terse 'Report the per-file decisions without writing the merge commit' by clarifying it as a pre-flight check. For solution_id, the schema already says 'The solution ID,' and the description doesn't add much—but that's fine given full coverage. The extra dry_run nuance justifies a 4.

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 a precise verb-action pair: 'JOIN a diverged dev and main.' It clearly states the tool's purpose and differentiates it from siblings by referencing ateam_github_promote's specific return codes and explicitly contrasting with ateam_github_sync_from_main. An agent can immediately understand what the tool does and why it exists.

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 explicit conditions for use: 'Use when ateam_github_promote returns PROMOTE_NEEDS_HUMAN or PROMOTE_PRECONDITION_FAILED.' It also instructs to 'TRY sync_from_main FIRST' and explains this tool calls it internally, escalating only on real conflicts. This provides a clear decision path and alternative, leaving no ambiguity about when to invoke it.

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