person

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

Annotations already mark the tool as destructive, and the description goes well beyond that: it warns that edits are public and attributed, that living people created by the user are private, that non-standardized dates/places get flagged, and that delete only works on people the user created. This adds meaningful behavioral context not inferable from annotations or schema.

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 well-organized as a compact action list with parentheticals, making ten actions scannable. It front-loads the most important operational warning about public, attributed edits and change reasons. It is long, but given the multi-action surface area, very little is wasted.

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 complex 30-parameter, multi-action tool with no output schema, the description covers action semantics, search syntax, edit conventions, and privacy/destructive behavior thoroughly. It does not detail response shapes or pagination/offset behavior, which remains a meaningful gap, but the description is complete enough for correct action selection and invocation in most cases.

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 only about 10% schema description coverage, the description does substantial compensating work: it explains fact id semantics for updates, formalDate/placeId standardization requirements, wildcard behaviors for name search, the records flag for matches, and the sources flag for get. Some parameters remain under-described (count, offset, includeSources, spouse-like fields), but the key behavioral parameters receive solid treatment.

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 identifies the resource (people in the FamilySearch Family Tree) and enumerates the specific actions available: get, search, ancestry, descendancy, changes, matches, create, update, delete_conclusion, and delete. It also distinguishes itself from sibling tools by explicitly deferring to relationship.create for connecting people and place.search for place lookups.

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 gives explicit usage conditions for each action: create is for unconnected persons, connect via relationship.create; updates with a fact id edit while without id they add; matches may return record hints; delete requires a reason. It also states a global rule that public, attributed edits always need a changeMessage/reason, which is exactly the kind of context an agent needs to invoke the tool safely.

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