Plan a migration to DeepLinkNow

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the output is a plan plus a code diff, scope is scoped to a single platform, and attribution migration is explicitly out of scope.

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?

A single front-loaded sentence with the deliverable ('plan and code diff') first and the step breakdown trailing as a compact list; nothing is wasted. It is dense but readable, with only mild fragmentation from the colon-and-comma step enumeration.

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?

With no output schema, the description must convey the return shape, and it does ('plan and code diff'). It also states the vendor scope and the attribution exclusion. The one soft ambiguity is that the listed steps ('replace the code and verify') could read as actions the tool performs, though readOnlyHint=true resolves that.

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 100% and both parameters are enums with descriptions, so the schema carries the semantics and 3 is the baseline. The description reinforces that 'platform' selects the variant the code diff targets and lists the accepted sources, but adds no format or behavior detail the schema lacks.

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 specific resource and deliverable ('a concrete plan and code diff' for moving deep linking to DeepLinkNow) and enumerates the four source vendors it accepts, so the agent knows exactly what it produces. The only weak spot is sibling differentiation: it says the plan includes 'set up DeepLinkNow', which is close enough to the sibling get_setup_guide that a routing note would have helped.

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 context is implied rather than stated: the source enum plus 'for one platform' tells the agent this applies only to apps currently on one of the four named vendors, and only one platform per call. There is no explicit when-to-use vs get_setup_guide/search_docs guidance and no stated prerequisites.

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