Skip to main content
Glama

Run twin sessions

pull_twin

Runs twin sessions (scripted performers and the machine follower, each session drawn, sealed, released, closed and opened like a real one) and analyses them under the twin's own pre-registration: how many sessions were labelled significant, that rate with its 95% interval, and the pooled report with its hash. Give a twin document (pull_schema lists its keys: others for a group, a room of beings, the system generator, a field lattice), or condition (P1 to P4, R1 to R4), coupling (0 to 1) and planted ([intended, unintended] gains, each -2 to 2) for the engine's default pair; field (toda) strings a lattice between leader and follower. Uncoupled twins measure the false-positive rate; coupled ones should come out significant. The same document and seed give the same report hash as ae_pull itself. sessions is 1 to 1,000 (default 20, or the document's own); a schedule runs to at most 5,000 beats a session. It costs one unit for each 40,000 session-draws over a thousand events (a session's own reading counts as 200 draws), at least 1. A plain pair of up to 20 sessions and 2 units answers at once. Anything more, and any field, group, room or system generator, is queued and priced by the engine's own count of the twin (events a session at the schedule's widest gaps, its draws and its pairs, and the CPU-seconds a lattice or a spiking network takes), at least a unit for each 5 CPU-seconds it estimates, times the sessions. A queued call is refused on the free plan with 402: its units buy only calls that answer at once, and queued jobs need a paid plan (a pass or the card plan).

Input Schema

NameRequiredDescriptionDefault
seedNoA whole number that makes the run reproducible: the same seed and inputs give the same answer.
twinNoA twin document written inline; or use condition, coupling, planted and field instead.
fieldNoThe field to run the twins in, by name.
detailNoTrue to return the fuller per-session detail.
plantedNoThe planted effect as a pair of numbers between -2 and 2.
couplingNoHow strongly the follower is coupled to the performer, 0 to 1.
sessionsNoHow many sessions to run, 1 to 1000.
conditionNoThe condition to run: P or R followed by 1 to 4.

Output Schema

NameRequiredDescriptionDefault
msNoMilliseconds the run took.
jobYesThe job id; the job tool reads it.
verbNoThe tool that made it.
filesNoFiles made, each with a name, type, size and a signed URL.
unitsNoUnits this call cost.
resultNoThe engine's own answer, a JSON document.
statusNoqueued when the job runs in the background.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changed
    • addedInput schema / properties / condition / description
      Added value: +"The condition to run: P or R followed by 1 to 4."
    • addedInput schema / properties / coupling / description
      Added value: +"How strongly the follower is coupled to the performer, 0 to 1."
    • addedInput schema / properties / detail / description
      Added value: +"True to return the fuller per-session detail."
    • addedInput schema / properties / field / description
      Added value: +"The field to run the twins in, by name."
    • addedInput schema / properties / planted / description
      Added value: +"The planted effect as a pair of numbers between -2 and 2."
    • addedInput schema / properties / seed / description
      Added value: +"A whole number that makes the run reproducible: the same seed and inputs give the same answer."
    • addedInput schema / properties / sessions / description
      Added value: +"How many sessions to run, 1 to 1000."
    • addedInput schema / properties / twin / description
      Added value: +"A twin document written inline; or use condition, coupling, planted and field instead."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "$schema": "http://json-schema.org/draft-07/schema#",
      +  "additionalProperties": true,
      +  "properties": {
      +    "files": {
      +      "description": "Files made, each with a name, type, size and a signed URL.",
      +      "items": {
      +        "additionalProperties": {},
      +        "type": "object"
      +      },
      +      "type": "array"
      +    },
      +    "job": {
      +      "description": "The job id; the job tool reads it.",
      +      "type": "string"
      +    },
      +    "ms": {
      +      "description": "Milliseconds the run took.",
      +      "type": "number"
      +    },
      +    "result": {
      +      "description": "The engine's own answer, a JSON document."
      +    },
      +    "status": {
      +      "description": "queued when the job runs in the background.",
      +      "type": "string"
      +    },
      +    "units": {
      +      "description": "Units this call cost.",
      +      "type": "number"
      +    },
      +    "verb": {
      +      "description": "The tool that made it.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "job"
      +  ],
      +  "type": "object"
      +}
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations declare non-read-only, non-idempotent, non-destructive, and closed-world, but the description adds rich behavioral context: deterministic reproducibility (same seed/document gives same hash), cost model in units, queuing rules, session limits, schedule bounds, and free-plan refusal. This is well beyond what annotations provide.

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?

The description is a single dense paragraph of ~250 words, front-loaded with purpose but lacking structural breaks (e.g., bullets for cost/queueing). While much content is necessary, some sentences (e.g., parsing the cost formula) could be condensed, making it harder to scan quickly.

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?

Given the complexity, output schema presence, and 8 parameters, the description covers all critical aspects: input modes, defaults, cost, queuing, plan restrictions, and reproducibility. An agent has everything needed to decide when and how to call it.

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 description coverage is 100%, so baseline is 3. The description adds meaningful details beyond schema: default session count (20 or document's own), field semantics as a lattice between leader and follower, and clarifies planted gains range. It doesn't fully re-explain every parameter but compensates well for the high coverage.

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 (runs) and resource (twin sessions) plus the analysis output: significance count, rate with 95% interval, and pooled report hash. Distinguishes from siblings by naming ae_pull for hash compatibility and pull_schema for document keys.

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 describes when to use a twin document versus condition/coupling/planted versus field, and explains the default pair behavior. Also covers cost, queuing, and free-plan refusal (402), leaving no ambiguity about invocation context.

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