Patterns for Agentic Tools: Your agents are only as good as your tools.

The Moment

Every few years, a new pattern language emerges that changes how we build software.

In 1994, the Gang of Four gave us Design Patterns. In 2003, Hohpe and Woolf gave us Enterprise Integration Patterns. Since then: Microservices Patterns, Cloud Patterns, and now Agent Patterns.

But there's a gap. Agents can chat and reason on their own - but they can't ‘act’ without tools. Standards like MCP have unlocked how agents discover and call tools. The protocol layer is solved. What's missing is the design layer: patterns for building tools that agents can actually use well. That's the missing layer.

What We Learned

We've built over 8000 tools across 100+ integrations - the largest catalog of agent-ready tools in production. Not API wrappers. Production-grade tools that handle the edge cases: rate limits, pagination, auth refresh, partial failures. 

Every mistake you can make: unclear descriptions, unhelpful errors, parameters that made sense to us but not to an LLM, we've made it. We learned that "working" isn't the same as "agent-usable." 

A tool can return the right data and still fail because the agent couldn't figure out when to call it.

After thousands of iterations, patterns emerged. We built internal checklists, review processes, and eventually a framework that let us ship quality tools consistently. Not theory - just what works when you're building tools that agents actually use.

We documented them. Now we're sharing them. Explore the full catalog at arcade.dev/patterns.

The Paradigm Shift

For two decades, we built integration around a simple model: middleware orchestrates, applications consume. ESBs routed messages. Workflow engines enforced sequence. The integration layer decided what happened, when, and in what order.

Agent tooling collapses that entire layer. There is no bus. There is no predetermined workflow. The agent decides which tool to call, interprets the parameters, handles the response, and figures out what to do next. The orchestration logic that lived in your middleware is now emergent, reconstructed by the agent on every invocation, with no guarantee it plays out the same way twice.

This isn't traditional integration with a new consumer. It's an entirely new type of consumer and the fundamentals have changed.

When an LLM selects which tool to call, interprets parameters, and decides what to do with errors, the design constraints are fundamentally different. The old patterns don't fit. We need new ones. 

So where do you start? With a way to classify what you're building.

Three Axes of Classification

Every tool exists somewhere in three dimensions. Understanding where helps you pick the right patterns.

Maturity is the vertical axis: how sophisticated your tool is. Atomic tools do one thing: get_user(id). Orchestrated tools coordinate many, managing state across calls. We'll dig deeper into this axis in the maturity model below.

Integration is what your tool connects to, APIs, databases, file systems, or system operations. Each carries different design constraints. Database tools need the Idempotent Operation pattern because agents retry on timeout and your tool must handle duplicate calls gracefully.

Access is how execution works. Synchronous tools are straightforward: call, wait, respond. But a report generation tool that blocks for 45 seconds will timeout or stall the agent. That's where the Async Job pattern comes in: the agent calls generate_report(), receives a job ID, and polls check_status(job_id) until complete.

Your coordinates across all three axes determine which patterns you need. A tool that is Composite × Database × Async has very different design requirements than one that is Atomic × API × Sync.

Cross-Cutting Concerns

Knowing where your tool sits on the three axes tells you which patterns to look at. But four concerns cut across every axis: agent experience, security boundaries, error-guided recovery, and tool composition. Get these wrong and it doesn't matter how well you've classified your tool.

Agent Experience

Design for the LLM, not the human. Tool descriptions, parameter names, and error messages should be optimized for agent comprehension.

The Parameter Coercion pattern is a good example: an agent might pass "2024-01-15", "January 15", or "yesterday",  your tool accepts all of them and normalizes internally.

Security Boundaries

Prompts express intent, code enforces rules. Never trust the agent to enforce security. Authorization and secrets must be handled server-side.

The Context Injection pattern passes user identity, permissions, and credentials through a server-side context object, never through the LLM.

Error-Guided Recovery

Errors should teach, not just fail. When things go wrong, provide actionable guidance. What should the agent try next? A raw 429 means nothing to an LLM. A response that says "rate limited, retry after 30 seconds or reduce batch size to 50" gives the agent a path forward.

Tool Composition

Tools should compose well together like Unix pipes, not like a chain of command. That means consistent response shapes so one tool's output feeds cleanly as another's input, batch support so agents don't loop one-at-a-time, and multiple abstraction levels so the agent picks the right granularity for the task.

The Landscape: 54 Patterns, 10 Categories

These four principles:  agent experience, security boundaries, error-guided recovery, and tool composition, thread through everything. They show up differently depending on the tool, but the questions they raise are universal: How will agents understand this? How do we keep it secure? What happens when it fails? How do tools fit together without directing each other?

We organized our answers into 54 patterns across 10 categories. Each category maps to one of those recurring questions:

Each pattern includes the problem it solves, when to apply it, implementation considerations, and code examples. 

The full catalog is at arcade.dev/patterns.

Now how do you actually put it to use?

Building Your First Tool

Where you start depends on two things: where your tool sits on the three axes, and what maturity level you're at today.

Classify Your Tool

Work through four questions: What type is this: Query, Command, or Discovery? What integration: API, Database, File System, or System? What access pattern: sync, async, streaming, or event-driven? And what maturity level: single operation or bundled workflow?

Find Your Level

Your position on the maturity axis tells you which patterns to start with. Don't over-engineer: start atomic, watch how agents actually use your tools, and level up when you see the signals in your traces.

The observable signals between levels are real things you'll find in your logs: high retry rates mean your tool needs better descriptions and error guidance. Repeated tool sequences mean it's time to bundle. Partial completions on multi-step operations mean you need transaction boundaries and compensation.

Join Us

These patterns exist because of the engineering discipline behind them. The Arcade engineering team, particularly Eric, Renato, and Francisco , authored thousands of tools and built the quality control processes that turned hard-won lessons into repeatable standards. 

This work is dedicated to them, to the broader tool engineering and MCP community, and to every team that's learned the hard way that "working" and "agent-usable" aren't the same thing.

The full set of patterns is at arcade.dev/patterns. Each pattern includes diagrams, code examples, and implementation considerations.

We're releasing these patterns openly because better tools benefit everyone. When the ecosystem builds better tools, agents get more capable. When agents get more capable, more people build with them. That's the future we want to help create.

What did we miss? What patterns have you discovered that aren't here? Where did we get it wrong? We'd love your feedback - send us a note, tell us what doesn't make sense.

This is a shared language. Help us make tools better.

Explore the full pattern catalog. 
All 54 patterns with examples, trade-offs, and implementation guidance: arcade.dev/patterns

Ready to build? 
Arcade gives you the runtime, the tools, and the auth layer to ship agents that actually work in production. Get started