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 the subscription.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "pull_twin"
  }
}

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.2/5.0
Behavior5/5

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

Annotations only cover the safety profile, and the description adds substantial behavior: determinism (same document and seed produce the same report hash as ae_pull), hard limits (sessions 1-1000, at most 5,000 beats per session), and a full cost/queueing model. It explicitly discloses that anything beyond a plain pair of up to 20 sessions is queued, priced by engine-side estimation, and refused with 402 on the free plan. That is exactly the kind of operational context annotations cannot carry.

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 purpose and input modes are front-loaded, but the text then collapses into a single dense block mixing cost arithmetic, queue behavior, and plan restrictions in one long sentence chain. The pricing detail largely duplicates what the pull_cost and subscription siblings exist to explain, so not every sentence earns its place here. Readability suffers from stacked parentheticals.

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?

This is a complex, expensive, queue-capable tool, and the description covers inputs, determinism, cost drivers, sync-vs-queued behavior, and the free-plan refusal path. An output schema exists so return values need not be re-explained, yet the description still names the headline results. An agent has enough to decide whether 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: planted is explained as [intended, unintended] gains, coupling as performer-follower coupling strength, field as a lattice between leader and follower, and sessions defaults to 20 or the document's own value. The condition and twin-document alternatives are also framed as mutually substitutable input modes, which the schema alone does not make clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: runs twin sessions and analyses them under the twin's pre-registration, returning the significant-session count, the rate with a 95% interval, and a pooled report hash. It even distinguishes itself from siblings by noting the same document and seed yield the same hash as ae_pull, and points to pull_schema for document keys. The one gap is that 'twin session' itself is never plainly defined, so the resource stays jargon-opaque for a newcomer.

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?

Gives clear selection context: supply a twin document (with pull_schema naming its keys) or the condition/coupling/planted/field shortcut for the engine's default pair. It also explains the semantic intent of the knobs (uncoupled twins measure the false-positive rate; coupled ones should come out significant), which tells an agent what to expect. It stops short of naming an explicit alternative tool for a given scenario beyond the pull_schema pointer.

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