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, macro-tools when round-trip overhead dominates.

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 parsing opaque output.

ReAct works best for exploratory tasks with uncertain paths, while function-calling suits 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 unsafe operations without bounds.

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 adding tools when they overlap semantically with existing ones, since overlapping action spaces confuse agent planning. Also avoid macro-tools unless round-trip overhead is the dominant cost, and keep large guidance in on-demand skills rather than the system prompt.