Skip to main content

​
Overview

FunctionDeclaration defines the OpenAPI-style schema for a tool’s parameters. It tells the LLM what arguments the tool accepts, their types, descriptions, and which are required. This structure is based on the Google Generative AI SDK and is compatible with multiple LLM providers.

​
Type Definition

import { FunctionDeclaration, JSONSchema } from '@iqai/adk';

interface FunctionDeclaration {
  name: string;
  description: string;
  parameters?: JSONSchema;
}

​
Properties

​
name
string
required
The name of the function/tool. Must match the tool’s name property.Should contain only alphanumeric characters and underscores.Example: http_request, calculate_sum, search_database
​
description
string
required
A clear description of what the function does. This helps the LLM understand when and how to use the tool.Should be descriptive and explain the tool’s purpose and behavior.Example: Makes HTTP requests to external APIs and returns the response
​
parameters
JSONSchema
The JSON Schema defining the function’s parameters. See JSONSchema Structure below.

​
JSONSchema Structure

The parameters field uses JSON Schema to define the structure of tool arguments:
​
type
Type
required
The schema type. For function parameters, this is typically Type.OBJECT.Available types from @google/genai:
  • Type.OBJECT
  • Type.STRING
  • Type.NUMBER
  • Type.INTEGER
  • Type.BOOLEAN
  • Type.ARRAY
​
properties
Record<string, JSONSchema>
Object mapping parameter names to their schema definitions.Each property can have:
  • type - The parameter’s type
  • description - What the parameter is for
  • enum - Array of allowed values
  • default - Default value if not provided
  • Additional nested schema properties
​
required
string[]
Array of parameter names that are required.Example: ['url', 'method']

​
Examples

​
Basic Function Declaration

import { Type } from '@google/genai';
import type { FunctionDeclaration } from '@iqai/adk';

const simpleDeclaration: FunctionDeclaration = {
  name: 'get_weather',
  description: 'Get current weather for a location',
  parameters: {
    type: Type.OBJECT,
    properties: {
      location: {
        type: Type.STRING,
        description: 'City name or coordinates'
      },
      units: {
        type: Type.STRING,
        description: 'Temperature units',
        enum: ['celsius', 'fahrenheit'],
        default: 'celsius'
      }
    },
    required: ['location']
  }
};

​
Complex Function Declaration

import { Type } from '@google/genai';
import type { FunctionDeclaration } from '@iqai/adk';

const complexDeclaration: FunctionDeclaration = {
  name: 'http_request',
  description: 'Make HTTP requests to external APIs',
  parameters: {
    type: Type.OBJECT,
    properties: {
      url: {
        type: Type.STRING,
        description: 'The URL to send the request to'
      },
      method: {
        type: Type.STRING,
        description: 'HTTP method to use',
        enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
        default: 'GET'
      },
      headers: {
        type: Type.OBJECT,
        description: 'Request headers as key-value pairs'
      },
      body: {
        type: Type.STRING,
        description: 'Request body content (typically JSON string)'
      },
      timeout: {
        type: Type.INTEGER,
        description: 'Request timeout in milliseconds',
        default: 10000
      }
    },
    required: ['url']
  }
};

​
Array Parameters

import { Type } from '@google/genai';

const arrayDeclaration: FunctionDeclaration = {
  name: 'process_items',
  description: 'Process a list of items',
  parameters: {
    type: Type.OBJECT,
    properties: {
      items: {
        type: Type.ARRAY,
        description: 'Array of items to process',
        items: {
          type: Type.STRING
        }
      },
      operation: {
        type: Type.STRING,
        description: 'Operation to perform on items',
        enum: ['uppercase', 'lowercase', 'reverse']
      }
    },
    required: ['items', 'operation']
  }
};

​
Nested Objects

import { Type } from '@google/genai';

const nestedDeclaration: FunctionDeclaration = {
  name: 'create_user',
  description: 'Create a new user account',
  parameters: {
    type: Type.OBJECT,
    properties: {
      username: {
        type: Type.STRING,
        description: 'Unique username for the account'
      },
      profile: {
        type: Type.OBJECT,
        description: 'User profile information',
        properties: {
          firstName: {
            type: Type.STRING,
            description: 'User first name'
          },
          lastName: {
            type: Type.STRING,
            description: 'User last name'
          },
          age: {
            type: Type.INTEGER,
            description: 'User age in years'
          }
        }
      },
      preferences: {
        type: Type.OBJECT,
        description: 'User preferences'
      }
    },
    required: ['username', 'profile']
  }
};

​
Automatic Generation

ADK-TS provides utilities to automatically generate function declarations:

​
Using buildFunctionDeclaration()

import { buildFunctionDeclaration } from '@iqai/adk';

/**
 * Calculates the sum of two numbers
 * @param a First number
 * @param b Second number
 * @returns The sum of a and b
 */
function add(a: number, b: number): number {
  return a + b;
}

const declaration = buildFunctionDeclaration(add, {
  name: 'add',
  description: 'Adds two numbers together'
});

// Result:
// {
//   name: 'add',
//   description: 'Adds two numbers together',
//   parameters: {
//     type: Type.OBJECT,
//     properties: {
//       a: { type: 'number', description: 'First number' },
//       b: { type: 'number', description: 'Second number' }
//     },
//     required: ['a', 'b']
//   }
// }

​
Using createTool() with Zod

import { createTool } from '@iqai/adk';
import { z } from 'zod';

const calculatorTool = createTool({
  name: 'calculator',
  description: 'Performs arithmetic operations',
  schema: z.object({
    operation: z.enum(['add', 'subtract', 'multiply', 'divide'])
      .describe('The arithmetic operation to perform'),
    a: z.number().describe('First operand'),
    b: z.number().describe('Second operand')
  }),
  fn: ({ operation, a, b }) => {
    switch (operation) {
      case 'add': return { result: a + b };
      case 'subtract': return { result: a - b };
      case 'multiply': return { result: a * b };
      case 'divide': return { result: a / b };
    }
  }
});

// Function declaration is generated automatically from Zod schema
const declaration = calculatorTool.getDeclaration();

​
Best Practices

Clear Descriptions

Write clear, concise descriptions for both the function and each parameter. This helps the LLM understand when and how to use your tool.

Use Enums

When a parameter has a limited set of valid values, use the enum property to constrain the choices.

Specify Required

Always specify which parameters are required. This prevents the LLM from calling your tool with missing arguments.

Provide Defaults

Use the default property for optional parameters to ensure sensible behavior when they’re omitted.

​
Type Reference

​
Type Enum

From @google/genai: 
enum Type {
  STRING = 'string',
  NUMBER = 'number',
  INTEGER = 'integer',
  BOOLEAN = 'boolean',
  ARRAY = 'array',
  OBJECT = 'object'
}

​
JSONSchema Interface

interface JSONSchema {
  type: Type;
  description?: string;
  properties?: Record<string, JSONSchema>;
  required?: string[];
  items?: JSONSchema;
  enum?: string[];
  default?: any;
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us