Skip to main content
Glama

shop_run

Run a custom module on the store and read its printed output for one-off reports, data checks, or fixes.

Instructions

Run a module of YOUR OWN on this store and read what it printed. This is for code you wrote yourself and want to try: a report over several tables, a check across the catalogue, a one-off fix with its own logic. For work the owner of the shop already provided for, use tool_run instead - that one has a registry row and a grant behind it, this one has nothing but the session key. The storefront runs the module exactly as it runs any module - same parser, same cache, same access to the data. Three conditions. The name starts with agent_ (the entry point runs nothing else); the module exists - create it with engine_php_add and write it with engine_php_save; and it is saved as an entry point, which is manifest ajax_load=1. The output is saved under mcp/melbis/runs/ and comes back here whole unless it is long.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
modYesModule name without .php, for example agent_price_audit.
paramsNoValues for the module, by name. The entry point hands them over as one serialized argument, so the module declares post: serial in its manifest param_info and reads them as $mVars[post] - names survive, and so do commas and any alphabet inside a value. The same values are in $_POST; login, secret and mod are stripped before the module sees them.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv6.5.1

TDQS

A4.5/5.0
Behavior4/5

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

No annotations exist, so the description carries the full burden of behavioral disclosure, and it does so richly: it discloses execution equivalence ('same parser, same cache, same access to the data'), auth context ('nothing but the session key'), output destination (mcp/melbis/runs/), and truncation behavior ('comes back here whole unless it is long'). A minor gap: what actually happens when output is long (error? truncated? saved to file only?) is left unstated.

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?

Long but efficiently packed with zero filler. Purpose is front-loaded, followed by the sibling differentiation, execution-equivalence note, three conditions, and output location. Each clause earns its place; the only knock is that the three conditions could be slightly tightened, but nothing is redundant.

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 tool that runs arbitrary code with a nested params object and no output schema or annotations, the description covers purpose, alternative routing, execution semantics, preconditions, and output handling. The only notable gap is the unspecified behavior for long output, which is an edge case an agent would want to know.

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% (baseline 3), and the schema already documents both params in detail - mod with an example, and params with serialization behavior, manifest param_info, $mVars[post], and $_POST stripping. The description adds value beyond the schema by imposing the agent_ prefix constraint on mod and the entry-point requirement, which are semantic restrictions not present in 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 ('Run a module of YOUR OWN on this store and read what it printed') with clear scope - it is for the agent's own code, not the owner's. It explicitly distinguishes itself from the sibling tool_run ('For work the owner of the shop already provided for, use tool_run instead'), making differentiation immediate.

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?

Gives explicit when-to-use guidance for the agent's own code and names the alternative (tool_run) with the exact condition that selects it ('that one has a registry row and a grant behind it, this one has nothing but the session key'). It also lists three concrete preconditions for valid use: name starts with agent_, module exists (created via engine_php_add, written via engine_php_save), and is saved as an entry point (ajax_load=1).

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