project_transfer

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

Annotations already declare write (readOnlyHint=false), non-destructive, non-idempotent, closed-world behavior, so the safety profile is covered. The description adds genuinely useful behavior: the output format is GEDCOM 5.5.1 and the export lands next to the project file, and import creates a new project. It does not say whether import overwrites existing data or what permissions are needed.

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?

A single, front-loaded sentence covering both operating modes with no filler. It is efficient, though the app-name parenthetical is slightly ornamental and the two modes could be split for faster scanning.

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?

An output schema exists, so return values need no explanation, and annotations cover the safety profile. What remains missing for a 3-parameter mutation tool is the export-side meaning of 'file', any overwrite/merge caveat on import, and a pointer to project_save as the prerequisite — a real gap given the low 33% schema coverage.

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 coverage is 33% (only 'file' is documented), so the description should compensate more than it does. It maps well onto the 'direction' enum by describing both export and import flows, and it hints at output location, but it says nothing about the required 'project' parameter and never clarifies the 'file' parameter's role on the export side.

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?

States a specific verb+resource pair with two named modes: exporting the project as GEDCOM 5.5.1 next to the project file, or starting a new project from an external GEDCOM. It also names target applications (MyHeritage, Ancestry, Gramps, Geni), which differentiates it from the project_view/project_save siblings. It falls short of 5 because it never explicitly ties these two modes to the 'direction' enum values.

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 two clauses imply when to use each mode (interop with other genealogy programs vs. onboarding a foreign GEDCOM), giving usable context. However, there is no explicit when-not-to-use, no required prerequisites (e.g. project must already exist/saved), and no mention of the project_save sibling it relates to.

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