import-project-template

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

Annotations declare write semantics (readOnlyHint: false); the description adds critical context beyond that: "This writes immediately and cannot be undone" and the warning to only run against projects the user explicitly named. The irreversibility warning and the distinction between gallery vs. personal template permissions in the schema enrich the annotation-only picture. No contradiction with annotations.

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?

Four sentences, zero filler. The purpose is front-loaded, followed by sourcing options, workflow sequencing, and a critical irreversibility warning — every sentence earns its place.

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 4-parameter import tool with 100% schema coverage and an output schema present, the description covers all key operational concerns: merge behavior, input sourcing, project-creation prerequisite, and irreversibility risk. Nothing material is left unaddressed for an agent to execute 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 rich per-parameter docs carry the burden. The description adds only a high-level summary ("by template ID/URL or by passing CSV content") that maps to templateId vs csvFileContent, reinforcing the exclusive-or relationship already documented in the schema. This is a solid baseline-3 case — no new syntactic meaning added beyond the schema.

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?

Starts with the specific verb+resource+scope "Import a template into an existing project, adding its tasks, sections and comments to whatever is already there," making the merge semantics explicit. It distinguishes itself from sibling `export-project-template` and `add-projects` by clarifying this is for existing projects only.

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?

Gives explicit workflow guidance: "To start a new project from a template, create the project with add-projects first, then import into it" names the exact alternative tool and sequencing. The safety rule "only run it against a project the user named" provides a clear when-to-run criterion. Only minor gap is not naming a 'when not to use' beyond the new-project case.

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