compare_person

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

Annotations only give readOnlyHint and openWorldHint, yet the description goes far beyond them: it discloses that nothing is changed, that 'packets' of proposed changes are drafted for manual execution, that living persons are refused, that an access token is required, and that the tree is community-edited with common same-name conflations. This is exactly the extra behavioral context the annotations cannot carry.

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?

Purpose and the no-mutation guarantee are front-loaded, but the prose is dense with layered admonitions ('A difference is not an error', 'weigh it, never follow it', 'This is a hint where to look, not evidence') that overlap somewhat. Most sentences earn their place for a high-risk genealogy workflow, but trimming is possible.

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?

With no output schema, the description does the work of explaining the return shape (agree/lacks/differs plus drafted packets) and the manual follow-up. Combined with the rich 100%-covered input schema and readOnly annotations, an agent has what it needs, though error or token-failure behavior is unstated.

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 every parameter, including confidence grading and source-URL matching, is already documented in the schema. The description reiterates the concept (confidence gates proposals, sources match by URL) but adds no syntax or value detail beyond it, so the baseline of 3 applies.

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 first sentence names a specific verb and resource: compare the caller's own record of one deceased person against their FamilySearch profile. It is clearly distinguished in kind from the retrieval siblings (get_person, get_ancestry), though no sibling is named explicitly, which keeps it just short of a 5.

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 sets context and preconditions well: confirm the profile is your person first, the tool refuses anyone possibly living, and the output is a hint to follow to a record rather than evidence. It does not name an alternative tool for the retrieval case, so it stops short of explicit when/when-not routing.

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