Converra

Create Run

create_run

Create a new run record from a real user/AI dialogue transcript. REQUIRED FOR OPTIMIZATION: You must upload runs before running trigger_optimization - optimization analyzes these dialogues to improve the prompt.

IMPORTANT: The content must contain actual back-and-forth dialogue between a user and AI assistant - NOT system prompts, instructions, or configuration text.

You can either:

Use an existing prompt: provide promptId
Auto-create a new prompt: provide prompt + promptName + llmModel

When auto-creating, the prompt will be created and activated automatically before the run is logged.

TOOL USAGE: If the agent had tools available or made tool calls, pass toolDefinitions (tools available) and toolCalls (calls actually made, with arguments and results) so Converra can grade tool selection and results.

Input Schema

Name	Required	Description
`prompt`	No	The system prompt content (for auto-create). If provided with promptName and llmModel, a new prompt will be created automatically.
`status`	No	Run status (default: completed)
`agentId`	No	The agent ID this run is associated with. Required unless using auto-create (prompt + promptName + llmModel)
`content`	Yes	The full run transcript with alternating user and AI messages. Format: Use 'User:' and 'AI:' (or 'Assistant:') labels. Example: User: Hi, I need help with my order AI: Hello! I'd be happy to help. Could you provide your order number? User: It's #12345 AI: Thanks! I found your order. What seems to be the issue? DO NOT submit system prompts, prompt instructions, configuration text, or anything that isn't actual user-AI dialogue.
`traceId`	No	Runtime trace ID this run belongs to. Groups it under a trace for lineage (see get_trace_lineage).
`llmModel`	No	LLM model used (e.g., 'gpt-4o'). Required when auto-creating a prompt.
`toolCalls`	No	Tool/function calls the agent actually made, in order. Send these so Converra can evaluate tool selection and results - auto-instrumentation captures tool definitions but not the calls themselves. Each item: { name, arguments, result?, id? }.
`customerId`	No	(Converra superadmin only) Target customer ID to act on behalf of
`promptName`	No	Display name for the auto-created prompt (required when providing prompt content)
`companyName`	No	Name of the company/client in the run (optional)
`parentTraceId`	No	The traceId of the trace that SPAWNED this one (e.g. a design run that spawned this interview). Requires traceId. Immutable once set.
`toolDefinitions`	No	Tools that were available to the agent during this run (ground-truth tool contracts). Lets Converra grade whether the agent reached for the right tools. Each item: { name, description?, parameters? }.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 15, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds real behavioral context beyond them: the content validation constraint (must be genuine dialogue, not system/config text) and the non-obvious side effect that auto-creating a prompt activates it before the run is logged. It does not cover permissions or rate limits, so 4 rather than 5.

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-loaded with the core action and the optimization prerequisite, then organized with clear labeled sections. Some overlap with the schema's own content requirement, but the length is defensible for a 12-parameter workflow tool.

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?

Covers purpose, prerequisite ordering, input-path selection, content validation rules, and the tool-grading rationale for the tool array parameters. No output schema exists, so return values need not be described; an agent has everything required to call this correctly.

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 adds value by explaining the interaction logic between parameters (the two prompt-sourcing paths and the purpose of toolCalls vs toolDefinitions) that the schema documents only per-field, not as a group.

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 ('Create a new run record') and immediately qualifies the source ('from a real user/AI dialogue transcript'). This distinguishes it from the read/list siblings (get_run, list_runs) and from the delete sibling without opening any schema.

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?

Explicitly states the prerequisite for another tool ('You must upload runs before running trigger_optimization') and lays out the two mutually exclusive input paths (existing promptId vs auto-create with prompt/promptName/llmModel). When-to-use and alternatives are fully specified.

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

All Converra tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?