merge_people

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

No annotations are provided, so the description carries the full behavioral burden, and it does so thoroughly: it discloses destructiveness, irreversibility, permanent deletion of merged persons, the transfer of faces, the preview behavior when confirm is false, and the side effects with confirm=true. The description is explicit that without confirm=true nothing happens, which is essential for an agent to avoid accidental data loss.

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 dense but organized: a clear purpose sentence, a behavioral warning, a workflow explanation, then a compact Args list and Returns line. Every sentence earns its place. Slightly long, but the destructive complexity justifies the length; the Args section could arguably be tightened, but it remains highly 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?

Given that there are no annotations and no schema descriptions for parameters, this description provides everything an agent needs: purpose, when to use, destructive consequences, the confirm gate, parameter semantics, and return shape. The output schema exists and the description even names the preview keys, making the return behavior clear without redundantly restating the schema.

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 explain all three parameters, and it does: person_id is the target UUID that keeps faces, merge_ids are the persons absorbed and permanently deleted, and confirm is the boolean switch between preview and execution. It also mentions the default behavior (nothing happens without confirm=true) and the return structure, which adds meaning far beyond the raw 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 opens with a specific verb and resource ('Merge multiple person clusters into one') and adds the crucial scoping detail that it is for the case where the same real person has been split into multiple face clusters. It is clearly distinguished from siblings like update_person, reassign_face, or delete_assets.

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 explicitly states when to use it ('when the same real person has been split into multiple face clusters') and explains the confirm=true vs confirm=false workflow, telling the agent to pass true only after the user has seen the preview and agreed. It also warns about irreversibility, which serves as a clear exclusion criterion.

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