agent-tool-lite
v0.1.0
Published
Define an LLM function-calling tool once — generate the provider JSON schema and validate the model's arguments before you execute.
Maintainers
Readme
agent-tool-lite
Define an LLM function-calling tool once — get the provider-shaped JSON schema out of it, and validate the model's arguments before you execute anything.
Zero runtime dependencies, framework-agnostic, TypeScript-first. It does not call any LLM, does not own your agent loop, and does not care which provider you use.
Install
npm install agent-tool-liteQuick start
import { defineTool, toJSONSchema, validateArgs, formatErrors } from 'agent-tool-lite';
const getWeather = defineTool({
name: 'get_weather',
description: 'Get the current weather for a city.',
parameters: {
city: { type: 'string', description: 'City name', required: true },
units: {
type: 'string',
description: 'Temperature units',
enum: ['celsius', 'fahrenheit'],
},
},
});
// 1. Send the tool definition to the model
const tools = [toJSONSchema(getWeather)];
// => [{ type: 'function', function: { name, description, parameters: {...} } }]
// 2. The model calls it — validate before executing
const result = validateArgs(getWeather, '{"city":"Mumbai","units":"celsius"}');
if (result.valid) {
await fetchWeather(result.value.city, result.value.units);
} else {
// hand the errors straight back to the model so it can retry
console.log(formatErrors(result.errors));
}The whole point
The model decides what to send you. It is usually right, and occasionally it invents a parameter, sends "7" where you wanted 7, drops a required field, or returns arguments that don't parse as JSON at all. validateArgs sits between "the model called your tool" and "your code ran" so those cases become a structured error instead of a TypeError three functions deep.
validateArgs(getWeather, { units: 'kelvin' });
// {
// valid: false,
// value: undefined,
// errors: [
// { path: 'city', message: 'required parameter is missing' },
// { path: 'units', message: 'value must be one of: celsius, fahrenheit' },
// ]
// }It never throws on bad model output — it returns a result you can branch on. formatErrors(errors) flattens it into one string that reads well as a tool-result message the model can act on:
city: required parameter is missing; units: value must be one of: celsius, fahrenheitProvider formats
toJSONSchema(tool); // 'openai' (default)
toJSONSchema(tool, 'anthropic'); // { name, description, input_schema }
toJSONSchema(tool, 'raw'); // just the parameters JSON Schema
toJSONSchemaAll(tools, 'anthropic'); // map over an arrayOpenAI-style:
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {
"city": { "type": "string", "description": "City name" },
"units": { "type": "string", "description": "Temperature units", "enum": ["celsius", "fahrenheit"] }
},
"required": ["city"]
}
}
}Anthropic-style is the same schema under input_schema. One tool definition, either wire format — so switching providers doesn't mean rewriting your tool declarations.
Nested parameters
object and array params nest, and required is declared inline on each child rather than as a separate list you have to keep in sync:
const createEvent = defineTool({
name: 'create_event',
description: 'Create a calendar event.',
parameters: {
title: { type: 'string', required: true },
location: {
type: 'object',
required: true,
properties: {
city: { type: 'string', required: true },
room: { type: 'string' },
},
},
attendees: {
type: 'array',
items: { type: 'string', description: 'Email address' },
minItems: 1,
},
},
});
validateArgs(createEvent, { title: 'Sync', location: { room: 'B2' }, attendees: ['[email protected]', 9] });
// errors:
// { path: 'location.city', message: 'required parameter is missing' }
// { path: 'attendees[1]', message: 'expected string, got number' }Error paths point at the exact value, nesting and array indices included.
Parameter options
| Option | Applies to | Description |
|---|---|---|
| type | all | string, number, integer, boolean, object, array |
| description | all | What the model reads to decide how to fill it in |
| required | all | Defaults to false |
| enum | primitives | Allowed values |
| properties | object | Child parameters |
| items | array | Element schema (required for arrays) |
| minimum / maximum | number, integer | Numeric bounds |
| minLength / maxLength | string | Length bounds |
| minItems / maxItems | array | Item-count bounds |
| additionalProperties | object | false to reject undeclared nested keys |
Strict mode
By default, arguments the model sends that you didn't declare are dropped from value but don't fail validation — a hallucinated extra field shouldn't kill an otherwise fine call. Set strict: true when you'd rather know:
defineTool({ name: 'transfer', description: '...', strict: true, parameters: { ... } });
// unknown keys now produce { path: 'rogue', message: 'unknown parameter is not allowed' }
// and toJSONSchema() emits "additionalProperties": falseDefinition-time errors
defineTool throws immediately on structural mistakes — an invalid tool name, an unsupported parameter type, an array without items — so you find out when the module loads, not when a provider rejects your request mid-conversation.
API
| Export | Signature |
|---|---|
| defineTool | (config: ToolConfig) => Tool |
| toJSONSchema | (tool: Tool, format?: 'openai' \| 'anthropic' \| 'raw') => object |
| toJSONSchemaAll | (tools: Tool[], format?) => object[] |
| validateArgs | <T>(tool: Tool, args: unknown) => ValidationResult<T> |
| formatErrors | (errors: ValidationError[]) => string |
validateArgs accepts either an object or the raw JSON string providers hand back, so you don't have to JSON.parse (and try/catch) it yourself.
Design notes
See CASE_STUDY.md for why this is ~350 lines of schema helper rather than an agent framework.
License
MIT © Tejas Kadam
