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

Annotations already flag destructive=true, non-idempotent, open-world; the description adds the async-processing nature, the PREVIEW-state precondition, and the required `imports:write` API-key scope. It stops short of saying what happens to data after the import runs or whether confirmed mappings can be changed later, which matters for a destructive operation.

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?

Three sentences, all load-bearing: purpose, precondition, and parameter/scope detail, with the action front-loaded.

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?

There is no output schema, and the description does not say what the call returns (job id, new status) or how to track progress. For a destructive async-starting tool that is a real gap, though annotations cover the safety profile.

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 only 50%, and the description compensates well for `columnMappings` by giving an example value for targetField and the allowed targetType values ('builtin' or 'custom_field'). However, `jobIdentifier` has no description in either the schema or the description beyond context.

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 the specific verb (confirm column mappings), the resource (a previewed CSV import job), and the consequence (starts async import processing), which cleanly separates it from pm_get_import_job and pm_list_import_jobs.

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 a clear precondition: it must be called AFTER a non-MCP client uploads via /csv/preview and produces a job in PREVIEW status. It does not name the MCP-side sibling (pm_get_import_job) as the way to verify that state, so routing is slightly incomplete.

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