Skip to main content
Glama

ai_complete

Call a platform AI model for a project. ai_catalog lists current models and prices; docs({topic:"sw.ai"}) explains the full contract.

With neither provider nor model, the call uses free gpt-6-luna: 10 requests/minute and 200/day per project owner on every plan, 8,192 estimated input tokens including system/tools/history, and at most 1,024 output tokens. Standard service, reasoning disabled, 20-second provider deadline including the body. No paid fallback, BYOK charge, or automatic paid repair.

Explicit provider/model selection uses that model's normal billing path, including explicitly selecting gpt-6-luna. Included workers-ai models retain their separate limits. ai_catalog lists the valid model IDs.

messages is a JSON-stringified array of {role,content}. For text use result.text; result.content contains text/tool_use blocks. With response_schema, the result carries result.parsed and result.parse_error. Paid OpenAI/Anthropic responses may report pending cost: unknown is not zero, and repeating a successful model call does not settle accounting.

Tool-capable models accept Anthropic-shaped tool definitions and tool_result messages. A caller-chosen conversation_id together with subject_type and subject_id retains history under that scope; that caller key continues the conversation on later ai_complete calls. ai_conversation_list, ai_conversation_delete, and ai_conversation_fork take the same scope. Later turns send only new messages. History works across supported providers. Free-default overflow truncates history for the request and never runs paid summarization. For larger conversations and explicit paid compaction read docs({topic:"sw.ai"}).

Structured output: pass response_schema as a JSON-stringified JSON Schema, without caller tools or streaming.

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": {
      "project_id": "<project_id>",
      "messages": "<messages>"
    },
    "name": "ai_complete"
  }
}

Input Schema

NameRequiredDescriptionDefault
modelNoOptional concrete model ID or alias from ai_catalog. Explicit selection uses the paid path unless cataloged as included.
toolsNoOptional JSON-stringified Anthropic tool definitions. Passed through unchanged.
systemNoOptional system prompt
messagesYesJSON-stringified array of {role, content} messages. content is a string OR Anthropic content-block array (for tool_result multi-turn).
providerNoOptional provider from ai_catalog. Omission of both provider and model selects free starter chat. Explicit providers use their normal pricing.
compactionNoOptional truncate (default) or summarize. Free default always truncates; explicit paid summarization can incur an additional model charge. Details: docs sw.ai.
max_tokensNoOptional output-token budget, default 1024. Free default capped at 1024; explicit models have their catalog limits.
project_idYesProject ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them).
subject_idNoRequired with conversation_id. Conversation owner id. Conversation reads take the same scope.
tool_choiceNoOptional JSON-stringified Anthropic tool_choice directive (e.g. {"type":"auto"} or {"type":"tool","name":"fs_search"}).
subject_typeNoRequired with conversation_id. Conversation owner type; 'app_user' is for signed-in app users. Conversation reads take the same scope.
conversation_idNoOptional caller-chosen chat key (any string up to 128 chars). The same key on later ai_complete calls loads prior turns. Reading, deleting or forking the saved record takes the id that ai_conversation_list returns when called without conversation_id.
response_schemaNoOptional JSON-stringified JSON Schema. The response exposes parsed and parse_error. This field cannot combine with tools or stream; the free default makes no repair request.
history_max_tokensNoOptional retained-history token budget (estimated), default 32000. New messages/system are counted against the overall input cap too.
history_max_messagesNoOptional. Cap on the number of stored history messages prepended on this call. Oldest dropped first. Default 50. Only applies when conversation_id is set.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Adds substantial behavior beyond the annotations: concrete free-tier limits (10 requests/minute, 200/day, 8,192 input / 1,024 output tokens, 20-second provider deadline), the fact that there is no paid fallback or automatic repair, and that explicitly selecting gpt-6-luna bills normally. It also discloses cost-accounting caveats (unknown is not zero) and that free-default overflow silently truncates history rather than running paid summarization.

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

Conciseness4/5

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

Front-loads the purpose and the free-default behavior before the caveats, which is the right ordering for an agent. It is long and a few points are restated (the paid path and the docs({topic:"sw.ai"}) pointer appear more than once), so it is dense but slightly redundant rather than lean.

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

Completeness5/5

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

There is no output schema, so the description carries the return-value burden and does: result.text, result.content blocks, and result.parsed/parse_error under response_schema. For a 15-parameter tool with billing, history, and structured-output concerns, nothing an agent needs in order to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is already 100%, so the baseline is 3; the description still adds real semantics, such as the coupling of conversation_id with subject_type/subject_id, later turns sending only new messages, and response_schema being JSON-stringified and incompatible with tools/streaming. The per-parameter meaning is largely carried by the schema, but the cross-parameter behavioral rules are genuinely additive.

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?

States a specific verb and resource — calling a platform AI model for a given project — and immediately routes the reader to ai_catalog for model/price discovery and docs for the contract. An agent can distinguish this from ai_generate_image, ai_tts, and ai_conversation_list without opening a schema.

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

Usage Guidelines4/5

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

Gives explicit selection logic: omitting both provider and model selects the free gpt-6-luna starter path, while explicit selection uses that model's normal billing path. It also names the sibling tools for model discovery and contract details. It does not, however, tell an agent when to prefer a different sibling (e.g., image or TTS tools) for non-text tasks, so the routing is strong but not exhaustive.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources