Skip to main content
Glama

grok_chat_completions

Send messages to a Grok model to receive OpenAI-compatible chat completions for reasoning, image understanding, or tool/function calling.

Instructions

Create a Grok (xAI) chat completion via the AceDataCloud Grok API.

Sends messages to a Grok chat model and returns the generated response in the
OpenAI-compatible chat completion format.

Use this when:
- You want to chat/reason with a Grok model (grok-4 / grok-3 family)
- You need vision/image understanding
- You need tool/function calling with Grok

For generating videos, use grok_text_to_video / grok_image_to_video instead.

Returns:
    JSON response containing the chat completion result.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "messages": "<messages>"
    },
    "name": "grok_chat_completions"
  }
}

Input Schema

NameRequiredDescriptionDefault
nNoHow many chat completion choices to generate. Default 1.
seedNoRandom seed for (best-effort) deterministic sampling.
stopNoStop sequences where the API will stop generating tokens.
userNoEnd-user identifier for abuse monitoring.
audioNoAudio output configuration when requesting audio modality.
modelNoThe Grok chat model: grok-4.7, grok-4.5, grok-4 (default), or grok-3.grok-4
storeNoWhether to store the output of this chat completion. Default false.
toolsNoList of tools (functions) the model may call.
top_pNoNucleus sampling probability mass. Default 1.
streamNoThis MCP tool returns a complete JSON response. Omit or set false; stream=true is rejected before sending a request.
logprobsNoWhether to return log probabilities of output tokens.
messagesYesConversation messages. Each message is a dict with 'role' ('system'/'user'/'assistant'/'tool') and 'content' keys. Content may be a list of text/image_url parts for image input. Required.
metadataNoDeveloper-defined metadata attached to the request.
logit_biasNoToken logit bias map.
max_tokensNoMaximum number of tokens to generate.
modalitiesNoOutput modalities requested for this response.
predictionNoStatic predicted output content to improve latency.
temperatureNoSampling temperature between 0 and 2. Higher = more random.
tool_choiceNoControls tool calling. 'none', 'auto', 'required', or a dict.
service_tierNoSpecifies the processing tier. Options: 'auto' (default), 'default', 'flex' (asynchronous batch-eligible), 'scale', or 'priority'.
top_logprobsNoNumber of most likely tokens to return at each token position.
stream_optionsNoOptions for streaming responses.
response_formatNoResponse format specification (e.g. {"type": "json_object"}).
presence_penaltyNoPresence penalty between -2.0 and 2.0. Positive increases topic variety.
reasoning_effortNoReasoning effort. Only applies to reasoning-capable models; ignored by non-reasoning models.
frequency_penaltyNoFrequency penalty between -2.0 and 2.0. Positive decreases repetition.
web_search_optionsNoWeb search configuration for search-capable models.
parallel_tool_callsNoWhether to enable parallel tool calls. Default true.
max_completion_tokensNoUpper bound for tokens generated for a completion.

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.12
    • changedInput schema / properties / model / description
      Previous value: -"The Grok chat model: grok-4.5 (default, latest flagship), grok-4 or grok-3."New value: +"The Grok chat model: grok-4.7, grok-4.5, grok-4 (default), or grok-3."
    • changedInput schema / properties / stream / description
      Previous value: -"Whether to stream partial message deltas. Default False."New value: +"This MCP tool returns a complete JSON response. Omit or set false; stream=true is rejected before sending a request."
  2. Changed1 schema field changedv0.1.10
    • changedInput schema / properties / model / enum
      Previous value: -[
      -  "grok-4.5",
      -  "grok-4",
      -  "grok-3"
      -]New value: +[
      +  "grok-4.7",
      +  "grok-4.5",
      +  "grok-4",
      +  "grok-3"
      +]
  3. Changed14 schema fields changedv0.1.6
    • addedInput schema / properties / audio
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Audio output configuration when requesting audio modality.",
      +  "title": "Audio"
      +}
    • addedInput schema / properties / logit_bias
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": {
      +        "type": "integer"
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Token logit bias map.",
      +  "title": "Logit Bias"
      +}
    • addedInput schema / properties / logprobs
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Whether to return log probabilities of output tokens.",
      +  "title": "Logprobs"
      +}
    • addedInput schema / properties / max_completion_tokens
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Upper bound for tokens generated for a completion.",
      +  "title": "Max Completion Tokens"
      +}
    • addedInput schema / properties / metadata
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Developer-defined metadata attached to the request.",
      +  "title": "Metadata"
      +}
    • addedInput schema / properties / modalities
      Added value: +{
      +  "anyOf": [
      +    {
      +      "items": {
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Output modalities requested for this response.",
      +  "title": "Modalities"
      +}
    • addedInput schema / properties / n
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "How many chat completion choices to generate. Default 1.",
      +  "title": "N"
      +}
    • addedInput schema / properties / parallel_tool_calls
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Whether to enable parallel tool calls. Default true.",
      +  "title": "Parallel Tool Calls"
      +}
    • addedInput schema / properties / prediction
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Static predicted output content to improve latency.",
      +  "title": "Prediction"
      +}
    • addedInput schema / properties / service_tier
      Added value: +{
      +  "anyOf": [
      +    {
      +      "enum": [
      +        "auto",
      +        "default",
      +        "flex",
      +        "scale",
      +        "priority"
      +      ],
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Specifies the processing tier. Options: 'auto' (default), 'default', 'flex' (asynchronous batch-eligible), 'scale', or 'priority'.",
      +  "title": "Service Tier"
      +}
    • addedInput schema / properties / store
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Whether to store the output of this chat completion. Default false.",
      +  "title": "Store"
      +}
    • addedInput schema / properties / stream_options
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Options for streaming responses.",
      +  "title": "Stream Options"
      +}
    • addedInput schema / properties / top_logprobs
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "integer"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Number of most likely tokens to return at each token position.",
      +  "title": "Top Logprobs"
      +}
    • addedInput schema / properties / web_search_options
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": true,
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "description": "Web search configuration for search-capable models.",
      +  "title": "Web Search Options"
      +}
  4. Changed5 schema fields changedv0.1.3
    • changedInput schema / properties / messages / description
      Previous value: -"Conversation messages. Each message is a dict with 'role' ('system'/'user'/'assistant'/'tool') and 'content' keys. For vision with grok-2-vision, content may be a list of text/image_url parts. Required."New value: +"Conversation messages. Each message is a dict with 'role' ('system'/'user'/'assistant'/'tool') and 'content' keys. Content may be a list of text/image_url parts for image input. Required."
    • changedInput schema / properties / model / description
      Previous value: -"The Grok chat model. grok-4 (default, flagship) and grok-3 are the broadly available models. Also: grok-4-1-fast, grok-4-1-fast-non-reasoning, grok-3-mini, grok-2-vision (image input) — availability depends on upstream provisioning."New value: +"The Grok chat model: grok-4.5 (default, latest flagship), grok-4 or grok-3."
    • changedInput schema / properties / model / enum
      Previous value: -[
      -  "grok-4",
      -  "grok-4-1-fast",
      -  "grok-4-1-fast-non-reasoning",
      -  "grok-3",
      -  "grok-3-mini",
      -  "grok-2-vision"
      -]New value: +[
      +  "grok-4.5",
      +  "grok-4",
      +  "grok-3"
      +]
    • changedInput schema / properties / reasoning_effort / anyOf
      Previous value: -[
      -  {
      -    "enum": [
      -      "low",
      -      "high"
      -    ],
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "enum": [
      +      "minimal",
      +      "low",
      +      "medium",
      +      "high"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedInput schema / properties / reasoning_effort / description
      Previous value: -"Reasoning effort: 'low' or 'high'. Only applies to reasoning-capable models (e.g. grok-3-mini). Ignored by non-reasoning models."New value: +"Reasoning effort. Only applies to reasoning-capable models; ignored by non-reasoning models."
  5. First observedv0.1.0

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are supplied, so the description carries the full behavioral burden. It discloses the OpenAI-compatible response format and that it sends messages to a Grok model, but it does not mention streaming limitations, authentication, rate limits, or error behavior. For a network-backed LLM call this is adequate but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded, uses short bullets for when-to-use guidance and alternatives, and avoids enumerating the 29 parameters. Every section, including the return note, contributes to selection or invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the large parameter surface, output schema, and lack of annotations, the description covers the essential purpose, alternatives, and response shape. It is not fully complete on operational constraints such as streaming rejection, but that is partly handled by the parameter schema, so a 4 is warranted.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for 29 parameters, so the schema already defines each field in detail. The description adds use-case context for vision/image inputs and tool calling, but it does not add syntax, constraints, or defaults beyond what the schema provides, making baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ("Create a Grok (xAI) chat completion"), states the transport/format, and explicitly routes video generation to sibling tools. It also enumerates core chat, vision, and tool-calling use cases, so an agent can distinguish this from grok_text_to_video and grok_image_to_video without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit "Use this when" conditions for chat/reasoning, vision/image understanding, and tool/function calling, and names grok_text_to_video and grok_image_to_video as alternatives for video generation. The selection logic is clear and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.