Built-in Tools

ModelRelay provides server-side tools that execute on the platform rather than requiring client implementation. When the model calls these tools, ModelRelay handles execution and returns results automatically.

Quick Reference

Tool	Purpose	Context Required
`kv.write`	Store key-value data	Run or Session
`kv.read`	Retrieve stored values	Run or Session
`kv.list`	List all stored keys	Run or Session
`kv.delete`	Remove stored values	Run or Session
`tasks.write`	Track task progress	Run or Session
`image_generation`	Generate images	None
`web_search`	Search the web	None
`web_fetch`	Fetch web pages	None

KV Tools

KV tools provide persistent key-value storage scoped to a run or session context.

kv.write

Store a string value under a namespaced key.

Tool Definition:

{
  "type": "function",
  "function": {
    "name": "kv.write",
    "description": "Store a value in persistent storage",
    "parameters": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Namespaced key (e.g., 'cache/result', 'user/preferences')"
        },
        "value": {
          "type": "string",
          "description": "Value to store (max 32KB)"
        }
      },
      "required": ["key", "value"]
    }
  }
}

Arguments:

Field	Type	Required	Description
`key`	string	Yes	Storage key. Pattern: `[A-Za-z0-9][A-Za-z0-9_.-](/[A-Za-z0-9][A-Za-z0-9_.-])*`. Max 128 bytes.
`value`	string	Yes	Value to store. Max 32KB.

Result:

{"ok": true}

Errors:

Condition	Error
Invalid key format	`kv.write key must be namespaced (segments separated by /, using [A-Za-z0-9_.-])`
Key too long	`kv.write key exceeds 128 bytes`
Value too large	`kv value exceeds 32768 bytes`
Total storage exceeded	`kv exceeds 131072 bytes`
Too many keys	`kv exceeds 256 keys`
No context	`kv.write requires run or session context`

kv.read

Retrieve a value by key.

Tool Definition:

{
  "type": "function",
  "function": {
    "name": "kv.read",
    "description": "Retrieve a value from persistent storage",
    "parameters": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Key to retrieve"
        }
      },
      "required": ["key"]
    }
  }
}

Arguments:

Field	Type	Required	Description
`key`	string	Yes	Key to retrieve

Result (found):

{"found": true, "value": "stored value here"}

Result (not found):

{"found": false}

kv.list

List all stored keys in alphabetical order.

Tool Definition:

{
  "type": "function",
  "function": {
    "name": "kv.list",
    "description": "List all keys in persistent storage",
    "parameters": {
      "type": "object",
      "properties": {},
      "additionalProperties": false
    }
  }
}

Arguments: None

Result:

{"keys": ["analysis/summary", "cache/api-response", "user/preferences"]}

kv.delete

Remove a key from storage.

Tool Definition:

{
  "type": "function",
  "function": {
    "name": "kv.delete",
    "description": "Delete a key from persistent storage",
    "parameters": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string",
          "description": "Key to delete"
        }
      },
      "required": ["key"]
    }
  }
}

Arguments:

Field	Type	Required	Description
`key`	string	Yes	Key to delete

Result:

{"ok": true, "deleted": true}

If the key didn’t exist:

{"ok": true, "deleted": false}

Tasks Tool

tasks.write

Update the task list to track progress on multi-step work.

Tool Definition:

{
  "type": "function",
  "function": {
    "name": "tasks.write",
    "description": "Update the task list",
    "parameters": {
      "type": "object",
      "properties": {
        "tasks": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "content": {
                "type": "string",
                "description": "Task description"
              },
              "status": {
                "type": "string",
                "enum": ["pending", "in_progress", "completed"],
                "description": "Task status"
              }
            },
            "required": ["content", "status"]
          },
          "description": "Complete task list (replaces existing)"
        }
      },
      "required": ["tasks"]
    }
  }
}

Arguments:

Field	Type	Required	Description
`tasks`	array	Yes	Array of task objects
`tasks[].content`	string	Yes	Task description
`tasks[].status`	string	Yes	One of: `pending`, `in_progress`, `completed`

Result:

{"ok": true}

Note: The entire task list is replaced on each call. To update a single task, include the full list with the updated task.

Storage Context

KV and tasks tools require either a run context or session context to store data.

Session Context

Pass session_id in the request to enable session-scoped storage:

{
  "model": "claude-sonnet-4-5",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "input": [...],
  "tools": [...]
}

Session storage:

Persists across multiple requests with the same session_id
Stored in session metadata under modelrelay.kv and modelrelay.tasks
Survives session updates and continues until session deletion

Run Context

For workflow runs, storage is automatically scoped to the run:

KV data stored in run_memory.v0 artifact
Tasks stored in run_tasks.v0 artifact
kv_updated and task_list_updated events emitted

Storage Limits

Limit	Value
Max key length	128 bytes
Max value size	32 KB
Max total storage	128 KB
Max keys	256

Image Generation Tool

The image_generation tool is documented in the Responses API reference.

Web Tools

Server-side web tools for searching and fetching web content. These execute on ModelRelay’s servers using Jina AI.

Note: These are different from the provider-level web tool type documented in Tool Use. Server-side web tools work in agentic workflows and execute automatically when called.

web_search

Search the web for information.

Tool Definition:

{
  "type": "function",
  "function": {
    "name": "web_search",
    "description": "Search the web for information",
    "parameters": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string",
          "description": "Search query"
        },
        "num_results": {
          "type": "integer",
          "description": "Number of results to return (default: 5)"
        },
        "site": {
          "type": "string",
          "description": "Limit search to a specific domain (e.g., 'docs.example.com')"
        }
      },
      "required": ["query"]
    }
  }
}

Arguments:

Field	Type	Required	Description
`query`	string	Yes	Search query
`num_results`	integer	No	Number of results to return
`site`	string	No	Limit search to a specific domain

Result:

{
  "results": [
    {
      "title": "Example Page Title",
      "url": "https://example.com/page",
      "snippet": "A brief excerpt from the page content..."
    }
  ]
}

Errors:

Code	Condition
`WEB_SEARCH_UNAVAILABLE`	Web search service unavailable
`WEB_SEARCH_FAILED`	Search request failed

web_fetch

Fetch and extract content from a web page.

Tool Definition:

{
  "type": "function",
  "function": {
    "name": "web_fetch",
    "description": "Fetch and extract content from a web page",
    "parameters": {
      "type": "object",
      "properties": {
        "url": {
          "type": "string",
          "description": "URL to fetch"
        },
        "max_length": {
          "type": "integer",
          "description": "Maximum content length to return"
        }
      },
      "required": ["url"]
    }
  }
}

Arguments:

Field	Type	Required	Description
`url`	string	Yes	URL to fetch
`max_length`	integer	No	Maximum content length to return

Result:

Returns the extracted text content from the page as a string.

Errors:

Code	Condition
`WEB_FETCH_UNAVAILABLE`	Web fetch service unavailable
`WEB_FETCH_FAILED`	Fetch request failed

Example: Using KV Tools

curl -X POST https://api.modelrelay.ai/api/v1/responses \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "session_id": "your-session-id",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{"type": "text", "text": "Store the result of your analysis for later"}]
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "kv.write",
          "description": "Store a value in persistent storage",
          "parameters": {
            "type": "object",
            "properties": {
              "key": {"type": "string"},
              "value": {"type": "string"}
            },
            "required": ["key", "value"]
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "kv.read",
          "description": "Retrieve a value from persistent storage",
          "parameters": {
            "type": "object",
            "properties": {
              "key": {"type": "string"}
            },
            "required": ["key"]
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "kv.list",
          "description": "List all keys in persistent storage",
          "parameters": {
            "type": "object",
            "properties": {}
          }
        }
      },
      {
        "type": "function",
        "function": {
          "name": "kv.delete",
          "description": "Delete a key from persistent storage",
          "parameters": {
            "type": "object",
            "properties": {
              "key": {"type": "string"}
            },
            "required": ["key"]
          }
        }
      }
    ]
  }'

Example: Using Tasks Tool

curl -X POST https://api.modelrelay.ai/api/v1/responses \
  -H "Authorization: Bearer mr_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "session_id": "your-session-id",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [{"type": "text", "text": "Plan and track your progress on refactoring the auth module"}]
      }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "tasks.write",
          "description": "Update the task list to track progress",
          "parameters": {
            "type": "object",
            "properties": {
              "tasks": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "content": {"type": "string"},
                    "status": {"type": "string", "enum": ["pending", "in_progress", "completed"]}
                  },
                  "required": ["content", "status"]
                }
              }
            },
            "required": ["tasks"]
          }
        }
      }
    ]
  }'

Next Steps

Stateful Tools Guide — Patterns and best practices
Sessions — Multi-turn conversation management
Responses API — Full request/response reference