Skip to main content
Glama
fernandogarzaaa

agent-as-model

by fernandogarzaaa
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

responses_create

Generate a completion from an OpenAI Responses-shaped request, returning the Responses API response object. The completion is produced by the host agent's own model: direct MCP sampling on pre-2026-07-28 connections, an MRTR…

Instructions

Generate a completion from an OpenAI Responses-shaped request, returning the Responses API response object. 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+. input is a string or a list of input items; each item is {role, content} with role user, assistant, system, or developer, and content a string or a list of text parts ({type: 'input_text'|'text', input_text: '...'}). A string input becomes one user message. System and developer items fold into the system prompt alongside instructions, which leads. Non-text parts are rejected. max_tokens is named for uniformity with the other tools (the Responses API calls it max_output_tokens); same meaning. 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 inside the output_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 output array carries the accompanying text as a message item (omitted when empty) followed by one function_call item per call: {type: 'function_call', id: 'fc_', call_id: '', name: '...', arguments: ''}; the host's tool-call id maps to call_id, the object id is derived from it. A plain-text host answer returns a single message item. 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 input and the previous turn's response id 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 previous response id) anchors a new chain at the passed history. The response object's id field IS the cursor: when previous_response_id is given it carries the 'cur_' tamper-evident commitment, when omitted it stays the opaque 'resp_' unique id 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

NameRequiredDescriptionDefault
inputYesThe Responses API input: a string, which becomes one user message, or a list of input items {role, content}. role is user, assistant, system, or developer; content is a string or a list of text parts ({type: 'input_text'|'text', input_text: '...'}). System and developer items fold into the system prompt alongside instructions. Non-text parts are rejected.
modelNoModel alias; agent-default means the host's own model.agent-default
toolsNoOptional 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.
personaNoOptional 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 (input, instructions, model, 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.
max_tokensNoMaximum tokens to generate. Named max_tokens for uniformity with the other tools; the Responses API calls it max_output_tokens.
temperatureNoSampling temperature, if the host honors it.
tool_choiceNoOptional tool-choice mode, forwarded with tools; defaults to 'auto' when tools are given.
instructionsNoOptional system prompt; leads the system/developer items.
output_schemaNoOptional 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_idNoOptional session cursor for host-owned multi-turn continuations. The server keeps no session state: pass the accumulated history back in input and the previous turn's response id 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 previous response id) anchors a new chain at the passed history. When given, the response object's id field carries the 'cur_' cursor; when omitted the id stays the opaque 'resp_' unique id exactly as before.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.1.2

TDQS

A4.4/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: it discloses the transport split (direct MCP sampling vs MRTR InputRequiredResult), silent degradation when sampling.tools is absent (tools dropped, warning logged, plain-text fallback), statelessness, no API key required, and loud-failure semantics for cursor mismatch naming expected vs received.

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?

It is a dense wall of run-on sentences; critical operational constraints (tools+output_schema exclusivity, cursor formats, MRTR resupply of previous_response_id) are buried mid-paragraph rather than front-loaded. Nearly every sentence carries real information, but the lack of structure makes retrieval hard for an agent.

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?

For a complex, stateful-looking-but-stateless sampling tool with no output schema, it covers the mechanics an agent needs: input shaping, capability gating, tool-call output item shapes, and cursor semantics. It stops short of fully describing the returned response envelope (fields besides id/output_text are only implied), leaving some reconstruction to the caller.

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; the description goes beyond it with cross-parameter rules the schema cannot express: tools and output_schema cannot be combined, persona.output_schema and output_schema cannot be combined, system/developer items fold into the prompt behind instructions, and the one-required-tool mechanics of output_schema. Some of this repeats schema text (max_tokens naming rationale, string-to-user-message) rather than adding to it.

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 ('Generate a completion from an OpenAI Responses-shaped request') and the exact return ('the Responses API response object'). The 'Responses-shaped' dialect naming implicitly separates it from the chat-completions and messages-shaped siblings, and the closing line 'the connected agent is the model' sharpens what kind of completion this is.

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 clear context for optional features: when to pass tools (only if host advertised sampling.tools), when to use output_schema (structured completion returned inside output_text), when to use persona, and how to use previous_response_id for continuations. It never explicitly says when to prefer this over chat_complete or messages_create, so sibling routing is left to inference from the API dialect.

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

Deploy Server

Other Tools