agent-harness-construction

Use stable, explicit tool names with schema-first narrow inputs and deterministic output shapes. Avoid catch-all tools unless isolation is impossible, and match granularity to risk: micro-tools for high-risk operations, medium tools for common edit/read/search loops.

Every tool response should include a status field (success, warning, or error), a one-line summary, actionable next_actions, and artifacts such as file paths or IDs. This structure lets the agent plan its next step without guessing.

ReAct suits exploratory tasks with uncertain paths, while function-calling fits structured deterministic flows. A hybrid approach is recommended: ReAct for planning combined with typed tool execution for reliability.

Every error path should include a root cause hint, a safe retry instruction, and an explicit stop condition. This prevents agents from looping indefinitely or retrying operations that cannot succeed.

Track completion rate, retries per task, pass@1 and pass@3, and cost per successful task. These metrics reveal whether harness changes actually improve reliability rather than just shifting failure modes.

Avoid macro-tools for high-risk operations like deploys, migrations, or permission changes, where micro-tools give finer control. Macro-tools are only appropriate when round-trip overhead is the dominant cost.