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

Annotations provide idempotentHint=true and destructiveHint=false, and the description meaningfully extends this by stating that re-runs skip already-imported keys and report householdId, imports never overwrite, and dryRun writes NOTHING. It also discloses the 200-household limit and deterministic template execution. This goes well beyond what annotations alone convey.

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 dense and front-loaded: the dryRun-first workflow, batch limit, and two input shapes appear before lower-level detail. Every sentence contributes necessary operational or behavioral information, and the reference to docs/data-migration.md avoids inlining the full template spec. There is no 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 bulk-import tool with 5 parameters, nested objects, and no output schema, the description is remarkably complete. It covers the write behavior, idempotency, never-overwrite guarantee, batch limit, two input forms, template determinism, and what reports are produced. The only slight gap is the exact response envelope, but the reference to per-row per-field reports and reported householdIds gives the agent enough to navigate.

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?

The schema covers 100% of parameters, so the baseline is 3. The description adds substantial semantic meaning beyond the schema: dryRun is a validation pass with no writes, importKey is a stable caller-provided id used for idempotency, and the template+records path executes a declarative mapping deterministically. It does not add much detail for api_key, but the schema already describes it.

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 opens with a specific verb and resource: 'Migrate a book (WS3.5): import up to 200 households in one call.' It clearly distinguishes this as a bulk migration operation versus the single-household sibling tools, and it names the two supported input shapes. The purpose is unambiguous and not a restatement of the tool name.

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 description gives explicit workflow guidance: use dryRun first to validate and write nothing, iterate until the report is clean, then run for real. It also explains the choice between direct households[] and template + records. It does not explicitly contrast with sibling create_household, but the bulk-migration context and dryRun-first workflow make the intended usage clear.

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