AI Agent Tools
an5 Agent provides 8 consolidated tools for schema exploration, query generation, database operations, and task management.
In VS Code, the same capabilities are reachable without writing any integration code: the an5OrmVScode extension ships an MCP server exposing schema tools, read-only queries and the schema operations to Copilot and other MCP clients. It registers itself — run MCP: List Servers and start AN5 ORM — or run AN5: Install MCP Server to write the config file.
Tool Overview
| Tool | Actions | Description |
|---|---|---|
schema |
list, describe, relations | Explore data models |
query |
generate, explain, validate | Work with SQL queries |
database |
execute, describe, health | Database operations |
generateClientCode |
- | Generate client code |
generateCode |
- | Request-specific application code through a model callback, or schema/API context for the calling model |
analyzeSchema |
- | Analyze schema issues |
retrieve |
schema, queries | Semantic search |
task |
create, list, update, delete | Manage tasks |
schema
Explore database schema structure.
Actions
| Action | Description | Required Params |
|---|---|---|
list |
List all models | - |
describe |
Get model details | modelName |
relations |
Get foreign keys | - (optional: modelName) |
Examples
List all models:
await agent.executeTool('schema', { action: 'list' });
// Returns: { models: [...], totalModels: 5 }
Describe a model:
await agent.executeTool('schema', {
action: 'describe',
modelName: 'User'
});
// Returns: { model: { name, fields, relations }, found: true }
Get relations:
await agent.executeTool('schema', {
action: 'relations',
modelName: 'User' // Optional: filter by model
});
// Returns: { relations: [...] }
query
Work with SQL queries.
Actions
| Action | Description | Required Params |
|---|---|---|
generate |
Generate SQL from natural language | description |
explain |
Analyze SQL query | sql |
validate |
Check SQL syntax | sql |
Examples
Generate SQL:
await agent.executeTool('query', {
action: 'generate',
description: 'Find all users with their orders',
tables: ['User', 'Order'] // Optional
});
// Returns: { sql: 'SELECT ...', explanation: '...', tables: [...] }
Explain query:
await agent.executeTool('query', {
action: 'explain',
sql: 'SELECT u.*, COUNT(o.id) FROM users u LEFT JOIN orders o ON u.id = o.userId GROUP BY u.id'
});
// Returns: { interpretedIntent: '...', estimatedComplexity: 'moderate', notes: [...] }
Validate query:
await agent.executeTool('query', {
action: 'validate',
sql: 'UPDATE users SET name = "John"' // Invalid: uses double quotes
});
// Returns: { isValid: false, errors: [...], suggestions: [...] }
database
Database operations.
Actions
| Action | Description | Required Params |
|---|---|---|
execute |
Run SELECT query | sql |
describe |
Get table structure | tableName |
health |
Check connection | - |
Examples
Execute query:
await agent.executeTool('database', {
action: 'execute',
sql: 'SELECT TOP 10 * FROM users',
connectionString: process.env.DATABASE_URL
});
// Returns: { success: true, rows: [...], rowCount: 10 }
Describe table (reads from schema first):
await agent.executeTool('database', {
action: 'describe',
tableName: 'User'
});
// Returns: {
// tableName: 'User',
// source: 'schema', // or 'database' if not in schema
// columns: [...]
// }
Health check:
await agent.executeTool('database', {
action: 'health',
connectionString: process.env.DATABASE_URL
});
// Returns: { connected: true, serverVersion: '...', latencyMs: 12 }
generateClientCode
Generate type-safe client code from schema, for any language the ORM supports:
typescript, python, dotnet, golang, rust, java, kotlin or swift.
await agent.executeTool('generateClientCode', {
schemaPath: 'an5Schema',
language: 'rust' // or 'typescript' | 'python' | 'dotnet' | 'golang'
});
// Returns: { success: true, files: [...], message: '...' }
The tool runs the real @an5/orm generator, so its output matches
npm run generate — the same files, with the same relations, filters and
metadata. Without outputDir it generates into a temporary directory, reads the
artifacts back and cleans up.
// Write straight into the project
await agent.executeTool('generateClientCode', {
schemaPath: 'an5Schema',
language: 'typescript',
outputDir: 'an5Client/typescript',
});
analyzeSchema
Analyze schema for design issues.
await agent.executeTool('analyzeSchema', {
schemaPath: 'an5Schema'
});
// Returns: {
// issues: [...],
// summary: { totalModels, totalFields, missingPrimaryKeys }
// }
retrieve
Semantic search over schema and query samples.
Types
| Type | Description |
|---|---|
schema |
Find model definitions |
queries |
Find SQL examples |
Examples
Search schema:
await agent.executeTool('retrieve', {
type: 'schema',
query: 'user authentication and permissions',
k: 3 // Optional: max results
});
// Returns: { results: [...], query: '...' }
Search query samples:
await agent.executeTool('retrieve', {
type: 'queries',
query: 'aggregate sales by month'
});
// Returns: { results: [...], query: '...' }
task
Manage tasks from code reviews.
Actions
| Action | Description | Required Params |
|---|---|---|
create |
Create task from issue | type, description |
list |
List tasks | - (optional: status, priority) |
update |
Update task | taskId + status/priority |
delete |
Delete task | taskId |
Examples
Create task:
await agent.executeTool('task', {
action: 'create',
type: 'BUG',
description: 'User email not validated properly',
file: 'src/services/user.ts'
});
// Returns: { id: '...', title: '...', priority: 'medium', status: 'todo' }
List tasks:
await agent.executeTool('task', {
action: 'list',
status: 'todo',
priority: 'high'
});
// Returns: [{ id: '...', title: '...', ... }]
Update task:
await agent.executeTool('task', {
action: 'update',
taskId: 'task-abc123',
status: 'in-progress'
});
Delete task:
await agent.executeTool('task', {
action: 'delete',
taskId: 'task-abc123'
});
// Returns: true
Natural Language Processing
import { An5Agent } from '@an5/agent';
// Registers the 7 default tools; optionally pass extra tools
const agent = new An5Agent();
// Ask questions in natural language
const result = await agent.process({
userQuestion: 'Show me all users with their recent orders',
toolContext: { connectionString: process.env.DATABASE_URL }
});
console.log(result.toolCalls);
console.log(result.answer);
Best Practices
- Use
schematool first - Understand your data structure before querying - Validate with
querytool - Always validate SQL before executing - Read from schema -
database describereads from.an5files first - Use parameterized queries - Prevent SQL injection
- Check health - Verify connection before operations
generateCode
Accepts request, optional language (auto, typescript, python, dotnet, golang, rust), projectRoot and schemaPath. Automatic detection uses manifests directly in the selected project directory. Missing or multiple language markers require an explicit language.
The tool returns schema models, the configured client output directory and real generated API references. Configure ToolContext.generateCode with your application’s model callback to return application code. Without a callback it returns status: context_ready; it does not pretend a snippet has been generated. Returned code is uncompiled and must be validated by the application. It never writes application files or executes SQL.
await agent.executeTool('generateCode', {
request: 'Write a function that lists User email addresses',
projectRoot: '/path/to/app',
schemaPath: 'an5Schema',
language: 'typescript',
}, {
generateCode: async context => yourModel(JSON.stringify(context)),
});
yourModel is supplied by the application. Vietnamese code requests are also supported by agent.process. Requires an ORM build exporting prepareCodeRequest.