Building a tool description from a function
This is the idea behind tool calling: the function's name, docstring and hints become a JSON description. Real libraries do the same with more detail. The two import lines load toolboxes that come with Python (Topic 6.1). inspect.getdoc returns the docstring text, and json.dumps(x, indent=2) prints nested data as indented JSON. The last two lines show that an annotation on a plain variable, like x: int, is stored too.
A docstring documents what a function does, and type hints (annotations) document what types its parameters and result should be. Python stores both on the function, shows them in help(), and lets tools read them, but it does not enforce the hints when the code runs.
Change the code and press Run (Ctrl+Enter). Predict what will happen first, then break it on purpose and read what changes. Your edits are saved and match the lesson page.
Ready for more? This phase has 6 hands-on exercises with automatic checks.
Practice questions
Write the code in the editor, run it, then open the model answer to compare.
Add a docstring and hints to def volume(length, width, height): return length * width * height. Print volume.__doc__ and volume.__annotations__.
Write describe_person(name: str, age: int = 0) -> str with a one-line docstring. Use inspect.signature to print its signature.
Show that a hint is not enforced: call a function annotated with int using a string and print the result.
Explain it without notes
What is a docstring and where does Python store it?
What do type hints do at run time?
Why write type hints if Python does not enforce them?
How can code read a function's hints, and why does that matter for AI tools?
Expected output
(city: str, units: str = 'celsius') -> str
{
"name": "get_weather",
"description": "Return a short weather report for a city.",
"parameters": {
"city": "str",
"units": "str"
},
"required": [
"city"
]
}
not an int - {'x': <class 'int'>}