Tools and actions are the capability layer through which an agent operates beyond its own reasoning. They sit alongside persona, reasoning and planning, knowledge and memory, and evaluation and feedback as one of five stacked agent layers. section 11.1 section 1.5
Treat a tool as a narrow, inspectable operation rather than a vague bundle of abilities. Clear names, docstrings, and typed parameters help the model select and call tools correctly, while structured outputs reduce brittle parsing. section 11.5 section 11.5
Build the layer with these practical rules:
- Keep each tool focused on a single responsibility so accuracy, testing, and cost remain manageable. section 11.5
- Describe inputs with crisp names, docstrings, and types; the resulting schema teaches the model how to use the tool. section 11.5
- Control invocation with tool_choice and parallel tool-call settings, and stop when one sufficient call completes the task. section 11.5
- Expect timeouts and other failures; add retries, graceful error payloads, and fallbacks rather than assuming every action succeeds. section 11.5
- Prefer prebuilt or hosted tools when useful, but select them deliberately instead of adding capabilities without a clear role. section 11.5
A reliable action boundary
A narrowly scoped action exposes typed parameters and returns a structured result. The agent can then choose whether to call it, handle an error payload, retry a transient failure, or fall back when the action is unavailable. section 11.5
Figure 11.1 The five agent layers. For each layer, the internal boxes represent the patterns that can help improve development of that layer.
Use the five-layer diagram to locate tools and actions within the wider agent design and compare its responsibilities with the other layers. section 11.1
