com_combine_documents

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

No annotations are provided, so the description carries the behavioral disclosure burden. It adds meaningful context: output defaults beside the original, original attributions are preserved, and Word must be installed. It does not explicitly state whether input files are modified or what happens if output_path already exists, but the provided behavioral details are substantive.

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 compact and front-loaded: purpose first, then usage guidance, alternative, output behavior, and prerequisite. Every sentence earns its place, and there is no redundant or vague phrasing.

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 moderate-complexity Word operation with no annotations, the description covers the main requirements: purpose, when to use, primary alternative, output location, and environment prerequisite. Since an output schema exists, return-value details do not need to be spelled out. The only notable gap is the lack of explicit per-parameter mapping for original_path and revised_path.

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%, so the description must compensate. It explains output_path's default behavior ('Output defaults beside the original'), but original_path and revised_path are left to their self-descriptive names without explicit explanation of which document each must point to. This is adequate but not fully compensating for the missing schema 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 starts with a specific verb-resource pair: 'Combine two reviewers' tracked changes into one document' and explicitly preserves original attributions. It also distinguishes itself from com_compare_documents by naming the alternative, so an agent can tell this from the closest sibling without opening the schema.

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?

Explicit usage guidance is present: 'Use when two people edited copies of the same draft and you need a unified redline.' It also gives a clear exclusion: 'For diffing two versions to discover what changed, use com_compare_documents instead.' This leaves little to inference.

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