Overview#
The Tool Schemas API provides endpoints for discovering, validating, and using structured schemas for AI agent tools. The system includes 6 default tools (search, kg_query, calc, tts, stt, scheduler) with comprehensive parameter validation, constraint enforcement, and OpenAPI schema export capabilities.
Base URL#
http://localhost:3007/v1/ai
Authentication#
All endpoints require authentication via Bearer token in the Authorization header.
Endpoints#
List All Tools#
GET /tools
Returns all available tool schemas.
Query Parameters:
category(optional): Filter by category (search, knowledge, computation, speech, scheduling, system)
Response: 200 OK
{
"tools": [
{
"name": "search",
"description": "Search the knowledge base",
"category": "search",
"parameters": [...],
"returns": {...},
"examples": [...]
}
],
"count": 6
}
Get Tool Schema#
GET /tools/:name
Retrieve a specific tool schema by name.
Response: 200 OK or 404 Not Found
{
"name": "search",
"description": "Search the knowledge base",
"category": "search",
"parameters": [
{
"name": "query",
"type": "string",
"description": "Search query",
"required": true,
"maxLength": 500
}
],
"returns": {
"type": "object",
"description": "Search results",
"schema": {
"results": "array",
"count": "number"
}
},
"examples": [
{
"input": { "query": "meditation techniques" },
"output": { "results": [...], "count": 5 },
"description": "Search for meditation content"
}
],
"permissions": ["read:content"],
"rateLimit": {
"calls": 100,
"period": "minute"
}
}
Validate Tool Input#
POST /tools/:name/validate
Validate input parameters against tool schema.
Request Body:
{
"input": {
"query": "example search",
"limit": 10
}
}
Response: 200 OK
{
"valid": true,
"errors": []
}
Error Response:
{
"valid": false,
"errors": [
"Missing required parameter: query",
"Parameter 'limit' exceeds maximum: 100"
]
}
Get Tools by Category#
GET /tools/category/:category
Retrieve all tools in a specific category.
Categories:
search- Search and retrieval toolsknowledge- Knowledge graph queriescomputation- Mathematical calculationsspeech- Text-to-speech and speech-to-textscheduling- Time-based schedulingsystem- System utilities
Response: 200 OK
{
"category": "speech",
"tools": [
{
"name": "tts",
"description": "Text-to-speech synthesis",
"category": "speech",
...
},
{
"name": "stt",
"description": "Speech-to-text transcription",
"category": "speech",
...
}
],
"count": 2
}
Export OpenAPI Schema#
GET /tools/:name/openapi
Export tool schema in OpenAPI 3.0 format.
Response: 200 OK
{
"openapi": "3.0.0",
"info": {
"title": "search",
"description": "Search the knowledge base",
"version": "1.0.0"
},
"paths": {
"/search": {
"post": {
"summary": "Search the knowledge base",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search query",
"maxLength": 500
}
},
"required": ["query"]
}
}
}
},
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
}
}
}
Export All Schemas#
GET /tools/openapi
Export OpenAPI schemas for all tools.
Response: 200 OK
{
"openapi": "3.0.0",
"info": {
"title": "AI Tools API",
"description": "All available AI agent tools",
"version": "1.0.0"
},
"paths": {
"/search": {...},
"/kg_query": {...},
"/calc": {...},
"/tts": {...},
"/stt": {...},
"/scheduler": {...}
}
}
Default Tools#
1. Search Tool#
{
name: "search",
description: "Search the knowledge base",
category: "search",
parameters: [
{
name: "query",
type: "string",
description: "Search query",
required: true,
maxLength: 500
},
{
name: "limit",
type: "number",
description: "Maximum results",
required: false,
default: 10,
minimum: 1,
maximum: 100
}
],
returns: {
type: "object",
description: "Search results with metadata",
schema: {
results: "array",
count: "number",
query: "string"
}
},
permissions: ["read:content"],
rateLimit: {
calls: 100,
period: "minute"
}
}
2. Knowledge Graph Query Tool#
{
name: "kg_query",
description: "Query the knowledge graph",
category: "knowledge",
parameters: [
{
name: "query",
type: "string",
description: "SPARQL or Cypher query",
required: true,
maxLength: 2000
},
{
name: "queryType",
type: "string",
description: "Query language",
required: false,
enum: ["sparql", "cypher"],
default: "sparql"
}
],
returns: {
type: "object",
description: "Query results",
schema: {
bindings: "array",
count: "number"
}
},
permissions: ["read:knowledge_graph"],
rateLimit: {
calls: 50,
period: "minute"
}
}
3. Calculator Tool#
{
name: "calc",
description: "Evaluate mathematical expressions",
category: "computation",
parameters: [
{
name: "expression",
type: "string",
description: "Mathematical expression to evaluate",
required: true,
pattern: "^[0-9+\\-*/()\\s.]+$",
maxLength: 200
}
],
returns: {
type: "number",
description: "Calculation result"
},
permissions: [],
rateLimit: {
calls: 1000,
period: "minute"
}
}
4. Text-to-Speech Tool#
{
name: "tts",
description: "Convert text to speech",
category: "speech",
parameters: [
{
name: "text",
type: "string",
description: "Text to synthesize",
required: true,
maxLength: 5000
},
{
name: "voice",
type: "string",
description: "Voice ID",
required: false,
default: "default"
},
{
name: "format",
type: "string",
description: "Audio format",
required: false,
enum: ["mp3", "wav", "ogg"],
default: "mp3"
}
],
returns: {
type: "object",
description: "Audio file URL and metadata",
schema: {
url: "string",
duration: "number",
format: "string"
}
},
permissions: ["use:tts"],
rateLimit: {
calls: 100,
period: "hour"
}
}
5. Speech-to-Text Tool#
{
name: "stt",
description: "Transcribe speech to text",
category: "speech",
parameters: [
{
name: "audioUrl",
type: "string",
description: "URL of audio file",
required: true,
pattern: "^https?://.+\\.(mp3|wav|ogg)$"
},
{
name: "language",
type: "string",
description: "Audio language",
required: false,
default: "en"
}
],
returns: {
type: "object",
description: "Transcription result",
schema: {
text: "string",
confidence: "number",
words: "array"
}
},
permissions: ["use:stt"],
rateLimit: {
calls: 50,
period: "hour"
}
}
6. Scheduler Tool#
{
name: "scheduler",
description: "Schedule tasks and reminders",
category: "scheduling",
parameters: [
{
name: "action",
type: "string",
description: "Scheduler action",
required: true,
enum: ["schedule", "cancel", "list"]
},
{
name: "taskId",
type: "string",
description: "Task ID for cancel operation",
required: false
},
{
name: "schedule",
type: "object",
description: "Schedule details for scheduling",
required: false
}
],
returns: {
type: "object",
description: "Scheduler response",
schema: {
taskId: "string",
status: "string",
scheduledAt: "string"
}
},
permissions: ["use:scheduler"],
rateLimit: {
calls: 100,
period: "minute"
}
}
Data Models#
ToolParameter#
interface ToolParameter {
name: string;
type: 'string' | 'number' | 'boolean' | 'object' | 'array';
description: string;
required: boolean;
default?: any;
enum?: any[];
pattern?: string;
minLength?: number;
maxLength?: number;
minimum?: number;
maximum?: number;
}
ToolSchema#
interface ToolSchema {
name: string;
description: string;
category:
| 'search'
| 'knowledge'
| 'computation'
| 'speech'
| 'scheduling'
| 'system';
parameters: ToolParameter[];
returns: {
type: string;
description: string;
schema?: any;
};
examples: Array<{
input: Record<string, any>;
output: any;
description: string;
}>;
permissions?: string[];
rateLimit?: {
calls: number;
period: 'second' | 'minute' | 'hour' | 'day';
};
}
Validation Rules#
Parameter Validation#
- Required: Must be present if
required: true - Type: Must match specified type (string, number, boolean, object, array)
- Enum: Must be one of the allowed values
- Pattern: Must match regex pattern
- Length: String length must be within minLength/maxLength
- Range: Number must be within minimum/maximum
Schema Validation#
- Name: Must be unique across all tools
- Description: Required, non-empty
- Category: Must be valid category
- Parameters: Each parameter must have name, type, description
Error Responses#
400 Bad Request
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid tool parameters",
"details": {
"valid": false,
"errors": ["Missing required parameter: query"]
}
}
}
404 Not Found
{
"error": {
"code": "TOOL_NOT_FOUND",
"message": "Tool 'unknown_tool' not found"
}
}
500 Internal Server Error
{
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred"
}
}
Examples#
Register Custom Tool#
curl -X POST http://localhost:3007/v1/ai/tools \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "translator",
"description": "Translate text between languages",
"category": "system",
"parameters": [
{
"name": "text",
"type": "string",
"description": "Text to translate",
"required": true,
"maxLength": 5000
},
{
"name": "targetLang",
"type": "string",
"description": "Target language code",
"required": true,
"enum": ["en", "es", "fr", "de", "zh", "ja"]
}
],
"returns": {
"type": "object",
"description": "Translation result",
"schema": {
"translatedText": "string",
"sourceLanguage": "string",
"confidence": "number"
}
},
"examples": [
{
"input": { "text": "Hello world", "targetLang": "es" },
"output": { "translatedText": "Hola mundo", "sourceLanguage": "en", "confidence": 0.99 },
"description": "English to Spanish translation"
}
]
}'
Validate Search Input#
curl -X POST http://localhost:3007/v1/ai/tools/search/validate \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"input": {
"query": "meditation techniques",
"limit": 10
}
}'
Get Speech Tools#
curl -X GET "http://localhost:3007/v1/ai/tools?category=speech" \
-H "Authorization: Bearer YOUR_TOKEN"
Export OpenAPI Schema#
curl -X GET "http://localhost:3007/v1/ai/tools/search/openapi" \
-H "Authorization: Bearer YOUR_TOKEN"
Test Coverage#
The Tool Schemas feature has comprehensive test coverage:
- Unit Tests: 54 tests (100% code coverage)
- Integration Tests: 19 tests (all HTTP endpoints)
- E2E Tests: 23 Playwright tests
- Total: 96 tests passing
Implementation#
- Language: TypeScript with strict type safety
- File:
apps/lilith/svc-ai/src/tool-schemas.ts - Lines of Code: 609
- Dependencies: None (in-memory storage)
Limitations#
- Tools are stored in-memory (not persisted to database)
- No pagination on list endpoints
- Tool schemas cannot be deleted after registration
- Rate limiting is metadata only (not enforced)
Future Enhancements#
- Database persistence (PostgreSQL)
- Dynamic tool loading from external sources
- Tool execution engine integration
- Real-time schema validation
- Tool versioning and deprecation
- Usage analytics and monitoring
Generated: 2025-10-03 API Version: 1.0.0 Test Coverage: 96 tests passing