Start an autonomous build loop for a goal. Returns loop_id and the next instruction (shrink, edit, check, test, tick). The model still writes code; Hexum gates each turn.
| Name | Required | Description | Default |
|---|---|---|---|
| goal | Yes | What the loop should accomplish. | |
| files | No | ||
| max_turns | No | Stop after N ticks. Default 12, max 24. | |
| test_command | No | Advisory command shown in instructions (e.g. cargo test). |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses a key trait (the model still writes code; Hexum gates each turn) and the return of a loop_id. However, it doesn't disclose side effects, idempotency, or what happens if called multiple times, leaving significant behavioral gaps.
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?
Two sentences with zero waste. The action is front-loaded, and the behavioral note is concise and relevant.
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 with 4 parameters, no output schema, and no annotations, the description is sparse. It doesn't explain what 'goal' should contain, what 'files' are for, or what 'tick' means. The agent would have to infer from sibling tool names and the context, which is insufficient 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 description adds no parameter information. The required 'goal' parameter lacks a schema description, and 'files' is also undocumented; the description doesn't clarify either. With schema coverage at 75%, the description could compensate but does not.
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 (start an autonomous build loop) and the resource (a goal), and mentions the return values (loop_id and next instruction). It is distinct from sibling loop tools, though it doesn't explicitly say 'use this to start, not to continue.'
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 the tool is for starting a loop but provides no explicit when-to-use vs alternatives, no exclusions, and no prerequisites. It doesn't mention that subsequent steps should use hexum_loop_tick or that hexum_loop_abort would stop it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.