Skip to main content
Glama

execute_write

Destructive

Execute JavaScript to perform authorized InSales API writes, using a fresh execution ID so identical retries return the journal without replaying changes.

Instructions

Execute JavaScript including writes. Provide a fresh UUID execution_id; identical retries return the journal without replay. Use get_operation to inspect completed or uncertain writes. Code is an async function body: await calls and return JSON. First return await insales.list_stores({}) to obtain store_id. Discover with catalog.search({query?:string,domain?:string,limit?:number}); inspect arguments with catalog.describe({names:string[]}), e.g. return await catalog.describe({names:["get_widget","update_widget"]}); then call insales.(args). Search without query lists domains. Batch related descriptions and compose known calls in one script; return focused data. Do not guess arguments: use inputSchema or the schema returned by validation errors. Results contain status, result/error, steps and execution_id. Large results/errors have result_ref/error_ref: read runtime.get_result(ref,{offset,limit}); inspect writes using runtime.get_execution(id). No imports, process, filesystem, crypto, timers or arbitrary network.

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": {
      "execution_id": "<execution_id>",
      "code": "<code>"
    },
    "name": "execute_write"
  }
}

Input Schema

NameRequiredDescriptionDefault
codeYesJavaScript async function body. Discover with catalog.search/describe, call insales methods, return JSON.
execution_idYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.0.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare destructive/openWorld/non-idempotent, but the description adds substantial context beyond them: the execution_id acts as a deduplication key so identical retries return the journal without replay, the sandbox forbids imports/process/filesystem/crypto/timers/network, and responses carry status, steps, and result_ref/error_ref handles. This is exactly the behavioral detail annotations cannot express.

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?

The critical contract (execute JS including writes, fresh UUID for retry dedup) is front-loaded, and nearly every sentence carries actionable guidance. However it is a single dense run-on paragraph mixing sandbox limits, discovery workflow, batching advice, and error handling with no formatting, making it harder to scan than it needs to be.

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?

For a complex code-execution tool with no output schema, the description covers the return shape (status, result/error, steps, execution_id), the ref-based overflow path, the sandbox restrictions, and the full discovery-to-invocation workflow. An agent has enough to call it correctly on the first attempt.

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 only 50% (execution_id has no schema description), and the description compensates by defining execution_id as a caller-supplied fresh UUID that governs retry/replay semantics, and by clarifying that code is an async function body that awaits calls and returns JSON. That is meaningful added semantics, though the exact code-string format and size limits are left to the schema.

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 ('Execute JavaScript') plus the crucial scope qualifier 'including writes', which is exactly what separates it from the sibling execute_read. An agent can tell what this tool does and what class of operation it covers without opening either 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?

Rich operational routing: use get_operation for completed/uncertain writes, runtime.get_result for large refs, runtime.get_execution to inspect writes, catalog.search/describe to discover methods, and 'do not guess arguments'. It never states the negative case (e.g., use execute_read when no writes are needed), so it falls short of full when/when-not/alternatives coverage.

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

Deploy Server

Other Tools