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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and the description reinforces 'Read-only state machine; executes nothing,' adding the key behavioral fact that it never invents missing inputs and reports blocked_by. It discloses order rules applied (map before compute, etc.). It does not detail pagination or exactly how next_args are drafted, but annotations plus text cover the salient behavior.

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-loads purpose well, but the middle is a dense run-on string of enumerated values and flag names that is hard to parse. It earns most of its place but could be structured with clearer separation of state vs inputs vs return fields.

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's complexity (state-machine advisor) and that an output schema exists, the description still usefully explains return fields (next_tool, next_args, missing_inputs, blocked_by, remaining_steps) and the order rules. Adequate for an agent to call and interpret it, though the intent_category selection logic could be fuller.

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. It does: enumerates the meaning of state keys (viewer_connected, point_layer, part_layer, tal_present, analysis_fresh, selection/realign flags) and inputs values, and explains missing_inputs. Only gap is that intent_category's enum semantics are listed but not deeply explained per category.

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 function: returns the next tool call for a multi-step workflow given workflow state. Clearly distinguishes itself as a read-only state machine advisor vs the many action siblings like account_build, realign, schedule_visits. Could be slightly sharper on how it relates to discover_intent and get_guidance.

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?

Explicitly says 'Calling it after each step with the updated state walks the whole workflow,' telling the agent exactly when and how to use it. It also enumerates the intent_category values that select the workflow, giving concrete routing conditions.

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