merge_branch

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It honestly states that on conflict it returns a 'conflicts' list instead of merging, that retrying with resolutions merges everything including previously non-conflicting changes, and that unresolved identities are reported again. It also reveals the commit behavior ("commits the merged result as a new version of the target session"). This is highly transparent.

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 a single dense paragraph that front-loads the core purpose and then methodically covers conflict handling, retry semantics, and alternative paths. Each clause earns its place, but the length and density make it slightly harder to parse quickly. It is efficient but not maximally concise.

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?

Given the complexity of a three-way merge tool, the description is remarkably complete. There is no output schema to explain return values, but the description covers the success case, conflict return format, retry workflow, and final cleanup via close_session. It also accounts for the edge case where the user wants to modify the target directly. This is sufficient for an agent to select and invoke the tool correctly.

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?

Though the input schema already describes each parameter (100% coverage), the description adds significant semantic value. It explains the 'resolutions' parameter in detail, including the behavior of merging everything in one call and the meaning of each resolution value. It also clarifies 'base_version_id' overrides and the roles of source/target session IDs, going beyond the schema's per-parameter descriptions.

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 specific verb and resource: "Session-aware three-way merge: merge a branch session's changes into a target session." It clearly distinguishes this tool from merge_knowledge by noting the automatic base resolution and the lack of user-supplied base. This makes the tool's purpose unambiguous and differentiates it from a direct 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?

The description provides explicit usage guidance: it contrasts with merge_knowledge ("unlike merge_knowledge -- you never supply the base yourself"), instructs not to call merge_branch unchanged after a conflict, directs the retry with a 'resolutions' argument, and offers an alternative path via evolve_knowledge. It also tells the user to close_session the source branch once fully integrated. This is comprehensive when/when-not guidance.

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