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

  1. Use schema tool first - Understand your data structure before querying
  2. Validate with query tool - Always validate SQL before executing
  3. Read from schema - database describe reads from .an5 files first
  4. Use parameterized queries - Prevent SQL injection
  5. 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.