design_next_action

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

With no annotations, the description carries the full burden and does so well: it discloses the bounded-retry policy and escalation to 'blocked', the gate-evaluation behavior (a stage logged ok but failing its gate returns 'retry' with failing numbers in 'guidance'), and the edge case that a stage logged with no numbers is taken as logged. That is exactly the non-obvious behavior an agent needs to avoid misinterpreting a 'retry' response.

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-loaded with the core decision, then the loop protocol, then the return contract, then gate semantics — a sensible escalation of detail. It runs a bit long and partly restates the output schema, but each paragraph adds a distinct operational fact.

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?

An output schema exists, so the return-value enumeration is supplementary rather than required; the real gaps are the undocumented session_id and the absence of any statement about failure when no session exists or how the tool resolves an implicit active session. Otherwise complete for a stateful pipeline-driver tool with no annotations.

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% and the single parameter 'session_id' (with an empty-string default) is never mentioned in the description. The phrase 'reads the session journal' hints that the tool is session-scoped, but nothing explains what session_id means, whether an empty value resolves to the active session, or what happens if it is wrong.

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 verb and resource — 'decide the single next action for an autonomous design run' — and makes the mechanism explicit: it reads the session journal and computes the next 13-stage pipeline step server-side. This clearly separates it from siblings like design_session_status (inspection) or design_autonomy_guide (reference material).

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?

Gives an explicit operating protocol: loop 'call design_next_action -> do what it says -> design_session_log the result' until status is complete or blocked, which tells the agent both when to call and when to stop. It never names a competing tool or states when *not* to use this one, so it stops short of full alternative routing.

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