tree

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

Annotations already set destructiveHint=true, and the description meaningfully extends that by stating delete is PERMANENT, requires confirmName to match the exact tree name, and requires user confirmation first. It also discloses export's dual write-or-base64 behavior and import's wait-for-completion behavior, which are non-obvious operational details.

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 front-loaded with the resource and packs all action semantics, prerequisites, and danger warnings into a compact, structured format. Every clause adds operational value and nothing is repeated or filler.

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 8-action, 16-parameter tool with no output schema, the description covers action effects, required parameters, and unusual return behaviors such as export's base64 option and import's waiting behavior. It does not state what create, update, set_privacy, or delete return, which an agent may need for follow-up operations.

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 25% schema coverage, the description compensates by connecting actions to required parameters and clarifying the purpose of outPath, filePath, and confirmName. However, 'root* fields' is ambiguous about which root properties are actually required, and rights, isPublic, and searchable are left to inference.

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 identifies the resource as family trees owned by the user and enumerates eight specific actions, each with a short effect (e.g., 'get (home person, counts, quality stats)', 'export_gedcom (writes ZIP with .ged to outPath, or returns base64)'). This is clearly distinct from sibling tools like person, fact, and record, which operate on other resource types.

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 final sentence provides explicit per-action prerequisites: 'get/update/set_privacy/export_gedcom/delete need treeId; create needs name + root* fields; import_gedcom needs name + filePath.' It also gives a clear workflow warning for delete: confirm with the user and provide confirmName. It does not explicitly name sibling alternatives, but the resource scope and action list establish when to use this tool.

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