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 choose granularity based on 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 is recommended: ReAct for planning combined with typed tool execution for reliability.

For every error path, include a root cause hint, a safe retry instruction, and an explicit stop condition. Error-only output without next steps is an anti-pattern that causes agents to loop or stall.

Track completion rate, retries per task, pass@1 and pass@3, and cost per successful task. These metrics reveal whether tool design and recovery contracts are actually improving convergence.

Use micro-tools for high-risk operations like deploys, migrations, and permission changes. Use macro-tools only when round-trip overhead is the dominant cost; medium tools cover common edit, read, and search loops.