Tool Schema Generator

https://github.com/youssefdawoud-dev/tool_schema_generator
Admin
Tool Schema Generator is a Dart code generator that automatically produces JSON Schema (Draft...
Tokens:5,374
Snippets:36
Trust Score:1.2
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### build_runner Configuration for tool_schema_generator

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Example `build.yaml` configuration for integrating `tool_schema_generator` with `build_runner`. This setup automatically applies to dependent packages, requiring only a `part` directive in consumer packages.

```yaml
# build.yaml (inside tool_schema_generator — NOT required in consumer packages)
builders:
  tool_schema:
    import: "package:tool_schema_generator/builder.dart"
    builder_factories: ["toolSchemaBuilder"]
    build_extensions: { ".dart": [".tool_schema.g.part"] }
    auto_apply: dependents
    build_to: cache
    applies_builders: ["source_gen:combining_builder"]
```

--------------------------------

### Run the schema generator build runner

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/example/README.md

Execute the build runner command to generate the `.g.dart` file after applying `@Tool()` annotations.

```bash
dart run build_runner build -d
```

--------------------------------

### Using `allToolSchemas` with LLM APIs

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Shows how to use the generated `allToolSchemas` constant to pass tool definitions to OpenAI and Gemini APIs. This aggregate list contains all schemas defined by `@Tool()`-annotated functions in the file.

```dart
// lib/tools.dart
import 'package:tool_schema_generator/tool_schema_generator.dart';
part 'tools.g.dart';

@Tool() void getWeather(String city) {}
@Tool() void sendEmail(String to, String subject, String body) {}
@Tool() void searchProducts(String query, int limit) {}

// --- Usage in your LLM integration ---

import 'tools.dart'; // exposes allToolSchemas

void callOpenAI() async {
  // Pass schemas directly to the OpenAI tools parameter:
  final requestBody = {
    'model': 'gpt-4o',
    'messages': [{'role': 'user', 'content': 'What is the weather in Cairo?'}],
    'tools': allToolSchemas,           // ← generated list, ready to use
    'tool_choice': 'auto',
  };
  // ... send requestBody to OpenAI API
}

void callGemini() async {
  // Pass schemas to the Gemini functionDeclarations parameter:
  final tools = allToolSchemas.map((schema) {
    final fn = schema['function'] as Map<String, dynamic>;
    return {
      'name': fn['name'],
      'description': fn['description'],
      'parameters': fn['parameters'],
    };
  }).toList();
  // ... send tools to Gemini API
}
```

--------------------------------

### Integrate and Dispatch LLM Tool Calls

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/README.md

Pass generated schemas to the LLM for tool generation. When the LLM responds with tool calls, use the toolRegistry to dispatch them and handle the results, distinguishing between success and errors.

```dart
import 'tools.dart';

void main() async {
  // 1. Pass the schemas to your LLM
  final response = await llm.generate(
    prompt: "Send an email to hello@example.com saying Hi!",
    // toolRegistry.allSchemas -> is a List<Map<String, dynamic>>
    // toolRegistry.sendEmail -> is a Map<String, dynamic>
    tools: toolRegistry.allSchemas, // or [toolRegistry.sendEmail]
  );

  // 2. When the LLM decides to call a tool,
  // you just simply call the dispatch method on the
  for (final toolCall in response.toolCalls) {
    // The registry safely casts arguments,
    // which handles missing required fields,
    // and catches internal exceptions.
    final result = await toolRegistry.call(
      toolCall.name,
      toolCall.arguments,
    );

    switch (result) {
      case ToolSuccess(:final value):
        print("Tool returned: $value");
      case ToolError(:final code, :final message):
        print("Tool failed (\$code): \$message");
    }
  }
}
```

--------------------------------

### Running build_runner Commands

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Common `build_runner` commands for generating code. Use `build -d` for a one-shot build that deletes conflicting outputs, or `watch -d` for continuous regeneration during development.

```bash
# One-shot build (delete conflicting outputs automatically with -d):
dart run build_runner build -d

# Watch mode for continuous regeneration during development:
dart run build_runner watch -d

# Works alongside json_serializable in the same file:
# part 'models.g.dart';     ← combined output covers both generators
```

--------------------------------

### Annotate Dart functions with @Tool()

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/README.md

Use the @Tool() annotation on top-level Dart functions to mark them for schema generation. Use @Describe() for detailed parameter descriptions. Remember to declare the part file for the generated code.

```dart
// lib/tools.dart
import 'package:tool_schema_generator/tool_schema_generator.dart';

// IMPORTANT: Declare the part file
part 'tools.g.dart';

/// Sends an email to a specific user.
@Tool()
void sendEmail(
  @Describe('The email address of the recipient') String to,
  @Describe('The subject line of the email') String subject, {
  @Describe('The main body content') required String body,
  bool isHtml = false,
}) {
  // Your logic here
}
```

--------------------------------

### Annotate parameters with @Describe()

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Provide human-readable descriptions for function parameters using the @Describe() annotation. Parameters without this annotation will be included in the schema but will lack a description field.

```dart
import 'package:tool_schema_generator/tool_schema_generator.dart';

part 'tools.g.dart';

/// Sends an email message to the specified recipients.
@Tool(description: 'Composes and sends an email message.')
void sendEmail(
  @Describe('Recipient email address') String to,
  @Describe('Email subject line') String subject,
  @Describe('Email body content') String body, {
  @Describe('CC recipients') List<String>? cc,
}) {}

// Generated schema (tools.g.dart):
//
// const sendEmailToolSchema = <String, dynamic>{
//   'type': 'function',
//   'function': <String, dynamic>{
//     'name': 'sendEmail',
//     'description': 'Composes and sends an email message.',
//     'parameters': <String, dynamic>{
//       'type': 'object',
//       'properties': <String, dynamic>{
//         'to':      <String, dynamic>{'description': 'Recipient email address', 'type': 'string'},
//         'subject': <String, dynamic>{'description': 'Email subject line',      'type': 'string'},
//         'body':    <String, dynamic>{'description': 'Email body content',      'type': 'string'},
//         'cc':      <String, dynamic>{'description': 'CC recipients', 'nullable': true, 'type': 'array', 'items': <String, dynamic>{'type': 'string'}},
//       },
//       'required': <String>['to', 'subject', 'body'],
//     },
//   },
// };
```

--------------------------------

### createUser

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Maps Dart primitive types to JSON Schema. Required parameters are listed in the 'required' array, while optional parameters with defaults or nullable types are omitted.

```APIDOC
## createUser

### Description
Creates a new user account.

### Method
Dart Function (annotated with @Tool())

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (Dart Function Signature)
- **username** (string) - Required - The username for the new account.
- **age** (integer) - Required - The age of the user.
- **score** (number) - Required - The user's score.
- **isAdmin** (boolean) - Optional - Defaults to false. Indicates if the user is an administrator.
- **nickname** (string) - Optional - Nullable. The user's nickname.

### Request Example
```dart
createUser(
  'john_doe',
  30,
  95.5,
  nickname: 'Johnny'
);
```

### Response
This function does not explicitly return a value in the provided documentation, but its schema generation is demonstrated.
```

--------------------------------

### Inject Runtime Parameters into LLM Tool

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/README.md

Use @Inject() for parameters that should not appear in the LLM schema but are needed at runtime. These parameters must be optional (nullable or have a default value).

```dart
@Tool()
Future<void> createTask(
  @Describe('Task title') String title, {
  @Inject() String? userId,
  @Inject() String locale = 'en',
}) async {
  // userId and locale are available here, but only title is in the schema.
}
```

```dart
final result = await toolRegistry.call(toolCall.name, {
  ...toolCall.arguments,
  'userId': currentUser.id,
  'locale': request.locale,
});
```

--------------------------------

### Dispatch LLM Tool Calls in Dart

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/README.md

Use the toolRegistry to dispatch LLM tool calls. It safely parses arguments, calls your Dart function, and handles results, returning either ToolSuccess or ToolError.

```dart
final result = await toolRegistry.call(
  toolCall.name,
  toolCall.arguments
);
```

--------------------------------

### Add tool_schema_generator to dependencies

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/example/README.md

Include `tool_schema_generator` in your project's dependencies and `build_runner` in dev dependencies.

```yaml
dependencies:
  tool_schema_generator: ^0.3.0

dev_dependencies:
  build_runner: ^2.4.0
```

--------------------------------

### Map Dart Primitive Types to JSON Schema

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Demonstrates mapping of Dart primitive types like String, int, double, and bool to their JSON Schema equivalents. Required parameters are listed in the 'required' array, while optional parameters with defaults or nullable types are omitted.

```dart
import 'package:tool_schema_generator/tool_schema_generator.dart';

part 'tools.g.dart';

/// Creates a new user account.
@Tool()
void createUser(
  String username,          // → {"type": "string"}       (required)
  int age,                  // → {"type": "integer"}      (required)
  double score, {
  bool isAdmin = false,     // → {"type": "boolean"}      (optional — has default)
  String? nickname,         // → {"nullable": true, "type": "string"} (optional)
}) {}
```

--------------------------------

### Dart Type Mapping for JSON Schema

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Demonstrates how Dart types like List<T> and Map<String, dynamic> are mapped to JSON Schema equivalents. List<T> becomes an 'array' with 'items' defined by T, while Map variants become 'object' types.

```dart
import 'package:tool_schema_generator/tool_schema_generator.dart';

part 'tools.g.dart';

/// Searches for products matching a query string.
@Tool(name: 'search_products')
List<Map<String, dynamic>> searchProducts(
  @Describe('The search query') String query,
  @Describe('Maximum number of results') int maxResults, {
  bool? includeOutOfStock,
}) => [];

// Generated:
//
// const searchProductsToolSchema = <String, dynamic>{
//   'type': 'function',
//   'function': <String, dynamic>{
//     'name': 'search_products',
//     'description': 'Searches for products matching a query string.',
//     'parameters': <String, dynamic>{
//       'type': 'object',
//       'properties': <String, dynamic>{
//         'query':              <String, dynamic>{'description': 'The search query',          'type': 'string'},
//         'maxResults':         <String, dynamic>{'description': 'Maximum number of results', 'type': 'integer'},
//         'includeOutOfStock':  <String, dynamic>{'nullable': true, 'type': 'boolean'},
//       },
//       'required': <String>['query', 'maxResults'],
//     },
//   },
// };
//
// List<String> example → {"type": "array", "items": {"type": "string"}}
// List<int>    example → {"type": "array", "items": {"type": "integer"}}
```

--------------------------------

### Annotate Dart functions with @Tool()

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Mark top-level Dart functions as LLM-callable tools using the @Tool() annotation. The function's name and doc comment are used for schema generation, but can be overridden.

```dart
// lib/tools.dart
import 'package:tool_schema_generator/tool_schema_generator.dart';

part 'tools.g.dart';

/// Gets the current weather for a given city.
///
/// Returns temperature, humidity, and wind conditions for the requested location.
@Tool()
String getWeather(String city) {
  return '{"temp": 22, "city": "$city"}';
}

// Override both name and description independently of the Dart source:
@Tool(
  name: 'custom_search_tool',
  description: 'Performs a full-text search across the product catalog.',
)
List<Map<String, dynamic>> search(String query) => [];

// Run the generator:
//   dart run build_runner build -d
//
// Generated output in tools.g.dart:
//
// const getWeatherToolSchema = <String, dynamic>{
//   'type': 'function',
//   'function': <String, dynamic>{
//     'name': 'getWeather',
//     'description': 'Gets the current weather for a given city.\n\nReturns temperature, humidity, and wind conditions for the requested location.',
//     'parameters': <String, dynamic>{
//       'type': 'object',
//       'properties': <String, dynamic>{
//         'city': <String, dynamic>{'type': 'string'},
//       },
//       'required': <String>['city'],
//     },
//   },
// };
```

--------------------------------

### getWeather

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Demonstrates mapping of Dart enum types with default values to JSON Schema string enums.

```APIDOC
## getWeather

### Description
Gets weather data in the specified unit.

### Method
Dart Function (annotated with @Tool())

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (Dart Function Signature)
- **city** (string) - Required - The name of the city to look up.
- **unit** (TemperatureUnit) - Optional - Defaults to TemperatureUnit.celsius. The unit for temperature values. Maps to a JSON Schema string enum with values ['celsius', 'fahrenheit', 'kelvin'].

### Request Example
```dart
getWeather('London', unit: TemperatureUnit.fahrenheit);
```

### Response
Returns an empty string. The primary purpose is schema generation demonstration.
```

--------------------------------

### Map Nested Dart Classes to JSON Schema Objects

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Illustrates mapping custom Dart classes to nested JSON Schema objects. The generator introspects the class's constructor to define properties and their types. Circular references are handled with a fallback.

```dart
import 'package:tool_schema_generator/tool_schema_generator.dart';

part 'tools.g.dart';

class GeoLocation {
  final double latitude;
  final double longitude;
  const GeoLocation({required this.latitude, required this.longitude});
}

/// Finds nearby places of interest based on geographic coordinates.
@Tool()
Map<String, dynamic> findNearbyPlaces(
  @Describe('The center point to search around') GeoLocation location,
  @Describe('Search radius in kilometers') double radiusKm, {
  @Describe('Category filter, e.g. restaurant, park') String? category,
}) => {};
```

--------------------------------

### Override Tool Name and Description

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/README.md

Override the default Dart function name and doc comment for a tool's schema using the 'name' and 'description' parameters in the @Tool annotation.

```dart
@Tool(
  name: 'custom_search_tool',
  description: 'A highly specific search tool description.'
)
void search(String query) {}
```

--------------------------------

### findNearbyPlaces

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Maps custom Dart classes (like GeoLocation) to nested JSON Schema objects. Circular references are handled.

```APIDOC
## findNearbyPlaces

### Description
Finds nearby places of interest based on geographic coordinates.

### Method
Dart Function (annotated with @Tool())

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (Dart Function Signature)
- **location** (GeoLocation) - Required - The center point to search around. This is a nested object with 'latitude' (number) and 'longitude' (number) properties, both required.
- **radiusKm** (number) - Required - Search radius in kilometers.
- **category** (string) - Optional - Nullable. Category filter, e.g. restaurant, park.

### Request Example
```dart
findNearbyPlaces(
  GeoLocation(latitude: 40.7128, longitude: -74.0060),
  5.0,
  category: 'restaurant'
);
```

### Response
Returns an empty map. The primary purpose is schema generation demonstration.
```

--------------------------------

### Define Nested Object for LLM Tool Schema

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/README.md

Custom classes are introspected to build nested JSON Schema objects. The generator uses constructor parameters to define the properties of the nested object.

```dart
class Location {
  final double lat;
  final double lng;
  Location({required this.lat, required this.lng});
}

@Tool()
void updateLocation(Location location) {}
```

--------------------------------

### setTaskPriority

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Maps Dart enum types to JSON Schema string enums. The enum's constants are emitted as an 'enum' array.

```APIDOC
## setTaskPriority

### Description
Sets the priority level for a task.

### Method
Dart Function (annotated with @Tool())

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters (Dart Function Signature)
- **taskId** (string) - Required - The task identifier.
- **priority** (Priority) - Required - The desired priority level. Maps to a JSON Schema string enum with values ['low', 'normal', 'high'].

### Request Example
```dart
setTaskPriority('task-123', Priority.high);
```

### Response
This function does not explicitly return a value in the provided documentation, but its schema generation is demonstrated.
```

--------------------------------

### Define Enum for LLM Tool Schema

Source: https://github.com/youssefdawoud-dev/tool_schema_generator/blob/master/README.md

Enums are automatically converted to JSON Schema string enums. This allows LLMs to use predefined string values for tool parameters.

```dart
enum Priority { low, normal, high }

@Tool()
void setTaskPriority(Priority priority) {}
```

--------------------------------

### Map Dart Enum Types to JSON Schema

Source: https://context7.com/youssefdawoud-dev/tool_schema_generator/llms.txt

Shows how Dart enum types are converted to JSON Schema string enums. The generator extracts enum constants into an 'enum' array with 'type': 'string'.

```dart
import 'package:tool_schema_generator/tool_schema_generator.dart';

part 'tools.g.dart';

enum Priority { low, normal, high }
enum TemperatureUnit { celsius, fahrenheit, kelvin }

/// Sets the priority level for a task.
@Tool()
void setTaskPriority(
  @Describe('The task identifier') String taskId,
  @Describe('The desired priority level') Priority priority,
) {}

/// Gets weather data in the specified unit.
@Tool()
String getWeather(
  @Describe('The name of the city to look up') String city, {
  @Describe('The unit for temperature values')
  TemperatureUnit unit = TemperatureUnit.celsius,
}) => '';
```
Tokens:
Raw