migration_get_plan

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

Annotations include readOnlyHint=true, and the description reinforces this by explicitly stating 'Resume is a read and never a re-run of prior steps.' This adds critical context beyond the annotation, clarifying a potential misunderstanding about the 'resume' concept. The description also discloses the filter-priority behavior (explicit filter wins over saved view), which is behavioral context not in the schema. No contradiction.

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 a single paragraph covering all key points: what is read, the savedViewId behavior, filter override, and the resume caveat. It is front-loaded with the main purpose. Slightly verbose in listing the six-phase journey and nextAction, but each item adds clarity. No unnecessary fluff, though it could be tightened.

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?

Given the tool reads a complex plan with many components, the description covers the main return elements and key behaviors (savedViewId, filter override, resume semantics). There is no output schema, so the description carries full weight for return values; it lists the key items. It could mention whether the response includes step-level details like status codes or error handling, but for a read tool, this is adequate. It also doesn't discuss pagination or large plan handling, but that's minor.

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%, so the description must compensate. The description clarifies the semantics of savedViewId (filter over the step list) and mentions dataClass/state as filters, but it doesn't detail the exact format or meaning of each parameter. For required workspaceId and planId, it's clear they identify the plan. However, it omits how state and dataClass values should be formatted or what they represent beyond being filters. With five parameters and zero schema help, this is a moderate gap, but the description does add value.

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 clearly states the tool reads a migration plan and lists the specific components it returns (steps, six-phase journey, nextAction, resume answer, primary action). It distinguishes itself from sibling tools like migration_list_plans and migration_check_step by focusing on a single plan's full detail. The verb 'Read a plan' is specific and unambiguous.

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 implies this is the read-only tool for a single plan, and contrasts with migration_list_plans (listing) and migration_rollback_step (acting). It explains the savedViewId behavior and the filter override rule, giving clear context. However, it doesn't explicitly state when to use an alternative like migration_get_check or migration_readiness, though sibling names suggest those are for checks and readiness.

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