agent-as-model

Overview Schema Source Related Servers Discussions Admin

messages_create

Instructions

Generate a completion from an Anthropic messages-shaped request. The completion is produced by the host agent's own model: direct MCP sampling on pre-2026-07-28 connections, an MRTR InputRequiredResult carrying the request payload on 2026-07-28+. When output_schema is given, the request carries exactly one required tool whose input schema is that schema, and the validated structured completion is returned as JSON text. When tools is given, the tool definitions are forwarded to the host's model with tool_choice, but only if the host advertised the sampling.tools capability: otherwise the tools are dropped (a warning is logged server-side) and the call degrades to a plain-text completion. When the host answers by calling tools, the returned text is JSON: {"text": "...", "tool_calls": [{"id": "...", "input": {...}, "name": "..."}]} (keys sorted). A plain-text host answer returns text as before. tools and output_schema cannot be combined. An optional persona {name, input_schema, output_schema} registers a per-call contract: the request arguments are validated against input_schema before anything is sent, and the host's completion text must parse as JSON validating against output_schema. The server is stateless and keeps no persona registry. persona.output_schema and output_schema cannot be combined. Session cursors: the server keeps no session state. To continue a conversation, pass the accumulated history back in and the previous turn's cursor as previous_response_id: '' starts a cursor chain (nothing verified), 'cur_<64 hex>' continues a verified chain (checked against the history passed back; mismatch fails loud naming expected vs received), 'resp_<32 hex>' (a responses_create response id) anchors a new chain at the passed history. When previous_response_id is given, the completion returns as JSON '{"completion": "", "response_id": "cur_<...>"}' instead of plain text; when omitted the tool returns plain text exactly as before. The cursor is 'cur_' + sha256 over canonical JSON '{"model","tool","transcript"}' (sorted keys, compact separators), the transcript being the conversation through the assistant turn, so the caller can recompute it. Re-supply previous_response_id on the MRTR retry round on 2026-07-28+ connections, like persona. No API key is used or needed: the connected agent is the model.

Input Schema

Name	Required	Description	Default
`model`	No	Model alias; agent-default means the host's own model.	agent-default
`tools`	No	Optional tool definitions to forward to the host's model. Each is {name, description, input_schema} where input_schema is a JSON Schema object with root type 'object'. Forwarded only when the host advertised the sampling.tools capability; otherwise dropped with a server-side warning and the call degrades to plain text.
`system`	No	System prompt as text or text blocks.
`persona`	No	Optional persona contract for this call: {name, input_schema, output_schema}. name is required and non-empty; the server is stateless and keeps no persona registry. When input_schema is given, the request arguments (messages, model, system, temperature, max_tokens, output_schema, tools, tool_choice, previous_response_id) are validated against it before anything is sent. When output_schema is given, the host's completion text must parse as JSON validating against it. persona.output_schema and output_schema cannot be combined.
`messages`	Yes	User/assistant messages in order.
`max_tokens`	No	Maximum tokens to generate.
`temperature`	No	Sampling temperature, if the host honors it.
`tool_choice`	No	Optional tool-choice mode, forwarded with tools; defaults to 'auto' when tools are given.
`output_schema`	No	Optional JSON Schema (root type object). When given, the sampling request carries exactly one required tool with this input schema and the completion is validated against it before returning.
`previous_response_id`	No	Optional session cursor for host-owned multi-turn continuations. The server keeps no session state: pass the accumulated history back in messages and the previous turn's cursor here. '' starts a cursor chain (nothing verified); 'cur_<64 hex>' continues a verified chain, checked against the history passed back (mismatch fails loud, naming expected vs received); 'resp_<32 hex>' (a responses_create response id) anchors a new chain at the passed history. When given, the completion returns as JSON '{"completion": "<text>", "response_id": "cur_<...>"}' instead of plain text; when omitted the tool returns plain text exactly as before.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedv0.1.2Oct 22, 2026

addedInput schema / $defs / Persona

Added value: +{
+  "description": "A host-registered persona contract for one completion call.\n\nThe server is stateless: it keeps no persona registry. The host supplies\nthe persona per call as a plain dict, and the server validates the call\nagainst it. `input_schema` constrains the tool's request arguments (see\n`_validate_persona_request` for the exact per-tool shape); `output_schema`\nconstrains the host's completion text, which must parse as JSON validating\nagainst it. Both schemas follow the same shape as `output_schema`: a JSON\nSchema object with root type \"object\".",
+  "properties": {
+    "input_schema": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Input Schema"
+    },
+    "name": {
+      "title": "Name",
+      "type": "string"
+    },
+    "output_schema": {
+      "anyOf": [
+        {
+          "additionalProperties": true,
+          "type": "object"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Output Schema"
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "title": "Persona",
+  "type": "object"
+}

addedInput schema / $defs / ToolDefinition

Added value: +{
+  "description": "One caller-defined tool to forward to the host's model.\n\nCallers pass these as plain dicts; the server validates them before they\ntravel anywhere. `input_schema` follows the MCP Tool inputSchema shape: a\nJSON Schema object with root type \"object\".",
+  "properties": {
+    "description": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": null,
+      "title": "Description"
+    },
+    "input_schema": {
+      "additionalProperties": true,
+      "title": "Input Schema",
+      "type": "object"
+    },
+    "name": {
+      "title": "Name",
+      "type": "string"
+    }
+  },
+  "required": [
+    "name",
+    "input_schema"
+  ],
+  "title": "ToolDefinition",
+  "type": "object"
+}

addedInput schema / properties / output_schema

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional JSON Schema (root type object). When given, the sampling request carries exactly one required tool with this input schema and the completion is validated against it before returning.",
+  "title": "Output Schema"
+}

addedInput schema / properties / persona

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/Persona"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional persona contract for this call: {name, input_schema, output_schema}. name is required and non-empty; the server is stateless and keeps no persona registry. When input_schema is given, the request arguments (messages, model, system, temperature, max_tokens, output_schema, tools, tool_choice, previous_response_id) are validated against it before anything is sent. When output_schema is given, the host's completion text must parse as JSON validating against it. persona.output_schema and output_schema cannot be combined."
+}

addedInput schema / properties / previous_response_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional session cursor for host-owned multi-turn continuations. The server keeps no session state: pass the accumulated history back in messages and the previous turn's cursor here. '' starts a cursor chain (nothing verified); 'cur_<64 hex>' continues a verified chain, checked against the history passed back (mismatch fails loud, naming expected vs received); 'resp_<32 hex>' (a responses_create response id) anchors a new chain at the passed history. When given, the completion returns as JSON '{\"completion\": \"<text>\", \"response_id\": \"cur_<...>\"}' instead of plain text; when omitted the tool returns plain text exactly as before.",
+  "title": "Previous Response Id"
+}

addedInput schema / properties / tool_choice

Added value: +{
+  "anyOf": [
+    {
+      "enum": [
+        "auto",
+        "required",
+        "none"
+      ],
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional tool-choice mode, forwarded with tools; defaults to 'auto' when tools are given.",
+  "title": "Tool Choice"
+}

addedInput schema / properties / tools

Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "$ref": "#/$defs/ToolDefinition"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Optional tool definitions to forward to the host's model. Each is {name, description, input_schema} where input_schema is a JSON Schema object with root type 'object'. Forwarded only when the host advertised the sampling.tools capability; otherwise dropped with a server-side warning and the call degrades to plain text.",
+  "title": "Tools"
+}

First observedv0.1.1Oct 18, 2026

TDQS

A4/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the transport (direct MCP sampling vs MRTR InputRequiredResult on 2026-07-28+), capability-gated degradation when sampling.tools is absent (tools silently dropped with a server-side warning), statelessness (no persona or session registry), fail-loud cursor verification with expected-vs-received naming, and that no API key is required. These are exactly the non-obvious behaviors an agent needs before calling.

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

Conciseness3/5

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

The purpose is front-loaded, but the body is a single unbroken wall of text covering transport, tools, persona, and cursors with no headings or grouping, making it hard to scan. The previous_response_id mechanics and return-format rule are restated in both the description and the schema, which is avoidable redundancy.

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?

For a 10-parameter tool with an output schema, complex conditional modes, and no annotations, the description covers everything an agent needs: validation timing, return shape changes (JSON with completion/response_id vs plain text vs tool_calls JSON), retry-round re-supply of previous_response_id and persona, and incompatibility rules. Nothing material is left to inference.

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 100%, so the baseline is 3, but the description adds value the schema does not: it states the mutual-exclusion constraints (tools and output_schema cannot be combined; persona.output_schema and output_schema cannot be combined) and the exact cursor derivation (sha256 over canonical JSON of model/tool/transcript) so a caller can recompute it. Some of the previous_response_id prose duplicates the schema's own description rather than extending it.

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

Purpose4/5

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

States a specific verb and resource: 'Generate a completion from an Anthropic messages-shaped request', and immediately clarifies the model producing it is the host agent's own. The Anthropic-message shape is a genuine distinguishing trait, but the description never names or contrasts with the sibling tools (chat_complete, responses_create, generate), so an agent must infer which completion endpoint to pick.

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

Usage Guidelines3/5

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

The description gives extensive conditional guidance for modes (tools, output_schema, persona, previous_response_id) and their mutual exclusions, which helps an agent choose how to call it. However, it offers no guidance on when to choose this tool over chat_complete, responses_create, or generate; usage relative to alternatives is only implied by the 'Anthropic messages-shaped' phrasing.

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

Deploy Server