choose_data_import_method

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

Goes well beyond the annotations by disclosing important behavior: if the gate closed in the meantime, the call returns ok when the method matches and HTTP 409 when it differs; the choice cannot be changed; and the agent should re-fetch the migration instead of retrying. This is valuable runtime behavior not inferable from readOnlyHint/destructiveHint alone.

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?

Front-loaded with purpose and trigger, then structured around numbered options and a clear prohibition. The longer second half covers conflict behavior, which is essential context. Every sentence earns its place and there is no filler or restating of the name.

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?

Covers the trigger, the user-interaction requirement, the alternative auto-selection path, the exact pendingAction condition, and the closed-gate conflict behavior. Together with the output schema and 100% parameter coverage, nothing needed to call this tool correctly is missing.

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 100% and the description adds meaning to the 'method' parameter by explaining what 'automated' and 'manual' actually entail. It also clarifies that jobId is the MANUAL_CHOOSE_DATA_IMPORT_METHOD job ID. Only migrationId leans on the schema, which is acceptable given full coverage.

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?

Clearly states the specific action ('Choose how to import data in Phase 3') and the exact trigger condition (MANUAL_CHOOSE_DATA_IMPORT_METHOD job READY with pendingAction.type CHOOSE_DATA_IMPORT_METHOD). This also differentiates it from siblings like choose_backend_switchover and choose_frontend_deploy by tying it to Phase 3 and the import gate.

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?

Very explicit: it must be called only when the MANUAL_CHOOSE_DATA_IMPORT_METHOD job is READY, and only when pendingAction.type is CHOOSE_DATA_IMPORT_METHOD. It also states when NOT to call it (when PROBE_SOURCE already deployed and verified, Staticbot auto-selects automated), and requires asking the user before choosing. No ambiguity remains.

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