A tool description tells a language model what a callable tool does, when to use it, and which inputs it needs. It is part of a structured tool definition sent with a request—not the code that performs the action. Clear descriptions improve tool selection; vague ones can cause a tool to be called at the wrong time or ignored. System-prompt guidance about tool use is a separate, complementary task. section 2.3.2 section 3.2
For a callable function, define:
- A name the model can put in a tool call, plus a description of the tool’s purpose and appropriate use. section 3.2.1
- A parameters object with each input’s name, type, and description; use constraints such as an enum where appropriate. section 3.2.1
- A required list for inputs that must appear in the call. section 3.2.1
Listing 3.1 Calculator tool definition schema
calculator_tool_definition = {
"type": "function",
"function": {
"name": "calculator",
"description": "Perform basic arithmetic operations.",
"parameters": {
"type": "object",
"properties": {
"operator": {
"type": "string",
"description": "Arithmetic operation to perform",
"enum": ["add", "subtract", "multiply", "divide"]
},
"first_number": {
"type": "number",
"description": "First number for the calculation"
},
"second_number": {
"type": "number",
"description": "Second number for the calculation"
}
},
"required": ["operator", "first_number", "second_number"],
}
}
}
The calculator definition shows the outer function declaration, its name and purpose, and a JSON-schema-style parameters object. section 3.2.1
From definition to execution
Given a calculator definition, a capital-city question can receive a direct answer, while “What is 1234 x 5678?” produces a calculator call with `operator="multiply"` and two numbers. The model generates the call; application code executes the function and returns its result to the model for the final answer. Supplying a definition alone does not execute anything. section 3.2.1 section 3.2
Definitions can be generated from Python functions rather than maintained by hand. Read `__name__` and `__doc__` for the name and description; use `inspect.signature` to map annotated parameters to schema types and defaults to optional arguments. Check the generated definition when functions change: a stale manual schema can misrepresent the callable function. section 3.3.2
Listing 3.18 Converting functions to tool definitions
def format_tool_definition(name: str, description: str, parameters: dict) -> dict:
return {
"type": "function",
"function": {
"name": name,
"description": description,
"parameters": parameters,
},
}
def function_to_tool_definition(func) -> dict:
return format_tool_definition(
func.__name__,
func.__doc__ or "",
function_to_input_schema(func)
)
function_to_tool_definition(search_web)
# {'type': 'function', 'function': {'name': 'search_web',
# ➥'description': 'Search the web for the given query.',
# ➥'parameters': {'type': 'object', 'properties':
# ➥{'query': {'type': 'string'}}, 'required': ['query']}}}
The conversion utility assembles a callable function’s name, docstring, and generated input schema into one tool definition. section 3.3.2
A definition also controls exposure. An MCP client can discover names, descriptions, and input schemas from a server, then convert them to an LLM provider’s format. In an agent, a tool whose `tool_definition` is `None` stays off the model’s callable-tool list while still being able to inject memories before a request. section 3.4.3 section 6.4.5
