DOC-API-MODEL-schema-1gomaj79cc#overview
ToolDefinition
A tool or function the model can request during generation.
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.
Type-reference view: API Schema 9frhv4euve, API Schema 9ftjkkjhfa. Request and response views describe this type; they do not declare an endpoint.
Meaning and usage
Section ID: DOC-API-MODEL-schema-1gomaj79cc#meaning
See the definition above.
Usage profiles
Section ID: DOC-API-MODEL-schema-1gomaj79cc#fields
| Usage | Fields and validation |
|---|---|
| In requests | View fields |
| In responses | View fields |
In requests
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request-field-namename | string | Required in requests | Name used to select and invoke the tool. Minimum length: 1. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request-field-descriptiondescription | string | Required in requests | Explanation of the tool’s purpose supplied to the model and callers. Minimum length: 1. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request-field-parametersjsonschemaparametersJsonSchema | Map from string to JSON value | Optional | JSON Schema object. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request-field-metadatametadata | Map from string to string | Optional | Additional tool metadata (version, category, etc.). |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request-field-serveridserverId | string | Required in requests | Required server identifier. Use client as the conventional value for client-side tools; those tools are matched by name, not by server. Minimum length: 1. |
tags | Array of string | Optional | Tool categorization tags. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request-field-documentationurldocumentationUrl | string | Optional | Link to detailed documentation. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#request-field-outputjsonschemaoutputJsonSchema | Map from string to JSON value | Optional | Optional output schema (JSON Schema serialized as string) describing structured results |
Request validation
Section ID: DOC-API-MODEL-schema-1gomaj79cc#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
Section ID: DOC-API-MODEL-schema-1gomaj79cc#response
API JSON uses JSON field names (camelCase).
| Field | Type | Presence | Meaning |
|---|---|---|---|
Section ID: DOC-API-MODEL-schema-1gomaj79cc#field-nameSection ID: DOC-API-MODEL-schema-1gomaj79cc#response-field-namename | string | Required in requests | Name used to select and invoke the tool. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#field-descriptionSection ID: DOC-API-MODEL-schema-1gomaj79cc#response-field-descriptiondescription | string | Required in requests | Explanation of the tool’s purpose supplied to the model and callers. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#field-parametersjsonschemaSection ID: DOC-API-MODEL-schema-1gomaj79cc#response-field-parametersjsonschemaparametersJsonSchema | Map from string to JSON value | Optional | JSON Schema object. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#field-metadataSection ID: DOC-API-MODEL-schema-1gomaj79cc#response-field-metadatametadata | Map from string to string | Optional | Additional tool metadata (version, category, etc.). |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#field-serveridSection ID: DOC-API-MODEL-schema-1gomaj79cc#response-field-serveridserverId | string | Required in requests | Required server identifier. Use client as the conventional value for client-side tools; those tools are matched by name, not by server. |
tags | Array of string | Optional | Tool categorization tags. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#field-documentationurlSection ID: DOC-API-MODEL-schema-1gomaj79cc#response-field-documentationurldocumentationUrl | string | Optional | Link to detailed documentation. |
Section ID: DOC-API-MODEL-schema-1gomaj79cc#field-outputjsonschemaSection ID: DOC-API-MODEL-schema-1gomaj79cc#response-field-outputjsonschemaoutputJsonSchema | Map from string to JSON value | Optional | Optional output schema (JSON Schema serialized as string) describing structured results |
DOC-API-MODEL-schema-1gomaj79cc#validation
Request validation
Section ID: DOC-API-MODEL-schema-1gomaj79cc#response-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 |
Where used
Section ID: DOC-API-MODEL-schema-1gomaj79cc#where-used
| Reference | Relationship |
|---|---|
| Create an agent profile | POST /api/v1/agent-profiles/create |
| Get an agent profile | POST /api/v1/agent-profiles/get |
| Import a prompt library | POST /api/v1/agent-profiles/import |
| List agent profiles | POST /api/v1/agent-profiles/list |
| Update an agent profile | POST /api/v1/agent-profiles/update |
| 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 |
| Send a message and wait for the result | POST /api/v1/llm/send-message-sync |
| Submit client-side tool results and wait for the next segment | POST /api/v1/llm/submit-client-tool-results-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 |
| Get the caller's end-user profile | POST /api/v1/enduser/get |
| 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 |
| Update the caller's default generation config | POST /api/v1/enduser/update-generation-config |
| ReceiveMessageRequest | API JSON uses JSON field names (camelCase). |
| ClientToolDispatch | API JSON uses JSON field names (camelCase). |
Models containing this value
| Model | Relationship |
|---|---|
| GenerationConfig | Nested in model |
| GenerationConfig | Nested in model |
| MCPServerInfo | Nested in model |
Download the public reference contract.
Document ID: DOC-API-MODEL-schema-1gomaj79cc