Skip to main content
Glama

Converra

by ai.converra
OverviewDiscussionsAdmin

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:

  1. Use an existing prompt: provide promptId

  2. 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

TableJSON Schema
NameRequiredDescriptionDefault
promptNoThe system prompt content (for auto-create). If provided with promptName and llmModel, a new prompt will be created automatically.
statusNoRun status (default: completed)
agentIdNoThe agent ID this run is associated with. Required unless using auto-create (prompt + promptName + llmModel)
contentYesThe 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.
traceIdNoRuntime trace ID this run belongs to. Groups it under a trace for lineage (see get_trace_lineage).
llmModelNoLLM model used (e.g., 'gpt-4o'). Required when auto-creating a prompt.
toolCallsNoTool/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? }.
customerIdNo(Converra superadmin only) Target customer ID to act on behalf of
promptNameNoDisplay name for the auto-created prompt (required when providing prompt content)
companyNameNoName of the company/client in the run (optional)
parentTraceIdNoThe traceId of the trace that SPAWNED this one (e.g. a design run that spawned this interview). Requires traceId. Immutable once set.
toolDefinitionsNoTools 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.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations mark this as a write (readOnlyHint=false) but say nothing about side effects; the description adds that auto-creating a prompt also activates it automatically before the run is logged, which is real behavioral context. It also warns that tool calls are not auto-captured and must be sent explicitly. No info on permissions beyond the schema's superadmin note.

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 core action, then uses short labeled sections (REQUIRED FOR OPTIMIZATION, IMPORTANT, numbered options, TOOL USAGE) to make it scannable. It runs long for a description, but every block carries distinct operational information rather than restating the schema.

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 12-parameter mutation tool with no output schema, the description covers the critical workflows, the optimization prerequisite, the content constraint, and the auto-create side effect. It omits what the created run returns (e.g. run ID), which would help chaining into trigger_optimization.

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, but the description adds the conditional grouping rule (prompt + promptName + llmModel must be supplied together for auto-create) and explains the purpose of toolDefinitions vs toolCalls (tools available vs calls actually made). That is meaning beyond the schema text.

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 from a real user/AI dialogue transcript.' The distinction from siblings is implicit but clear (list_runs/get_run/delete_run/sync_runs are different operations), and the description immediately qualifies the required input shape.

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 ties the tool to its dependent workflow ('you must upload runs before running trigger_optimization'), and lays out two mutually exclusive usage paths (existing promptId vs auto-create with prompt + promptName + llmModel). It also states a hard when-not rule for content: no system prompts, instructions, or configuration text.

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

All Converra toolsInspect
Try in Browser
Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources