Command Tool | Patterns for Agentic Tools

arcade.dev/patterns

Context

Building tools that modify state or trigger actions.

Problem

Agents need to understand which tools have consequences and require careful invocation.

Solution

A Command Tool:
- Modifies state: Creates, updates, or deletes
- Has side effects: Triggers external actions
- May not be idempotent: Repeat calls may produce different results (e.g. creating a database entry twice)
- Requires confirmation: For destructive operations

Examples

Python

@tool(destructive=True)
def delete_user(user_id: str) -> DeleteResult:
    """Permanently delete a user. Irreversible."""
    return db.users.delete(user_id)

TypeScript

const deleteUser = tool({
  name: "delete_user",
  destructive: true,  // Hint: has consequences
  execute: async ({ userId }) => db.users.delete(userId)
});

Considerations

Document irreversible operations clearly
Consider requiring confirmation for destructive actions
Make commands idempotent where possible

Related Patterns

More in Tool

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.

Discovery Tool

A tool that reveals available operations, schema, or capabilities.

LLM-Optimized View

# Command Tool

A tool that performs actions with side effects.

## Category
Tool

## Context
Building tools that modify state or trigger actions.

## Problem
Agents need to understand which tools have consequences and require careful invocation.

## Solution
A Command Tool:
- **Modifies state**: Creates, updates, or deletes
- **Has side effects**: Triggers external actions
- **May not be idempotent**: Repeat calls may produce different results (e.g. creating a database entry twice)
- **Requires confirmation**: For destructive operations

## Example (Python)
```python
@tool(destructive=True)
def delete_user(user_id: str) -> DeleteResult:
    """Permanently delete a user. Irreversible."""
    return db.users.delete(user_id)
```
## Example (TypeScript)
```typescript
const deleteUser = tool({
  name: "delete_user",
  destructive: true,  // Hint: has consequences
  execute: async ({ userId }) => db.users.delete(userId)
});
```

## Considerations
- Document irreversible operations clearly
- Consider requiring confirmation for destructive actions
- Make commands idempotent where possible

## Related Patterns
- tool
- query-tool
- idempotent-operation
- compensation-handler

---
Source: https://arcade.dev/patterns/command-tool