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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, so the mutation/safety profile is partly covered. The description adds a genuine behavioral constraint (never auto-decide recommendations; suggest then ask), which is useful context. It still omits mechanics such as what skipping does to data or the final state of the import, so it stays near baseline.

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?

Two short sentences, front-loaded with the core keep/skip action before the policy note. The second sentence restates the same defer-to-user idea twice ('never decide' / 'suggest, then ask'), a minor redundancy that keeps it short of 5.

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 mutation tool in a multi-step import workflow with no output schema, the description covers the core action and the human-in-the-loop intent. It does not clarify the resulting state, ordering relative to commit_import/review_import, or what happens to unaddressed entries, leaving meaningful gaps.

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 75% and keep/skip/rest are already documented. The description adds the key semantic distinction that keep/skip act by id while 'rest' acts on everything still unsorted at once, which clarifies how the two modes interact. import_id remains undocumented in both, keeping it from a 5.

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 states a clear verb pair (keep/skip) applied to a specific resource (entries in an import), and the title reinforces it. It distinguishes itself functionally from pipeline siblings like review_import and commit_import, though it does not name any sibling explicitly.

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?

Usage is implied through the import workflow and the instruction to defer decisions to the person. However, it never explains when to call this versus review_import or commit_import, nor what prerequisites (e.g. an existing started import) are needed. Guidance exists but is not routed against alternatives.

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