Reference

Limits

Resource	Limit
Tools per session	20
Parameters per tool	20
Tool name length	1–64 characters
Tool name pattern	^[a-zA-Z_][a-zA-Z0-9_]*$
Tool names	Must be unique within a session
Description length	1–1024 characters
Enum values per string parameter	20
Enum value length	64 characters
Nested properties per object	20
Backend RPC timeout	1–8 seconds (default 4)
Backend RPC handlers per session	1

Reading tool call history

After a session ends, you can read back tool call history from the Conversations API.

The list endpoint includes a hasTools flag on each conversation:

curl https://api.dev.runwayml.com/v1/avatar_conversations \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06"

The detail endpoint includes the full transcript with tool calls and results:

curl https://api.dev.runwayml.com/v1/avatar_conversations/conv_123 \
  -H "Authorization: Bearer $RUNWAYML_API_SECRET" \
  -H "X-Runway-Version: 2024-11-06"

The response includes:

• tools — the tools that were configured for the session (type, name, description)
• transcript — each entry can include:
  • toolCalls — tool invocations on assistant turns: { id, name, arguments }
  • toolResults — results returned: { id, name, result, error, durationMs }
  • content — can be null for tool-only turns where the Character didn’t speak

Example transcript entry with a tool call:

{
  "role": "assistant",
  "content": null,
  "timestamp": "2025-01-15T10:30:00Z",
  "toolCalls": [
    {
      "id": "call_abc123",
      "name": "check_order_status",
      "arguments": { "order_id": "ORD-12345" }
    }
  ],
  "toolResults": [
    {
      "id": "call_abc123",
      "name": "check_order_status",
      "result": { "status": "shipped", "eta": "2025-01-17" },
      "error": null,
      "durationMs": 230
    }
  ]
}

Troubleshooting

Tool not being invoked

Make descriptions specific about the trigger (“when the user asks about…”). You can also add guidance in the Character’s personality field about when to use each tool.

Backend RPC timing out

The default timeout is 4 seconds. Increase timeoutSeconds (max 8) if your handler makes external API calls. If it consistently takes longer, consider pre-fetching or caching.

Backend handler not connecting

Verify RUNWAYML_API_SECRET is set correctly. The session must be in READY or RUNNING status before the handler can connect. Only one backend handler can connect per session.

Client tool events not arriving

Make sure you’re subscribing inside an AvatarCall, AvatarProvider, or AvatarSession component. Check the browser console for WebRTC data channel errors.

Unexpected arguments

Use Standard Schema (Zod) validation with clientTool to catch malformed args at runtime. For backend RPC, validate args in your handler and throw descriptive errors.