Skip to main content
Glama

start_silicon_sample_run

Destructive

Start a Silicon Sample run with confirm: true: LLM personas answer the survey and their answers are saved as responses labeled silicon_sample, alongside real respondents' data. It spends the configured LLM credential's real API budget. Track it with read_silicon_sample include job or wait. Requires a Pro plan (or a workspace with a Pro owner).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "survey_id": "<survey_id>",
      "confirm": "<confirm>",
      "llm_credential_id": "<llm_credential_id>"
    },
    "name": "start_silicon_sample_run"
  }
}

Input Schema

NameRequiredDescriptionDefault
confirmYesMust be true. Starting a run spends the configured LLM credential's real API budget and writes persona-generated rows into this survey's live response data, alongside genuine respondent submissions.
contextNoFree-text description of the population or extra instructions added to every persona's prompt. Without a panel it defaults to "General survey respondents".
panel_idNoBuild personas from a saved panel's stored respondent records (Panels in the workspace). Cannot be combined with source_survey_id.
parallelNoHow many personas run at the same time (1–16, default 1).
survey_idYesSurvey UUID
column_slotsNoPanel personas only: panel column name → the demographic it holds, so the persona intro can phrase it (e.g. {"Q3_age": "age"}). Slotted columns are left out of the question-and-answer lines.
persona_countNoHow many personas to run (1–5000, default 10); with a panel or earlier survey, the size of the random respondent sample.
save_as_draftNoAlso save these run settings as the survey's shared Silicon Sample draft (default false).
intro_templateNoWith a panel: the persona's opening sentence, with {{column name}} tokens filled from that respondent's record. Blank builds one from column_slots.
include_columnsNoWith a panel: the panel column names to describe each persona with (default every stored column).
prompt_overridesNoGlobal template overrides; omit fields to retain defaults
qa_line_templateNoHow each remaining answer is written into the persona, with {{question}} and {{answer}} tokens. Default: To the question "{{question}}," you responded, "{{answer}}."
source_survey_idNoBuild personas from the responses to an earlier survey (read_survey lists surveys). Requires source_question_ids; cannot be combined with panel_id.
llm_credential_idYesSaved LLM credential UUID (read_silicon_sample include credentials lists them); the API key itself stays in the app.
source_question_idsNoWith source_survey_id: the earlier survey's question UUIDs whose answers describe each persona.
source_response_idsNoWith panel_id or source_survey_id: use exactly these respondents (record or response ids). Takes precedence over use_all_respondents and persona_count.
use_all_respondentsNoWith panel_id or source_survey_id: use every respondent instead of a random sample of persona_count. Ignored when source_response_ids is set.
exclude_previously_usedNoWith a panel: skip panel records already used by an earlier run on this survey (default true).
question_prompt_overridesNoOverrides for how questions are rendered into the answer prompt

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior4/5

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

Annotations already flag destructiveHint=true, openWorldHint=true and non-idempotent, but the description adds material behavior: real API budget is spent on the configured LLM credential, and generated rows are written into live response data intermingled with genuine submissions. It omits cleanup/reversibility and expected run duration, which would matter for an irreversible-feeling write.

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?

Three tight sentences, front-loaded with the action and consequence, with the tracking hint and plan requirement trailing. The 'with confirm: true:' phrasing is slightly awkward but wastes no space.

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 19-parameter, nested-object, budget-spending mutation with an output schema available, the description covers the essentials an agent needs before calling: cost, data write, plan gate, and follow-up. The main gap is any guidance on choosing between the panel-based and earlier-survey-based persona sources, which the schema carries alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all 19 parameters including nested template overrides are already documented in the schema. The description only glosses 'confirm: true' and 'the configured LLM credential', adding no syntax or interaction detail (e.g. panel_id vs source_survey_id precedence) beyond the schema, so the baseline 3 applies.

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?

The description names a specific verb and resource ('Start a Silicon Sample run') and immediately explains the effect: LLM personas answer the survey and their answers are stored as responses labeled silicon_sample alongside real respondent data. That is enough for an agent to distinguish it from read_silicon_sample/edit_silicon_sample 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 Guidelines4/5

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

It gives clear operating context — requires confirm: true, requires a Pro plan or Pro-owned workspace, and points to read_silicon_sample with include job or wait for tracking. It does not state when NOT to use it (e.g. changing settings without running belongs to edit_silicon_sample), so it stops short of explicit alternatives/exclusions.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources