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

Beyond the annotations, the description explains that nothing is removed, that the surviving person keeps spellings and facts with sources, and that find_person, list_persons, and marks will answer for any spelling afterward. It also covers chained merges, rejected-person handling, journal lines, write-access requirements, and the AI plan requirement.

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 core purpose and prerequisite are front-loaded, and each sentence carries relevant information. Some phrasing is dense or slightly cryptic, such as 'Both journals keep a line,' but the description remains efficient for a tool with this many behavioral edge cases.

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 destructive, permission-gated mutation tool with no output schema, the description is unusually complete: it covers semantics, reversibility, lookup consequences, access control, and edge cases. An agent has what it needs to decide whether to call it and how to use the two integer parameters 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?

Schema description coverage is 100%, so the two parameters are already documented as the person merged and the person who stays. The description adds useful semantic nuance by tying the parameters to list_persons output and clarifying that merging into an already-merged person resolves to the ultimate survivor.

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 states a precise verb and resource: merge one person of a project's register into another when they are the same human being. It even provides an example («Sjorgren» into «Sjogren»), making the operation distinct from sibling tools like list_persons, find_person, and unmerge_person.

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?

It gives explicit when-to-use guidance (when two records are one human being) and warns that list_persons' 'similar' marker is only a hint, not sufficient reason to merge. It also says to ask the person first, names the undo path through unmerge_person, and states permission and plan prerequisites.

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