Tool and Function Calling Guide for the Piramyd API

Tool calling lets you describe functions to the model and have it decide when and how to invoke them. Instead of generating free-form text, the model emits a structured tool_calls object with the function name and arguments it wants to call. Your code executes the function, then submits the result back so the model can continue. This pattern is the foundation of most AI agents.

Check Model Support

Not every model supports tool calling. Before sending tools in your request, check that the model’s supports_tools field is true in the GET /v1/models response. Sending tool definitions to a model that doesn’t support them returns a 400 error.

import httpx

models = httpx.get(
    "https://api.piramyd.cloud/v1/models",
    headers={"Authorization": "Bearer sk-YOUR_PIRAMYD_KEY"},
).json()

tool_models = [
    m for m in models["data"]
    if m.get("supports_tools") and "/v1/chat/completions" in m.get("endpoints", [])
]
model_id = tool_models[0]["id"]

Define Tools

Pass a tools array in your request body. Each entry has type: "function" and a function object with a name, description, and a JSON Schema parameters definition.

{
  "model": "claude-opus-4.8",
  "messages": [
    {"role": "system", "content": "You can call tools when needed."},
    {"role": "user", "content": "What's the weather in Lisbon?"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {"type": "string", "description": "City name"}
          },
          "required": ["city"]
        }
      }
    }
  ],
  "tool_choice": "auto"
}

Set tool_choice to control whether and how the model uses tools:

Value	Behaviour
`"auto"` (default)	Model decides whether to call a tool or respond in text
`"none"`	Tool definitions are ignored; model always responds in text
`"required"`	Model must call at least one tool
`{"type": "function", "function": {"name": "get_weather"}}`	Model must call the named function

Full Tool Calling Loop

A complete agent loop has four steps.

Streaming Tool Calls

When stream: true is set, function.arguments arrives as a stream of string fragments across multiple chunks. Accumulate every fragment before calling json.loads — do not parse intermediate chunks.

tool_calls_buffer = {}

with client.chat.completions.stream(
    model="claude-opus-4.8",
    messages=messages,
    tools=tools,
) as stream:
    for chunk in stream:
        for tc in (chunk.choices[0].delta.tool_calls or []):
            idx = tc.index
            if idx not in tool_calls_buffer:
                tool_calls_buffer[idx] = {
                    "id": tc.id,
                    "name": tc.function.name or "",
                    "arguments": "",
                }
            tool_calls_buffer[idx]["arguments"] += tc.function.arguments or ""

# Only parse after the stream completes
for tc in tool_calls_buffer.values():
    args = json.loads(tc["arguments"])  # always valid — Piramyd auto-repairs
    print(tc["name"], args)

Piramyd’s automatic tool call integrity buffers argument deltas server-side, repairs any truncated JSON, and handles continuation if the model hits max_tokens mid-call. You always receive complete, valid JSON — no custom repair logic needed on your side.

Parameters Reference

tool_choice values

Value	Type	Description
`"auto"`	string	Default. Model chooses whether to call a tool.
`"none"`	string	Forces text-only response; tools are ignored.
`"required"`	string	Model must invoke at least one tool.
`{"type": "function", "function": {"name": "..."}}`	object	Forces a specific function to be called.

finish_reason values related to tool calls

Value	Meaning
`"tool_calls"`	The model returned one or more tool calls; no text content.
`"stop"`	Normal text completion; no tool call was made.
`"length"`	Hit `max_tokens`; Piramyd auto-continues mid-call when possible.

Check supports_tools: true on a model before defining any tools, and always verify finish_reason before trying to parse tool_calls. For deeper context on how Piramyd handles large argument payloads during streaming, see the Tool Call Integrity concept page.

Get Started

Core Concepts

Guides

Errors & Reliability

Tool and Function Calling Guide for the Piramyd API

Check Model Support

Define Tools

Full Tool Calling Loop

Streaming Tool Calls

Parameters Reference

​Check Model Support

​Define Tools

​Full Tool Calling Loop

​Streaming Tool Calls

​Parameters Reference

Check Model Support

Define Tools

Full Tool Calling Loop

Streaming Tool Calls

Parameters Reference