ToolDefinition

Canonical tool/function definition used across all services

serverId is required on every tool definition. Use "client" as the conventional value for tools you execute — client tools are matched by name, not by server.

parametersJsonSchema is what the model reads to work out how to call your tool. Describe the fields accurately. It is not a validation contract — the platform never checks the model's arguments against it, so treat what arrives as untrusted.

Usage profiles

Usage	Fields and validation
In requests	View fields
In responses	View fields
In webhook payloads	View fields

In requests

API JSON uses JSON field names (camelCase).

Field	Type	Presence	Meaning
name	string	Required in requests	Name used to select and invoke the tool. Minimum length: 1.
description	string	Required in requests	Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1.
parametersJsonSchema	Map from string to JSON value	Optional	JSON Schema object.
metadata	Map from string to string	Optional	Additional tool metadata (version, category, etc.).
serverId	string	Required in requests	Which server provides this tool (for MCP tools). Minimum length: 1.
tags	Array of string	Optional	Tool categorization tags.
documentationUrl	string	Optional	Link to detailed documentation.
outputJsonSchema	Map from string to JSON value	Optional	Optional output schema (JSON Schema serialized as string) describing structured results

Request validation

These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.

Applies to	Rule	Requirement
name	Minimum length	1
description	Minimum length	1
serverId	Minimum length	1

In responses

API JSON uses JSON field names (camelCase).

Field	Type	Presence	Meaning
name	string	Required in requests	Name used to select and invoke the tool.
description	string	Required in requests	Explanation of the tool’s purpose supplied to the model and callers.
parametersJsonSchema	Map from string to JSON value	Optional	JSON Schema object.
metadata	Map from string to string	Optional	Additional tool metadata (version, category, etc.).
serverId	string	Required in requests	Which server provides this tool (for MCP tools).
tags	Array of string	Optional	Tool categorization tags.
documentationUrl	string	Optional	Link to detailed documentation.
outputJsonSchema	Map from string to JSON value	Optional	Optional output schema (JSON Schema serialized as string) describing structured results

Request validation

These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.

Applies to	Rule	Requirement
name	Minimum length	1
description	Minimum length	1
serverId	Minimum length	1

In webhook payloads

Webhook JSON uses protobuf field names (snake_case).

Field	Type	Presence	Meaning
name	string	Required in requests	Name used to select and invoke the tool.
description	string	Required in requests	Explanation of the tool’s purpose supplied to the model and callers.
parameters_json_schema	Map from string to JSON value	Optional	JSON Schema object.
metadata	Map from string to string	Optional	Additional tool metadata (version, category, etc.).
server_id	string	Required in requests	Which server provides this tool (for MCP tools).
tags	Array of string	Optional	Tool categorization tags.
documentation_url	string	Optional	Link to detailed documentation.
output_json_schema	Map from string to JSON value	Optional	Optional output schema (JSON Schema serialized as string) describing structured results

Request validation

These rules apply when this value is supplied in a request. Request validation does not guarantee that response fields are present or satisfy the same rules.

Applies to	Rule	Requirement
name	Minimum length	1
description	Minimum length	1
server_id	Minimum length	1

Where used

Reference	Relationship
Create an agent profile	POST /api/v1/agent-profiles/create
Import a prompt library	POST /api/v1/agent-profiles/import
Update an agent profile	POST /api/v1/agent-profiles/update
Append a message without generating	POST /api/v1/llm/append-message
Create a new conversation thread	POST /api/v1/llm/create-thread
Send a message to a conversation	POST /api/v1/llm/send-message
Send a message and wait for the result	POST /api/v1/llm/send-message-sync
Update context management settings	POST /api/v1/llm/update-context-management-settings
Update default generation config	POST /api/v1/llm/update-default-generation-config
Update the caller's default generation config	POST /api/v1/enduser/update-generation-config
Get an agent profile	POST /api/v1/agent-profiles/get
List agent profiles	POST /api/v1/agent-profiles/list
Withdraw your rating on a message	POST /api/v1/llm/delete-message-rating
Get full conversation state	POST /api/v1/llm/conversation-state
Get detailed MCP server info	POST /api/v1/llm/mcp-get-server-info
List available MCP tools	POST /api/v1/llm/mcp-list-tools
Rate an assistant message	POST /api/v1/llm/rate-message
Submit client-side tool results and wait for the next segment	POST /api/v1/llm/submit-client-tool-results-sync
Get the caller's end-user profile	POST /api/v1/enduser/get
Generation configuration	API JSON uses JSON field names (camelCase).
llm.generation_started	Webhook JSON uses protobuf field names (snake_case).
llm.message_published	Webhook JSON uses protobuf field names (snake_case).
GenerationConfig	Nested in model
GenerationConfig	Nested in model
GenerationConfig	Nested in model
MCPServerInfo	Nested in model

Download the public reference contract.

• agent-profiles OpenAPI
• conversations OpenAPI
• end-users OpenAPI

Document: DOC-API-MODEL-tool-definition.