Skip to main content
⚙️ Tools Calling

Pawa AI Tools Calling lets you expose safe actions (functions/APIs) that the model can invoke with JSON arguments. Use it to search, query databases, fetch weather, run payments, or orchestrate internal services—while you stay in control of execution and access.

Pawa AI Tool Calling Example
Web Browsing Example

​
When to use Tools Calling

  • You have deterministic operations the model should trigger (search, lookups, CRUD, RAG retrieval)
  • You want grounded answers that incorporate real‑time data
  • You need multi‑step workflows where the model plans, calls tools, and synthesizes results

​
Example use cases

🌦️ Weather & Events

Get today’s weather for a location, then craft user‑facing summaries.

🧾 Account Ops

Access account details by user ID and enforce role‑based checks.

↩️ Post‑order Actions

Issue refunds, re‑ship items, or create tickets after verification.

​
Types of tools in Pawa AI

  • ◆Built‑in tools (pawa_tool) such as web_search_tool and pesa_pay_tool
  • ◆Custom tools you define and pass in the chat request using JSON schema

​
Tools Calling Models in Pawa AI.

Currently we have one tool calling model:
  • pawa-v1-blaze-20250318: A powerful small language model (SLM) optimized for reasoning, complex generation, multimodal, tools understanding, agentic workflow, and advanced knowledge tasks.

​
Built‑in Tools

Pawa provides platform tools you can enable without hosting your own code. Include them in the tools array with type pawa_tool. 
    curl https://api.pawa-ai.com/v1/chat/request \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $PAWA_AI_API_KEY" \
      -d '{
        "model": "pawa-v1-blaze-20250318",
    "tools": [
      { "type": "pawa_tool", "name": "web_search_tool" },
      { "type": "pawa_tool", "name": "pesa_pay_tool" }
    ],
    "messages": [ {"role":"user","content":"Find the latest news about Pawa AI and summarize it."} ]
  }'
  • Built‑in tools are executed by Pawa; you typically receive the final summarized answer without sending a second request.
  • Some tools may accept options; consult the tool’s reference for supported fields.

​
Custom Tools

Custom tools are the tools you define on yourself and send through chat request. This normally has the following steps:
  1. Define the tool in JSON schema
  2. Make a request to the model with the tools it can call
  3. Receive a tool call from the model
  4. Execute your code with the provided arguments
  5. Send a second request including the tool result
  6. Receive the final response (or additional tool calls)

​
Step‑by‑step example on custom tools.

1) Define the tool

Describe your function with JSON Schema. This shapes the arguments the model will produce.

{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "Get current weather by city",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {"type": "string"},
        "unit": {"type": "string", "enum": ["celsius","fahrenheit"], "default": "celsius"}
      },
      "required": ["city"],
      "additionalProperties": false
    }
  }
}
Each tool entry follows a consistent shape. The function object uses JSON Schema to precisely describe the arguments you expect.type: Must be function for custom tools. function.name: Short, unique identifier the model will reference in tool_calls. strict function.description: One sentence describing when to use the tool; critical for good tool selection. function.parameters.type: Usually object (a set of named arguments). properties: Map of argument names to schemas. Use type, description, and constraints (enum, minimum, maxLength, etc.). required: Array of argument names that must be present. tool_choice additionalProperties: Set to false to prevent unexpected fields. Optional fields like default, examples, and format help the model produce better arguments.
2) Send initial request

Provide the tool definition and a user question. The model decides whether to call the tool.

    curl https://api.pawa-ai.com/v1/chat/request \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $PAWA_AI_API_KEY" \
      -d '{
        "model": "pawa-v1-blaze-20250318",
    "tools": [{ "type": "function", "function": { "name": "get_weather", "parameters": { "type": "object", "properties": { "city": {"type":"string"} } , "required": ["city"] } } }],
    "messages": [ {"role": "user", "content": "What is the weather in Dar es Salaam?"} ]
  }'
3) Receive tool call

The assistant replies with tool_calls including the tool name and arguments.

{
  "success": true,
  "message": "Chat request processed successfully",
  "data": {
    "request": [
      {
        "finish_reason": "tool_calls",
        "message": {
          "role": "assistant",
          "content": "In this request, the model has made a tool call, extract the tool call from the response, process it accordingly and return the result",
  "tool_calls": [
    { "id": "call_01", "type": "function", "function": { "name": "get_weather", "arguments": { "city": "Dar es Salaam", "unit": "celsius" } } }
  ]
        }
      }
    ],
    "created": "2025-09-25",
    "model": "pawa-v1-blaze-20250318",
    "object": "chat.request"
  }
}
4) Execute your code

Your backend runs the function safely and prepares a compact JSON result.

async function getWeather({ city, unit = "celsius" }) {
  // Replace with a real API
  return { city, unit, temp_c: 28, condition: "Sunny" };
}
5) Send tool result back

Post a follow‑up message with role tool, the tool name, and the JSON output.

    curl https://api.pawa-ai.com/v1/chat/request \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $PAWA_AI_API_KEY" \
      -d '{
        "model": "pawa-v1-blaze-20250318",
    "messages": [
      {"role":"user","content":"What is the weather in Dar es Salaam?"},
          {
                        "role": "tool",
                        "name": get_weather,
                        "content": [
                            {"type": "text", "text": str({\"city\":\"Dar es Salaam\",\"unit\":\"celsius\",\"temp_c\":28,\"condition\":\"Sunny\"})},
                            {
                                "type": "text",
                                "text": "Now you have got the answers required by user. Explain this back to the user as it is",
                            }
                        ],
                    }
    ]
  }'
6) Receive final answer

The model grounds its response on the tool output. It may request more tools if needed.

{
  "role": "assistant",
  "content": "In Dar es Salaam it is Sunny at around 28°C."
}

​
Best practices for authoring schemas

  • Use clear, action‑oriented names (e.g., get_weather, refund_order)
  • Write concise descriptions that specify when to use the tool and what it returns.
  • Constrain arguments with enum, ranges, and additionalProperties: false to reduce errors.
  • Prefer simple primitives (string/number/boolean) over deeply nested shapes unless required.
  • Return compact JSON from your tool for the model to reason over; avoid verbose prose.

​
Multiple tools in one request

You can provide several tools at the same time (custom and built‑in). The model may call one or more in sequence, or even in parallel. 
   curl https://api.pawa-ai.com/v1/chat/request \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $PAWA_AI_API_KEY" \
      -d '{
        "model": "pawa-v1-blaze-20250318",
    "tools": [
      { "type": "function", "function": { "name": "get_weather", "parameters": { "type": "object", "properties": { "city": {"type":"string"} }, "required": ["city"] } } },
      { "type": "function", "function": { "name": "get_events", "parameters": { "type": "object", "properties": { "city": {"type":"string"}, "date": {"type":"string", "format": "date"} }, "required": ["city"] } } },
      { "type": "pawa_tool", "name": "web_search_tool" }
    ],
    "messages": [ {"role":"user","content":"I am in Dar es Salaam tomorrow. What should I prepare for?"} ]
  }'
Example tool_calls (parallel): 
{
  "success": true,
  "message": "Chat request processed successfully",
  "data": {
    "request": [
      {
        "finish_reason": "tool_calls",
        "message": {
          "role": "assistant",
          "content": "In this request, the model has made a tool call, extract the tool call from the response, process it accordingly and return the result",
   "tool_calls": [
    { "id": "call_weather", "type": "function", "function": { "name": "get_weather", "arguments": { "city": "Dar es Salaam" } } },
    { "id": "call_events", "type": "function", "function": { "name": "get_events", "arguments": { "city": "Dar es Salaam", "date": "2025-09-12" } } }
  ]
        }
      }
    ],
    "created": "2025-09-25",
    "model": "pawa-v1-blaze-20250318",
    "object": "chat.request"
  }
}
Handle both calls concurrently in your backend, then post two tool messages with the results. The final model message will synthesize both.
With Pawa AI tool calling, you get the most powerful up to date techninique to build advanced agentic AI bot that solves complex problems by using and integrating with the external sources or systems.
⌘I