advance_phase

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

With no annotations provided, the description must carry the burden of disclosing side effects. It only states that the tool advances to the next phase and returns a message and guidance. It does not mention whether the action is reversible, whether it validates completion of the current phase, or what happens at the final phase. This is insufficient for a state-changing tool.

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 first two sentences are near-identical ('Advance to the next phase...' and 'This tool advances to the next phase...'), showing clear redundancy. The Args/Returns structure is logical, but the duplication wastes words.

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 tool in a phased workflow, the description lacks context about the phase progression, prerequisites, or how it fits with siblings like follow_threat_modeling_plan or get_current_phase_status. The output schema covers return values, but the description fails to provide sufficient usage context for correct invocation.

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?

The schema has zero parameters, so the baseline is 4. However, the description lists an 'Args: ctx' entry despite the schema having no properties, which could mislead an agent into thinking there is a parameter. Since there are no actual parameters to explain, the description adds no meaningful semantic value and the misleading note reduces the score.

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 clearly states the action ('Advance to the next phase') and the resource ('threat modeling process'), making it distinct from sibling tools like get_current_phase_status or follow_threat_modeling_plan. The repetition in the second sentence is redundant but does not obscure the purpose.

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?

The description gives no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, such as completing the current phase or checking current status. There are no exclusions or alternative tool references, leaving the agent to infer usage purely from the name.

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