Skip to main content
Glama

run_scratch_code

Run JavaScript or TypeScript in the workspace sandbox without creating a playbook or run record. Use when probing an API, checking credentials, or trying step code before wiring a playbook (for example lead enrichment or invoice lookups). Pass a short plain-English description (3-8 words) shown as the step title. Default and max wait is 50s (timeoutClamped: true if a larger timeout is passed). Default allowNetwork is false; set true for fetch and metaphor.*. Pass secretNames to inject vault values; missingSecret lists names that were absent. Never print secret values. Optional packages install in the sandbox; if install plus execute exceeds 50s the call times out. Existing attachment keys: pass in input and read with metaphor.attachment(key). No upload on this tool.

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": {
      "language": "<language>",
      "code": "<code>"
    },
    "name": "run_scratch_code"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYesFull source to execute in the sandbox harness.
inputNoJSON object available as input_data inside the sandbox.
timeoutNoMax execution time in ms. Default and maximum 50000 on inbound MCP.
languageYes
packagesNo
descriptionNoShort plain-English description of what this code does (3-8 words, active voice, e.g. "Fetch open HubSpot deals" or "Test Zendesk ticket search"). Shown to the user as the step title.
secretNamesNo
allowNetworkNoAllow network (metaphor.*, fetch). Default false.

Schema Changelog

Changes observed during successful MCP inspections.

No schema history has been recorded yet.

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations, disclosing the 50s default/max wait and timeoutClamped flag, allowNetwork defaulting to false and gating fetch/metaphor.*, vault value injection via secretNames with missingSecret in the result, the prohibition on printing secrets, the install+execute time budget, attachment key handling, and that this tool cannot upload. None of this is in the annotations, and it is exactly the behavior an agent needs to avoid failed calls.

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-loaded with the purpose and use cases, then moves through runtime constraints and secrets in a logical order with no filler sentences. It is dense and slightly run-on across many clauses, which slows scanning on a long tool description, but every sentence carries operational information.

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?

There is no output schema, and the description compensates by naming the return signals an agent must watch (timeoutClamped, missingSecret) and the 50s ceiling that governs failure. For an 8-parameter sandbox execution tool with network, secrets, and package installs, the coverage of gotchas is unusually thorough.

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?

With 8 parameters at 63% schema coverage, the description fills most gaps: it explains timeout clamping, what allowNetwork unlocks, the secretNames/missingSecret round trip, package install implications, and that input carries attachment keys. Some content duplicates the schema (allowNetwork default, description length/format), which is why this is not a 5.

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 (run JavaScript/TypeScript in the workspace sandbox) plus the crucial scope qualifier 'without creating a playbook or run record', which cleanly separates it from run_playbook and the run-history siblings. An agent can pick this out of the tool list without opening the 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?

Gives concrete use cases: probing an API, checking credentials, trying step code before wiring a playbook, with examples (lead enrichment, invoice lookups). That is strong context but there is no explicit 'do not use for production execution' exclusion naming run_playbook as the alternative.

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