Run Migration

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

With no annotations the description carries the full burden, and it does disclose valuable failure semantics: waves run in dependency order and a failed wave aborts the run by default because schema/auth issues repeat, with continue_on_error as an override. It still omits dry_run behavior (read-only vs actual mutation), what the source credentials do, and whether the operation is long-running or irreversible.

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 tight sentences, front-loaded with the core action and followed by the ordering and failure rules. Nothing is redundant, though the final sentence is slightly padded.

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?

The output schema exists so return values need not be described, and the failure/ordering semantics are well covered. But for an 8-parameter mutation tool with zero annotation coverage and zero schema descriptions, the description should at minimum explain dry_run and the credential parameters, which it does not.

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 0% across 8 parameters, so the description must compensate and largely does not. It explains continue_on_error and loosely implies entity_types ('one or all'), but leaves migration_id, dry_run, verify_tls, and the three source_* credential params completely uninterpreted.

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 and resource ('Run an ordered end-to-end migration') and scopes it to 'one or all planned entity types,' which separates it from sibling migrate_records and run_migration_wave. However it never names those siblings, so an agent must infer the boundary from context rather than being told.

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 only implied via 'planned entity types' (suggesting it follows create_migration_plan) and the continue_on_error note. There is no explicit when-to-use versus validate_migration, rollback_migration, or run_migration_wave, nor any stated prerequisites such as requiring a completed plan.

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