FDE Foundations · Module 8: Agents & Tools
Tool Contracts for Agents
An agent is only as reliable as its tools. Each tool is a contract: typed inputs, typed outputs, structured errors, and a description that says when to use it and when not to.
11 min reading
Objectives
- Design tools as explicit contracts with schemas
- Return structured errors the agent can act on
- Keep the tool surface small and purposeful
Tools are APIs with a reader who guesses
The model chooses tools from descriptions and schemas. Write those descriptions like API docs for a smart new hire: purpose, when to use, when not to use, input fields with meanings and examples, output shape, and error meanings. Ambiguity in the description becomes randomness in the loop.
Errors the agent can use
Return structured errors with codes and retry hints ("rate_limited, retry_after 30"), not prose. The agent should be able to branch on the code: retry, ask the user, or give up cleanly. Log every call and result; the transcript is your debugging surface.
Small surface, big wins
Five well-designed tools beat twenty overlapping ones: every extra tool is another chance to choose wrong. Merge near-duplicates, split tools that do two things, and make destructive operations separate tools with extra friction (confirmation arguments, narrower permissions) rather than flags on general ones.
Test tools without a model
Because tools are contracts, you can test them independently: schema validation, error paths, idempotency. When agent behavior misbehaves in production, the tool test suite tells you whether the contract or the planning failed, which halves debugging time.
Quick check
An optional 2-3 question self-check. Answers never leave your device, are not stored, and never count toward any assessment.
Exercise
Write tool contracts for a fictional refunds agent: three tools (lookup order, check policy, issue refund) with input and output fields, two error codes each, and one-line usage guidance.
Pass criteria
Three tools with typed fields, structured errors with retry hints, destructive refund tool separated with a confirmation argument, and usage guidance distinguishing overlapping tools.