Ollama tool calling lets a supported model request a function that your application provides. Send the tool’s description and argument schema with a chat request. When the model requests it, validate the arguments, run the allowed function yourself, and send the resulting tool message back. Begin with a read-only example that works offline and has a known answer.
Choose a tool you can verify without side effects
Start with a function such as looking up a test project’s status in a small in-memory object. Give it one string argument, such as a project identifier. Use three fake records whose answers you already know. Make the function return an explicit result for an unknown ID. This keeps the first experiment focused on message flow and validation. A network service or a file-writing action can introduce errors that have little to do with the tool interface itself.
Pick an installed model whose documentation includes tool calling. Verify the exact tag in your local environment. Our local AI setup guide walks through establishing a working base model. Before introducing a tool, send an ordinary prompt and confirm that the expected process answers. If that fails, check that Ollama is running and that the client is using the intended host. Keep the first test on the local endpoint so you can inspect the request without involving another deployment.
Describe what the function does and accepts
Add a tools array to the native chat request. In a function entry, provide a stable name, a description and an object schema for the arguments. A simple name such as get_project_status works well. Document what an identifier looks like and which fields the function returns. If the arguments are too flexible, the caller will have to guess what the function accepts. Give your application a separate validator even if the tool definition declares the expected types and required fields.
The Ollama tool calling reference shows request and response examples for the native API and SDKs. Start with stream set to false while learning the shape of the messages. Our native chat API guide covers sending a basic request and checking the response. If you use the OpenAI-compatible route instead, follow its documented message format. Do not mix a native tool response with a different endpoint’s conversation format by accident.
Inspect the response before executing anything
Ask for the status of one fake project. Review the assistant message and see whether it contains a tool call. It may instead contain a normal answer. Handle both cases explicitly. If the model proposes a function, compare its name against the functions your application actually exposes. Check that the arguments have the expected shape and that the specific project is allowed in this session. A model request is a suggestion to your code. Your code remains responsible for deciding whether to execute it.
For the first test, reject an unknown name or an invalid argument and report a controlled error. Do not transform an unknown tool name into a shell command or lookup a function dynamically from arbitrary input. Keep a small explicit mapping between declared names and implementations. Test an argument that is missing, one of the wrong type, and one whose value is syntactically valid but unrecognized. Each should produce a predictable result that the application can display or pass back in a limited form.
Return the result and check the final answer
Preserve the assistant message containing the tool call in the conversation history. Run the allowed function and append a tool result using the native message fields documented for your client. Send that conversation back to the model. Check that the final answer agrees with the function’s actual result. If the record says a project is blocked but the answer says it shipped, keep that as a test failure. A successfully executed function does not establish that the model interpreted its result correctly.
Keep the result small and use a consistent format. For example, return the requested ID, a status and an optional explanation from your test data. Do not include other records or private attributes that the response does not need. Treat stored text as data, even if it contains instructions about what to do next. If the model asks to call another function after receiving a result, check whether your design expects that behavior. A simple first prototype can allow one call and then request a final answer.
Add bounded behavior before expanding the workflow
When a workflow needs several calls, cap the number of steps and give slow functions a timeout. Check each requested name and each set of arguments independently. Avoid repeating expensive operations when the model asks the same question again. Decide how the application should handle a partial result, a timeout or a denied request. Test these cases before connecting useful data. A visible error is easier to diagnose than a conversation that appears to run forever.
For workflows that might later make changes, keep permissions and any user approval decisions in application code. Model instructions can help explain the intended behavior, while the application determines who may do what. Keep an audit record with enough information to reconstruct a problem without logging secrets or full private messages. Our Modelfile guide explains why a default system instruction guides output but cannot replace a control enforced by your program.
Evaluate calls and answers separately
Build a few repeatable examples. Include one prompt that should call a tool, one that can be answered without tools and one that refers to an unknown record. Measure whether the model selected the right function, produced acceptable arguments and represented its result accurately. Save the exact model and runtime configuration with those results. If you later choose a different model, our benchmarking guide describes a controlled comparison. Keep the original good and bad examples as regression tests.
For an additional test, make the fake tool return an error without throwing an unhandled exception. Check whether the final answer reports unavailability clearly instead of inventing an outcome. Save the case with your normal successful example and rerun both after changing the model.
Once the read-only example passes, try returning two similar records with clearly different states. Ask a question that names just one record and confirm the assistant uses that identifier throughout. Then ask about the other record in a follow-up. Check the newly selected arguments and the final answer independently. This catches a client that accidentally reuses the first result or mixes messages from different requests. Keep conversation state separate for each user session.
Frequently asked questions
Does Ollama run my application function automatically?
Your application receives the requested call and decides whether to run the implementation. Your code sends the function result back.
What if the model answers without using the tool?
Check model support and improve the tool description. Use an example that requires the lookup and verify whether a structured call appears.
Should I start with streaming?
Start with a complete response to inspect the structure. Add streaming later and test how your client assembles partial tool calls.
