Skip to main content

​
Introduction

Meridian’s AI agents leverage a comprehensive suite of tools to analyze data, generate insights, and interact with external information sources. These tools are built using the @convex-dev/agent framework and provide seamless integration between AI models and database operations.

​
Available Tools

Agent tools are organized into three main categories:

​
Database Operations

Query Tool

Execute SQL queries and retrieve data from DuckDB

Schema Tools

Get table schemas, sample rows, and database structure

​
Data Visualization

Chart Tool

Create interactive charts from query results

Insights Tool

Generate AI-powered insights from data analysis

​
Web Integration

Web Search

Search the web using Firecrawl integration

Web Scraping

Extract content and structured data from web pages

​
Tool Architecture

All agent tools follow a consistent architecture: 
import { createTool } from '@convex-dev/agent'
import { z } from 'zod'

export const toolName = createTool({
  description: 'Tool description for the AI agent',
  args: z.object({
    // Zod schema for tool arguments
  }),
  handler: async (ctx, args) => {
    // Tool implementation
    return { success: true, data: result }
  },
})

​
Response Truncation

To optimize token usage and reduce costs, all tool responses are automatically truncated:
  • String fields: Maximum 2,000 characters
  • Large content: Maximum 5,000 characters (markdown/HTML)
  • Arrays: Maximum 10 items
  • Rows returned: Maximum 10 rows (with rowCount indicating total)
Truncated responses include flags like _truncatedRows, _truncatedSources, etc.

​
Agent Modes

Meridian uses two specialized agents that leverage these tools:

​
Query Agent

Generates SQL queries for database operations:
  • Writes valid DuckDB SQL
  • Splits complex requests into multiple queries
  • Returns structured JSON with commands and descriptions
  • Maximum 10 queries per request

​
Analysis Agent

Explores and analyzes databases with tool assistance:
  • Queries and inspects DuckDB tables
  • Creates visualizations from data
  • Searches web for external context
  • Assesses data quality and compares tables
  • Maximum 6 tool execution steps

​
Tool Registration

Tools are registered when creating agents: 
import { Agent } from '@convex-dev/agent'
import {
  queryDuckDB,
  createChart,
  generateInsights,
  firecrawlSearch,
  scrapeWebPage,
  getTableSchema,
  getSampleRows,
} from './agent_tools'

const agent = new Agent(components.agent, {
  name: 'Analysis Agent',
  languageModel: model,
  instructions: 'Agent instructions...',
  maxSteps: 6,
  tools: {
    queryDuckDB,
    getTableSchema,
    getSampleRows,
    createChart,
    generateInsights,
    firecrawlSearch,
    scrapeWebPage,
  },
})

​
Error Handling

All tools implement consistent error handling: 
try {
  const result = await performOperation()
  return {
    success: true,
    // ... result data
  }
} catch (error) {
  return {
    success: false,
    error: error instanceof Error ? error.message : 'Unknown error occurred',
  }
}

​
Next Steps

Query Tool

Learn about database query operations

Chart Tool

Create visualizations from data

Web Tools

Integrate external web data

Using AI Agents

Guide to working with agents

Build docs developers (and LLMs) love

Get started for freeTalk to us