Tools reference

This reference guide provides detailed information about all tools available in the Recall Agent Toolkit, including parameters, return values, and usage examples.

Account tools

Account tools allow agents to interact with Recall accounts, including viewing account information and managing credits.

`get_account_info`

Retrieves information about a Recall account, including token balances, address, and nonce.

Parameters

Parameter	Type	Required	Description
`address`	string	No	The address of the account to get information for. If not provided, uses the connected account.

Returns

{
  address: string; // The account's address (0x...)
  nonce: number; // The account's transaction nonce
  balance: string; // The account's RECALL token balance
  parentBalance: string; // The account's token balance on the parent chain
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
I'll get the account information:
<function_calls>
<invoke name="get_account_info">
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "address": "0x123abc...",
  "nonce": 42,
  "balance": "1000000000000000000",
  "parentBalance": "0"
}
*/

`get_credit_info`

Gets credit information for the connected account, including available credits and used credits.

Parameters

Parameter	Type	Required	Description
`address`	string	No	The address of the account to get credit information for. If not provided, uses the connected account.

Returns

{
  credits: string; // The account's current credit balance
  used: string; // The amount of credit the account has used
  address: string; // The account's address
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
Let me check my credit balance:
<function_calls>
<invoke name="get_credit_info">
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "credits": "5000",
  "used": "250",
  "address": "0x123abc..."
}
*/

`buy_credit`

Buys credit for the connected account, allowing the agent to perform more operations on Recall.

Parameters

Parameter	Type	Required	Description
`amount`	string	Yes	The amount of credit to buy in ETH.
`to`	string	No	The address of the account to buy credit for. If not provided, uses the connected account.

Returns

{
  txHash: string; // The transaction hash
  credits: string; // The new credit balance after the purchase
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
I'll buy some more credit:
<function_calls>
<invoke name="buy_credit">
<parameter name="amount">0.01</parameter>
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "txHash": "0xdef789...",
  "credits": "6000"
}
*/

Bucket tools

Bucket tools allow agents to create, manage, and interact with storage buckets on Recall.

`list_buckets`

Lists all buckets owned by an address in Recall.

Parameters

Parameter	Type	Required	Description
`address`	string	No	The address of the account to list buckets for. If not provided, uses the connected account.

Returns

{
  buckets: Array<{
    bucket: string; // The bucket address (0x...)
    name: string; // The bucket name/alias
    metadata?: Record<string, string>; // Optional bucket metadata
  }>;
}

Example

// The agent might use it like this:
/*
Let me list all my buckets:
<function_calls>
<invoke name="list_buckets">
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "buckets": [
    {
      "bucket": "0xbucket1...",
      "name": "user-memories"
    },
    {
      "bucket": "0xbucket2...",
      "name": "chat-history",
      "metadata": {
        "createdAt": "2023-04-01T12:00:00Z"
      }
    }
  ]
}
*/

`create_bucket`

Creates a new bucket in Recall with the specified alias.

Parameters

Parameter	Type	Required	Description
`bucketAlias`	string	Yes	The alias to assign to the new bucket.
`metadata`	object	No	Optional metadata to store with the bucket.

Returns

{
  bucket: string;         // The address of the newly created bucket
  name: string;           // The alias of the bucket
  metadata?: Record<string, string>; // Any metadata stored with the bucket
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
I'll create a new bucket for storing user preferences:
<function_calls>
<invoke name="create_bucket">
<parameter name="bucketAlias">user-preferences</parameter>
<parameter name="metadata">{"createdBy": "agent", "purpose": "store user preferences"}</parameter>
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "bucket": "",
  "name": "user-preferences",
  "metadata": {
    "createdBy": "agent",
    "purpose": "store user preferences"
  }
}
*/

`get_or_create_bucket`

Gets an existing bucket by alias or creates a new one if it doesn't exist. This is often more convenient than separate get/create operations.

Parameters

Parameter	Type	Required	Description
`bucketAlias`	string	Yes	The alias of the bucket to retrieve or create.
`metadata`	object	No	Optional metadata to store with the bucket if created.

Returns

{
  bucket: string;         // The address of the bucket
  name: string;           // The alias of the bucket
  metadata?: Record<string, string>; // Any metadata stored with the bucket
  created: boolean;       // Whether the bucket was newly created
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
I'll get or create a bucket for storing chat history:
<function_calls>
<invoke name="get_or_create_bucket">
<parameter name="bucketAlias">chat-history</parameter>
<parameter name="metadata">{"type": "conversation", "version": "1.0"}</parameter>
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "bucket": "0xff0000000000000000000000000000000000008f",
  "name": "chat-history",
  "metadata": {
    "type": "conversation",
    "version": "1.0"
  },
  "created": true
}
*/

`add_object`

Adds an object to a bucket in Recall. This is how agents store data persistently.

Parameters

Parameter	Type	Required	Description
`bucket`	string	Yes	The address of the bucket (0x...).
`key`	string	Yes	The key under which to store the object.
`data`	string \| Uint8Array	Yes	The data to store. Most commonly a string or serialized JSON.
`metadata`	object	No	Optional metadata to store with the object.
`overwrite`	boolean	No	Whether to overwrite an existing object with the same key. Default is false.

Returns

{
  key: string;           // The key of the stored object
  size: number;          // The size of the stored data in bytes
  metadata?: Record<string, string>; // Any metadata stored with the object
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
I'll add the user preference data to the bucket:
<function_calls>
<invoke name="add_object">
<parameter name="bucket"></parameter>
<parameter name="key">preferences</parameter>
<parameter name="data">{"theme":"dark","language":"en"}</parameter>
<parameter name="metadata">{"lastUpdated":"2024-02-20T15:30:00Z"}</parameter>
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "key": "preferences",
  "size": 39,
  "metadata": {
    "lastUpdated": "2024-02-20T15:30:00Z"
  }
}
*/

`get_object`

Retrieves an object from a bucket in Recall. This is how agents retrieve previously stored data.

Parameters

Parameter	Type	Required	Description
`bucket`	string	Yes	The address of the bucket (0x...).
`key`	string	Yes	The key under which the object is stored.
`outputType`	string	No	The type of output to return: "string" (default) or "uint8array".

Returns

{
  value: string | Uint8Array; // The stored data
  key: string;                // The key of the retrieved object
  metadata?: Record<string, string>; // Any metadata stored with the object
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
I'll retrieve the user preferences:
<function_calls>
<invoke name="get_object">
<parameter name="bucket"></parameter>
<parameter name="key">preferences</parameter>
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "value": "{\"theme\":\"dark\",\"language\":\"en\"}",
  "key": "preferences",
  "metadata": {
    "lastUpdated": "2024-02-20T15:30:00Z"
  }
}
*/

`query_objects`

Queries objects in a bucket based on prefix, delimiter, and other criteria. Useful for listing objects or finding objects with specific patterns.

Parameters

Parameter	Type	Required	Description
`bucket`	string	Yes	The address of the bucket (0x...).
`prefix`	string	No	Filter objects that start with this prefix.
`delimiter`	string	No	Character used to group objects (similar to directories).
`startKey`	string	No	Start listing from this key (for pagination).
`limit`	number	No	Maximum number of results to return.

Returns

{
  objects: Array<{
    key: string;           // The key of the object
    size: number;          // The size of the object in bytes
    metadata?: Record<string, string>; // Any metadata stored with the object
  }>;
  startKey?: string;       // The key to use for pagination if results were limited
}

Example

// Claude or other MCP client will automatically discover and use this tool
// The agent might use it like this:
/*
I'll list all objects in the chat-history bucket that start with "user-":
<function_calls>
<invoke name="query_objects">
<parameter name="bucket">0xff0000000000000000000000000000000000008f</parameter>
<parameter name="prefix">user-</parameter>
<parameter name="limit">10</parameter>
</invoke>
</function_calls>
*/
 
// Sample response:
/*
{
  "objects": [
    {
      "key": "user-123-chat-1",
      "size": 256,
      "metadata": {
        "timestamp": "2024-02-20T10:15:00Z"
      }
    },
    {
      "key": "user-123-chat-2",
      "size": 512,
      "metadata": {
        "timestamp": "2024-02-20T11:20:00Z"
      }
    }
  ]
}
*/

Best practices

Error handling

When using the tools, implement proper error handling to make your agent more resilient:

try {
  const result = await toolkit.run("get_object", {
    bucket: bucketId,
    key: "user-data",
  });
  // Process the result
} catch (error) {
  if (error.message.includes("not found")) {
    // Handle missing object
    console.log("Object not found, creating default data");
  } else {
    // Handle other errors
    console.error("Error:", error);
  }
}

Object storage patterns

For structured data, serialize to JSON before storing:

const data = {
  preferences: {
    theme: "dark",
    fontSize: "medium",
  },
  history: [{ timestamp: Date.now(), action: "login" }],
};
 
// Call the add_object tool...

When retrieving, parse the JSON:

// Call the get_object tool...
 
const data = JSON.parse(value);
console.log(data.preferences.theme); // "dark"

Naming conventions

Use consistent key naming patterns to organize data effectively:

Hierarchical keys: Use slashes to create pseudo-directories: users/123/profile
Prefixes: Use consistent prefixes for related data: user-123-preferences, user-123-history
Timestamps: Include timestamps in keys for time-series data: logs-2023-04-01

Performance considerations

When working with the Agent Toolkit tools, consider these performance tips:

Batch operations: When storing multiple related objects, consider storing them as a single JSON object rather than multiple individual objects.
Lazy loading: Only retrieve data when needed rather than preemptively loading everything.
Caching: If repeatedly accessing the same data, cache it in memory rather than fetching it each time.
Pagination: Use the limit and startKey parameters when dealing with large numbers of objects.

For more complex scenarios or high-performance requirements, consider implementing a custom middleware that can optimize the API calls or implement caching.

Next steps

Now that you understand the available tools in the Agent Toolkit, you might want to:

Check out the core concepts guide for a deeper understanding of the toolkit's architecture
Learn about bucket monitoring to track your agent's storage
Explore MCP integration for using the toolkit with MCP-compatible models

Tools reference

On this page