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 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—ReAct planning with typed tool execution—is recommended for most production agents.

Every error path should include a root cause hint, a safe retry instruction, and an explicit stop condition. This prevents infinite retry loops and gives the agent enough context to recover or halt cleanly.

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 unless round-trip overhead is the dominant cost. High-risk operations like deploys, migrations, and permission changes should use micro-tools so each step can be validated and recovered independently.