Run Phase

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

The description discloses the main side effects: it records state and persists to pipeline-state.json and the audit log. This is sufficient given readOnlyHint=false and destructiveHint=false. It does not mention potential external network impact on the target, but openWorldHint=true suggests external actions are possible; the description is somewhat vague on that point.

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 description is concise, with no redundant words. It uses backticks for inline code, making it readable. Each sentence adds value: purpose, parameter clarifications, and persistence behavior. The structure is logical and easy to scan.

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?

The description covers essential context: what the tool does, how parameters behave, and what side effects occur. Since an output schema exists (per context signals), not describing return values is acceptable. The description also mentions the relationship to other tools (run_pipeline, pipeline_status), providing complete operational context.

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 description provides meaningful explanations for all three parameters: phase is defined as one of the pipeline phases, target defaults to the engagement's first seed, and extra_json is an optional JSON object of extra kwargs. This goes far beyond the schema's type-only definitions, achieving high coverage.

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 tool's purpose: 'Run a single phase against a target and record its state.' It distinguishes itself from run_pipeline by specifying it runs a single phase, and from specific scanner tools (e.g., jaeles_scan) by being a generic phase runner. The verb 'run' and resource 'phase' are unambiguous.

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 implies usage when a single pipeline phase is needed, and explicitly notes the persistence so that run_pipeline and pipeline_status reflect the result, signaling how it fits into the ecosystem. However, it does not directly contrast with run_pipeline or other phase-specific tools, leaving some inference needed.

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