Patterns for Agentic Tools

Design patterns for building quality tools for AI agents.

// guiding_principle
"Your agents are only as good as your tools."

Tools are how agents interact with the world. When tools are well-designed, orchestration stays simple and agents behave predictably. When tools are sloppy, the orchestration layer has to compensate - and it never does it well. These patterns capture what works, so you don't have to figure it out the hard way.

Where Tools Fit

Tools are the interface between agents and the external world. Click a category to filter.

Agents
Tool Patterns (52)
Systems APIs · Databases · Services · File Systems · Enterprise Apps

Tool

(4)
Tool The atomic callable unit that an agent can invoke to perform work.
→
Query Tool A read-only tool that retrieves data without side effects.
→
Command Tool A tool that performs actions with side effects.
→
Discovery Tool A tool that reveals available operations, schema, or capabilities.
→

Tool Interface

(7)
Tool Description Write descriptions optimized for LLM comprehension, not human reading.
→
Constrained Input Use enums, ranges, and validation to limit inputs to valid values.
→
Smart Defaults Reduce required parameters by providing sensible defaults.
→
Natural Identifier Accept human-friendly identifiers and resolve them internally.
→
Mutual Exclusivity Enforce 'exactly one of X or Y' parameter constraints.
→
Performance Hint Guide agents toward efficient usage patterns.
→
Parameter Coercion Accept flexible input formats and normalize internally.
→

Tool Discovery

(5)
Tool Registry Provide a catalog of available tools with their capabilities.
→
Schema Explorer Progressively reveal structure through layered discovery.
→
Dependency Hint Embed 'call X before Y' guidance in tool descriptions.
→
Capability Matching Find tools by intent or capability, not just name.
→
Health Check Verify tool availability before relying on it.
→

Tool Composition

(6)
Abstraction Ladder Provide tools at multiple levels of granularity for the same capability.
→
Task Bundle Combine multiple operations into a single tool.
→
Batch Operation Process multiple items in a single tool call.
→
Operation Mode Provide different modes for different access patterns.
→
Tool Chain Explicitly define sequences of tool calls for complex workflows.
→
Scatter-Gather Tool Fan out to multiple sources, then combine results.
→

Tool Execution

(6)
Synchronous Execution Immediate request-response execution.
→
Async Job Handle long-running operations with job IDs and polling.
→
Idempotent Operation Make operations safe to retry with identical results.
→
Transactional Boundary Ensure all-or-nothing execution for multi-step operations.
→
Compensation Handler Undo completed steps when a multi-step operation fails.
→
Timeout Boundary Define maximum execution time with graceful termination.
→

Tool Output

(6)
Response Shaper Transform raw API responses into agent-friendly formats.
→
Token-Efficient Response Minimize response size while preserving essential information.
→
Paginated Result Handle large result sets with cursor-based pagination.
→
Progressive Detail Return summary by default, full detail on request.
→
GUI URL Include links to view or edit results in a web interface.
→
Partial Success Report mixed success/failure results for batch operations.
→

Tool Context

(4)
Identity Anchor Establish user identity and context at the start of a session.
→
Resource Reference Point to external data by URI instead of embedding it.
→
Context Injection Automatically inject relevant context the agent didn't request.
→
Context Boundary Define the scope or boundaries of tool operations.
→

Tool Resilience

(6)
Recovery Guide Provide actionable error messages that tell agents how to fix the problem.
→
Error Classification Distinguish between retryable and permanent failures.
→
Confirmation Request Request clarification when input is ambiguous.
→
Fuzzy Match Threshold Auto-accept high-confidence matches, confirm uncertain ones.
→
Graceful Degradation Return partial results when full operation isn't possible.
→
Fallback Tool Provide alternative tools when the primary is unavailable.
→

Tool Security

(4)
Secret Injection Inject credentials at runtime, never passing them through the LLM.
→
Permission Gate Enforce access control in code, not prompts.
→
Scope Declaration Declare required OAuth scopes per tool.
→
Audit Trail Log all tool invocations for security and debugging.
→

Compositional

(4)
Tool Gateway Provide a unified interface to multiple tool backends.
→
Tool Adapter Wrap legacy APIs as agent-friendly tools.
→
Canonical Tool Model Use standard data models across the tool ecosystem.
→
Tool Versioning Support multiple tool versions coexisting.
→