Skip to main content
Glama

Converra

by ai.converra
OverviewDiscussionsAdmin

trigger_optimization

Start a new optimization process for an agent. Returns the optimization process ID.

IMPORTANT PREREQUISITES (optimization will fail without these):

  1. RUNS REQUIRED: The agent must have run transcripts uploaded via create_run. Optimization analyzes real user/AI dialogues to improve the agent - it cannot run without them.

  2. Business context (industry and/or objectives) must be set via sync_context_from_url or update_settings.

You can either:

  1. Use an existing agent: provide agentId

  2. Auto-create a new agent: provide prompt + agentName + llmModel

When auto-creating, the agent will be created and activated automatically before optimization starts. NOTE: Even with auto-create, you must still upload runs using create_run before triggering optimization.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modeNoOptimization mode: 'validation' for statistical rigor, 'exploratory' for faster iteration (default: exploratory)
intentNoOptional optimization intent to guide the process
promptNoThe agent's system prompt content to optimize. Required if agentId is not provided.
agentIdNoThe ID of an existing agent to optimize. If not provided, use prompt + agentName + llmModel to auto-create.
llmModelNoLLM model for the auto-created agent (e.g., 'gpt-4o', 'claude-sonnet-5-5', 'o1'). Required if using prompt content.
agentNameNoDisplay name for the auto-created agent. Required if using prompt content instead of agentId.
customerIdNo(Converra superadmin only) Target customer ID to act on behalf of
personaIdsNoSpecific persona IDs to test against (use list_personas to find IDs)
variantCountNoNumber of variants to generate and test (default: 3, max: 5)
customVariantsNoCustom variant content to test. Each variant needs either 'content' (full prompt) or 'diff' (unified diff patch applied to baseline).
simulationTypeNoSimulation policy override. Context-grounded modes require eligible runtime context for this exact agent prompt.
agentDescriptionNoOptional description for the auto-created agent.

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 establish a non-read-only, non-destructive mutation. The description adds meaningful behavioral detail beyond that: the sequencing prerequisites, the failure mode when runs are absent, and the auto-activation behavior when an agent is auto-created. It stops short of describing process duration, async/polling behavior, or what the returned ID is used for.

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?

Purpose and return value are front-loaded, then prerequisites are ranked as numbered rules. Slight redundancy: the runs requirement is stated both in prerequisite 1 and repeated in the trailing NOTE, which costs a little tightness without much added clarity.

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, nested-object, zero-required mutation tool with no output schema, the description covers the invocation paths, prerequisites, and the returned ID. It omits how to monitor the started process (though get_optimization_details exists as a sibling), which is a minor gap rather than a blocking one.

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, and the schema already documents all 12 parameters. The description goes beyond it by explaining the conditional relationship between agentId and the prompt/agentName/llmModel group, which is the key parameter-selection decision an agent must make.

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+resource ('Start a new optimization process for an agent') and its primary side effect (returns the optimization process ID). It is clearly distinguished from siblings like stop_optimization, get_optimization_details, and list_optimizations without needing to open 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 lists prerequisites (runs uploaded via create_run; business context via sync_context_from_url or update_settings) and states optimization fails without them. It also enumerates the two invocation paths (existing agentId vs auto-create via prompt+agentName+llmModel) and clarifies that runs are required even for auto-create.

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