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

No annotations are provided, so the description carries the full burden. It discloses the interactive behavior (lists phases, returns flows/hint, expects a follow-up call) and the heuristic hint to classify the use case. However, it leaves ambiguity about whether the tool actually modifies the integration or is purely informational—the phrase 'Begin or change' suggests action but the described behavior (returning phases/plans) implies advisory. Permissions or side effects are not mentioned.

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 sentences, front-loaded with purpose, then a compact step-by-step usage pattern. No redundancy or filler. The structure is efficient and easy to follow.

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?

No output schema exists, so the description explains expected returns for each invocation mode: phases, flows with hint, and full plan. It also advises sequential execution. It does not cover error cases or prerequisites, but for an interactive guidance tool this is sufficiently complete to get an agent started.

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% with descriptions for each parameter, so the baseline is 3. The description adds sequential meaning beyond the schema: it explains that `phase` determines which flows are returned, `goal` is the flow id you classified, and how the parameters are used across calls. This relationship is not captured in the schema and helps the agent use the parameters correctly.

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 purpose: 'Begin or change an Alter integration.' It is clearly the entry point for starting or modifying an integration, and the description of phases/flows distinguishes it from siblings like list_phases or next_step. The verb and resource are explicit enough for an agent to understand the core function.

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?

Provides explicit multi-step guidance: first call with no args to list phases, then with `phase` to get flows and a heuristic hint, then with `goal` for the plan. Also advises sequential execution for multi-flow use cases. However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of a full when/when-not comparison.

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