Documentation Index
Fetch the complete documentation index at: https://docs.definable.ai/llms.txt
Use this file to discover all available pages before exploring further.
Definable generates a JSON Schema for each tool from its Python type hints. The model uses this schema to understand what arguments to pass.
Type Hints
Standard Python type hints are supported:
from typing import List, Optional
from definable.tool.decorator import tool
@tool
def search(
query: str,
max_results: int = 10,
include_archived: bool = False,
) -> List[str]:
"""Search for documents matching the query.
Args:
query: The search query string.
max_results: Maximum number of results to return.
include_archived: Whether to include archived documents.
"""
return [f"Result for '{query}'"]
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query string."
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return.",
"default": 10
},
"include_archived": {
"type": "boolean",
"description": "Whether to include archived documents.",
"default": false
}
},
"required": ["query"]
}
Supported Types
| Python Type | JSON Schema Type |
|---|
str | string |
int | integer |
float | number |
bool | boolean |
list / List[T] | array |
dict / Dict[str, T] | object |
Optional[T] | T (not required) |
Literal["a", "b"] | string with enum |
Enum | string with enum |
Descriptions from Docstrings
Parameter descriptions are extracted from your docstring. Both Google and NumPy styles are supported:
@tool
def analyze(text: str, language: str = "en") -> dict:
"""Analyze text for sentiment.
Args:
text: The text to analyze.
language: ISO language code for the text.
"""
Pydantic Models as Parameters
For complex inputs, use Pydantic models:
from typing import Optional
from pydantic import BaseModel, Field
from definable.tool.decorator import tool
class SearchFilter(BaseModel):
category: str = Field(description="Document category to filter by")
date_from: Optional[str] = Field(None, description="Start date (YYYY-MM-DD)")
date_to: Optional[str] = Field(None, description="End date (YYYY-MM-DD)")
@tool
def search(query: str, filters: SearchFilter) -> str:
"""Search documents with filters."""
return f"Searching '{query}' in {filters.category}"
Enum Parameters
Use Literal or Enum to restrict values:
from typing import Literal
@tool
def set_priority(task_id: str, priority: Literal["low", "medium", "high"]) -> str:
"""Set the priority of a task."""
return f"Set {task_id} to {priority}"
Default Values
Parameters with default values are optional in the schema:
@tool
def fetch_data(url: str, timeout: int = 30, retries: int = 3) -> str:
"""Fetch data from a URL."""
return f"Fetched from {url}"
url is required. The model can omit timeout and retries.
Validation
When validate_tool_args=True in AgentConfig (the default), arguments are validated against the schema before execution. Invalid arguments result in an error message sent back to the model, which can then correct its call.
