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 get well-designed tools every time.

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.
→