Tool Integration & Function Calling
Tool Definition Patterns
5 min read
Modern AI assistants are only as capable as their tools. Understanding how production systems define tools in their system prompts reveals patterns for building powerful, safe tool ecosystems.
Tool Definition Structure
Production tools follow consistent patterns:
{
"name": "tool_name",
"description": "Clear explanation of what this tool does",
"parameters": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"param1": {
"type": "string",
"description": "What this parameter controls"
}
},
"required": ["param1"]
}
}
Claude Code's Tool Definitions
From Claude Code's system prompt (January 2026):
{
"name": "Read",
"description": "Reads a file from the local filesystem. You can access any file directly by using this tool. Assume this tool is able to read all files on the machine.",
"parameters": {
"properties": {
"file_path": {
"description": "The absolute path to the file to read",
"type": "string"
},
"offset": {
"description": "Line number to start reading from",
"type": "number"
},
"limit": {
"description": "Number of lines to read",
"type": "number"
}
},
"required": ["file_path"]
}
}
Key patterns:
- Clear description of capability
- Required vs optional parameters
- Type specifications
- Usage context
Tool Categories
Production systems organize tools by function:
1. File Operations
File Tools:
- Read: Access file contents
- Write: Create new files
- Edit: Modify existing files
- Glob: Pattern-based file search
- Grep: Content search
Usage rules:
- Use Read before Edit (always)
- Prefer Edit over Write for existing files
- Use Glob for file discovery
- Use Grep for content search
2. Execution Tools
Execution Tools:
- Bash: Run shell commands
- Task: Spawn sub-agents
- WebFetch: Retrieve web content
- WebSearch: Search the internet
Constraints:
- Bash has timeout limits
- Task agents have scoped permissions
- Web tools respect rate limits
3. Communication Tools
Communication Tools:
- AskUserQuestion: Get user input
- TodoWrite: Track task progress
- ExitPlanMode: Complete planning phase
Guidelines:
- Minimize user interruptions
- Use TodoWrite for complex tasks
- Clear question formatting
Tool Descriptions Best Practices
From real system prompts:
Be Specific About Capabilities
Bad:
"description": "Searches files"
Good:
"description": "Fast file pattern matching tool that works with any codebase size. Supports glob patterns like '**/*.js' or 'src/**/*.ts'. Returns matching file paths sorted by modification time."
Include Usage Guidelines
"description": "Executes a bash command with optional timeout.
Usage notes:
- Commands timeout after 120000ms by default
- Output truncated after 30000 characters
- Use for git, npm, docker operations
- NOT for file reading (use Read tool instead)"
Provide Examples
"description": "Edits files using exact string replacement.
Examples:
- Replace function name: old_string='function foo', new_string='function bar'
- Fix import: old_string='import x', new_string='import { x }'
The old_string must be unique in the file."
Parameter Design
Required vs Optional
{
"properties": {
"path": {
"description": "Required: Directory to search",
"type": "string"
},
"pattern": {
"description": "Required: Glob pattern to match",
"type": "string"
},
"depth": {
"description": "Optional: Max directory depth (default: unlimited)",
"type": "number"
}
},
"required": ["path", "pattern"]
}
Type Constraints
{
"timeout": {
"type": "number",
"minimum": 0,
"maximum": 600000,
"description": "Timeout in milliseconds (max 10 minutes)"
},
"output_mode": {
"type": "string",
"enum": ["content", "files_with_matches", "count"],
"description": "What to return from search"
}
}
Tool Discovery Patterns
How agents know which tools to use:
Category-Based Selection
Tool Selection Guidelines:
- File operations → Read, Write, Edit, Glob
- Code search → Grep, Glob
- System commands → Bash
- Research → WebSearch, WebFetch
- Complex tasks → Task (spawn agent)
NEVER use Bash for:
- File reading (use Read)
- File editing (use Edit)
- File search (use Glob/Grep)
Context-Based Routing
Context-Aware Tool Selection:
If searching for files by name:
→ Use Glob
If searching for content in files:
→ Use Grep
If exploring unknown codebase:
→ Use Task with Explore agent
If running build/test:
→ Use Bash
Tool Composition
Combining tools for complex operations:
Composition Pattern: Code Modification
1. Glob to find relevant files
2. Read to understand current code
3. Edit to make changes
4. Bash to run tests
5. Read to verify changes
Example flow:
- Glob("**/*.ts") → Find TypeScript files
- Grep("deprecated") → Find deprecated usage
- Read(file) → Understand context
- Edit(file, old, new) → Update code
- Bash("npm test") → Verify changes
Tool Permissions
Production systems control tool access:
Permission Levels:
ALLOWED (no approval needed):
- Read, Glob, Grep
- WebSearch, WebFetch
- Safe Bash commands (ls, git status)
REQUIRES_APPROVAL:
- Write, Edit
- Bash with side effects
- Task spawning
NEVER_ALLOWED:
- Destructive operations
- Credential access
- Network egress to unknown hosts
Cursor's Yolo Mode
Cursor allows bypassing approvals:
Yolo Mode Configuration:
When enabled:
- File writes proceed without confirmation
- Bash commands execute immediately
- Agent has higher autonomy
Risk mitigation:
- Git provides rollback
- Sandboxed environment
- User can interrupt
Anti-Patterns
What NOT to do in tool definitions:
Anti-Pattern 1: Vague descriptions
❌ "description": "Does stuff with files"
✓ "description": "Creates a new file at the specified path with given content"
Anti-Pattern 2: Missing constraints
❌ No max length, no timeout
✓ "maximum": 10000, "timeout": 60000
Anti-Pattern 3: Overlapping tools
❌ Multiple tools that do similar things
✓ Clear separation of concerns
Anti-Pattern 4: Hidden side effects
❌ Tool that reads AND modifies
✓ Separate Read and Edit tools
Key Insight: Well-designed tool definitions are the foundation of capable AI assistants. Clear descriptions, appropriate constraints, and logical categorization enable agents to select the right tool for each task while maintaining safety.
Next, we'll explore function calling syntax across different AI platforms. :::