| name | agentic-tooluse |
| description | Tool use pattern for agents requiring external world interaction. Foundation layer for most real-world agentic tasks with design principles for effective tool contracts. |
Agentic Tool Use Pattern
[!TIP]
TL;DR: Tool use is the foundation layer for most agentic patterns. If a task requires external data, state, or actions, tools are required. Tool use sits UNDER the reasoning layer, not alongside it.
Key Principle: "A ReAct agent with tools is still ReAct, and a planning agent with tools is still planning."
Pattern Overview
Tool use enables agents to interact with the external world:
- Query databases
- Call APIs
- Retrieve documents
- Execute code
- Modify system state
┌─────────────────────────────────────────┐
│ AGENTIC SYSTEM LAYERS │
│ │
│ ┌─────────────────────────────────────┐│
│ │ REASONING LAYER (ReAct/Planning) ││
│ │ "What should I do next?" ││
│ └─────────────────────────────────────┘│
│ │ │
│ ┌─────────────────┴──────────────────┐ │
│ │ TOOL LAYER (Foundation) │ │
│ │ [Database] [API] [Code] [Search] │ │
│ └─────────────────────────────────────┘│
└─────────────────────────────────────────┘
Critical insight: Tools add capability without changing the reasoning pattern. This means:
- A ReAct agent with tools is still ReAct
- A planning agent with tools is still planning
Decision Gate
When to use: Apply this pattern when:
- Question 2b = YES: Task requires tool access or external information
The answer is almost always YES. An agent that can only reason over training data handles a narrow slice of real-world tasks.
Effective Tool Design
Effective tools have three components:
1. Clear Input Specification
| Good Input | Bad Input |
|---|
user_id: string (required) | query: something |
date_range: {start, end} | filter: whatever |
limit: integer (default=10, max=100) | count: limitish |
2. Predictable Output Format
{
"status": "success" | "error",
"data": [...],
"meta": { "count": N, "timestamp": "..." }
}
3. Defined Failure Modes
| Failure Mode | How to Handle |
|---|
| API timeout | Retry with exponential backoff, then fail gracefully |
| Invalid input | Return clear error message, don't crash |
| Rate limit | Implement backoff, notify agent |
| Partial failure | Return what's available + status |
Tool Categories
Data Retrieval Tools
| Tool | Purpose | Example |
|---|
| Database query | Structured data access | query_sql(query) |
| Vector search | Semantic similarity | search_similar(text, k) |
| Document retrieval | Unstructured text | get_documents(query) |
| Web search | Real-time information | web_search(query) |
| API call | External services | call_api(endpoint, params) |
Action Tools
| Tool | Purpose | Example |
|---|
| Code execution | Run generated code | execute(code, lang) |
| File operations | Read/write files | write_file(path, content) |
| Message send | External notifications | send_email(to, body) |
| System command | OS-level operations | run_shell(cmd) |
Computation Tools
| Tool | Purpose | Example |
|---|
| Calculator | Precise math | calculate(expr) |
| Formatter | Data transformation | format_table(data) |
| Aggregator | Summary statistics | summarize(data, metrics) |
Tool Contract Template
## Tool: [tool_name]
**Purpose**: [One sentence description]
**Input**:
- [param1]: [type] (required/optional) - [description]
- [param2]: [type] (required/optional) - [description]
**Output**:
- status: "success" | "error"
- data: [type] (on success)
- error: { code, message } (on error)
**Failure Modes**:
1. [Condition] → [Handling]
2. [Condition] → [Handling]
**Example**:
Input: { param1: "value", param2: 42 }
Output: { status: "success", data: [...] }
Tool Use vs. Reasoning Patterns
Tool use is orthogonal to reasoning patterns:
| Reasoning Pattern | + Tool Use | = Same Pattern |
|---|
| ReAct | + Tools | ReAct with tools |
| Planning | + Tools | Planning with tools |
| Reflection | + Tools | Reflection with tools |
| Multi-Agent | + Tools | Multi-Agent with tools |
Therefore: When designing, separate:
- What tools are available (tool layer)
- How reasoning happens (reasoning pattern layer)
Failure Modes
Excessive Tool Calls
| Signal | Cause | Fix |
|---|
| Tool calls > 50 in single task | Agent doesn't know when to stop | Add max tool calls limit |
| Same tool called repeatedly | No state tracking | Add output caching |
| Tool calls without progress | Wrong tool for task | Evaluate tool necessity |
Tool Contract Violations
| Signal | Cause | Fix |
|---|
| Unexpected output format | Contract not followed | Add validation layer |
| Type errors | Input specification unclear | Tighten specifications |
AGEM Integration
Native Tools
run_agem_cycle — Reasoning phase that invokes toolsdetect_gaps — Identify missing tools causing failuresget_soc_metrics — Monitor tool efficiency
Tool Registration
When building an agent with tools:
- Define tool contracts (input/output/failures)
- Register tools in agent context
- Monitor tool call patterns
- Optimize frequently used tools
Workflow Template
1. REQUIREMENTS:
a. Identify external data needed
b. Identify actions to perform
c. List available tools
2. TOOL DESIGN:
a. Define contracts for each tool
b. Implement error handling
c. Document failure modes
3. INTEGRATION:
a. Add tools to agent context
b. Set tool call limits
c. Add progress tracking
4. MONITORING:
a. Track tool call efficiency
b. Identify underused/overused tools
c. Optimize based on patterns
Quick-Start Template
## Tool Use Task Definition
**Task**: [What needs external interaction]
**External Requirements**:
- Data needed: [databases/APIs/search]
- Actions needed: [code/file/system]
### Available Tools:
┌────────────────┬──────────────┬────────────────────┐
│ Tool Name │ Category │ Purpose │
├────────────────┼──────────────┼────────────────────┤
│ [tool_1] │ [retrieval/ │ [description] │
│ │ action/ │ │
│ │ compute] │ │
└────────────────┴──────────────┴────────────────────┘
### Max Tool Calls: [N per task]
### Failure Handling:
- API timeout → [retry/backoff/fail]
- Invalid input → [validate/reject]
- Rate limit → [backoff/wait]
See Also
