data_merge

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

The description adds valuable behavioral context beyond the readOnlyHint annotation. It explains the deep merge behavior ('values from the second file override or extend those in the first'), describes the conditional output behavior (write to file vs return in response), and documents error conditions. While annotations already indicate it's read-only, the description provides operational details that help the agent understand how the tool behaves.

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 well-structured and efficiently organized. It begins with a clear purpose statement, then explains the merge behavior, followed by organized parameter explanations, return value documentation, and error conditions. Every sentence serves a distinct purpose with zero wasted text, making it easy to parse and understand.

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 tool's complexity (file merging with format handling), the description provides complete context. It covers the merge algorithm, parameter semantics, output behavior, return structure, and error conditions. With both comprehensive annotations (readOnlyHint) and an output schema (implied by the Returns section), the description fills all necessary gaps without redundancy.

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?

With 100% schema description coverage, the baseline would be 3, but the description adds meaningful semantic context. It clarifies the relationship between file_path1 and file_path2 ('base' vs 'overlay'), explains the default behavior for output_format ('defaults to the format of the first file'), and describes the conditional logic for output_file ('when omitted, merged content is returned'). This provides valuable interpretation beyond the schema's technical specifications.

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 clearly states the specific action ('merge two files into a single deep-merged configuration'), identifies the resource ('files'), and distinguishes from siblings by specifying it's for merging configuration files rather than querying, converting, or validating data. The mention of 'deep merge' provides technical specificity beyond a generic merge operation.

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 implies usage context through the parameter explanations (e.g., 'overlay file whose values override the base'), but doesn't explicitly state when to use this tool versus alternatives like data_convert or data_query. No explicit when-not-to-use guidance or named alternatives are provided, leaving usage context somewhat implied rather than clearly articulated.

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