fow_interaction

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

Annotations already declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, so mutation risk and external reach are known. The description adds genuine context beyond that in the Effects line ('Persists conversation context, lenses and continuations', external providers 'may be consulted', and 'selecting a surface does not authorize its work'), but it never maps destructive behavior to specific routes (clear, clear_project) or states auth/permission needs, so it only partially fills the gap.

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 text is front-loaded with purpose and then cleanly sectioned into Route, Prerequisites, Effects, and an 'Exact help' pointer, making it easy to scan. It is fairly dense with neologisms and repeats the route list already present in the operation enum, but every section is functionally purposeful.

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?

For a 12-route multiplexer this is thin: the description lists operation names but never explains what distinguishes select from switch from frame from resolve, which is exactly what an agent needs to choose a route. Output values need not be explained since an output schema exists, and the pointer to fow_capabilities partially mitigates the gap, but it forces a second call to become actionable.

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%, so the schema already documents all 16 parameters thoroughly, including which routes each applies to. The description adds only the prerequisite that interaction_session_ref and selection intent must be supplied, so the baseline 3 for a fully-documented schema is appropriate.

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 names a concrete set of verbs (connect, discover, select) and a resource (the lifecycle project/work surface) and enumerates the 12 routes, which helps an agent see the multiplexer's scope. However, it is wrapped in invented jargon ('durable lifecycle project', 'bounded work surface', 'issued choices and frame') and never distinguishes this tool from siblings like fow_what_next, fow_goal, or fow_capabilities, so an agent cannot easily tell when this is the right entry point.

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?

It gives a real prerequisite ('Supply the host's stable interaction_session_ref and explicit selection intent') and tells the agent to pick a route via the operation selector, plus points to fow_capabilities for exact per-operation help. But it offers no when-to-use vs when-not-to-use guidance and names no alternative sibling tool, leaving route selection to inference.

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