Query Tool | Patterns for Agentic Tools

arcade.dev/patterns

Context

Building tools that fetch information.

Problem

Agents need to access data in order to make decisions, reason about a problem, and plan actions.

Solution

A Query Tool:
- Interacts with external systems: retrieves data from external systems (database, API, etc.)
- Never modifies state: guarantees idempotency by design
- Returns data: Structured response
- Cacheable: Results can be cached

Examples

Python

@tool(read_only=True)
def get_user_profile(user_id: str) -> UserProfile:
    """Retrieve user profile. Safe to retry."""
    return db.users.find_one(user_id)

TypeScript

const getUserProfile = tool({
  name: "get_user_profile",
  readOnly: true,  // Hint: no side effects
  execute: async ({ userId }) => db.users.findOne(userId)
});

Considerations

Mark read-only tools explicitly for agent optimization
Query tools can be parallelized safely
Consider caching for expensive queries

Related Patterns

More in Tool

Tool

The atomic callable unit that an agent can invoke to perform work.

Command Tool

A tool that performs actions with side effects.

Discovery Tool

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

LLM-Optimized View

# Query Tool

A read-only tool that retrieves data without side effects.

## Category
Tool

## Context
Building tools that fetch information.

## Problem
Agents need to access data in order to make decisions, reason about a problem, and plan actions.

## Solution
A Query Tool:
- **Interacts with external systems**: retrieves data from external systems (database, API, etc.)
- **Never modifies state**: guarantees idempotency by design
- **Returns data**: Structured response
- **Cacheable**: Results can be cached

## Example (Python)
```python
@tool(read_only=True)
def get_user_profile(user_id: str) -> UserProfile:
    """Retrieve user profile. Safe to retry."""
    return db.users.find_one(user_id)
```
## Example (TypeScript)
```typescript
const getUserProfile = tool({
  name: "get_user_profile",
  readOnly: true,  // Hint: no side effects
  execute: async ({ userId }) => db.users.findOne(userId)
});
```

## Considerations
- Mark read-only tools explicitly for agent optimization
- Query tools can be parallelized safely
- Consider caching for expensive queries

## Related Patterns
- tool
- command-tool
- idempotent-operation

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