defineTool

import { defineTool } from '@carloscortezcloud/tinkuy-agent';

const weatherTool = defineTool({
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' },
      units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
    },
    required: ['city'],
  },
  execute: async (args) => {
    const { city, units = 'celsius' } = args;
    const temp = await fetchWeather(city, units);
    return { temperature: temp, city, units };
  },
});

Tool Parameters

The parameters field follows JSON Schema. Supported types:

• string, number, boolean
• array (with items schema)
• object (with properties)
• enum for constrained values
• description helps the LLM decide when to use the tool

Tool Execution

The execute function receives the validated arguments. It can:

• Return any JSON-serializable value
• Throw an error (the agent will report it back to the LLM)
• Be async (supports Promise)

Best Practices

// 1. One tool = one responsibility
const searchTool = defineTool({
  name: 'search_docs',
  description: 'Search documentation',
  // ...
});

// 2. Be specific in descriptions
const sendEmail = defineTool({
  name: 'send_email',
  description: 'Send an email to a verified recipient with the provided content',
  // ...
});

// 3. List required parameters explicitly
const createTicket = defineTool({
  name: 'create_ticket',
  parameters: {
    type: 'object',
    properties: {
      title: { type: 'string' },
      priority: { type: 'string', enum: ['low', 'medium', 'high'] },
      assignee: { type: 'string' },
    },
    required: ['title', 'priority'],  // assignee is optional
  },
  // ...
});