← Back to blog

Easy Mode MCP: Runtime Tool Discovery for Small LLMs

September 22, 2026 · Eric · 8 min read

Every MCP client pays the same tax: it asks the server tools/list and gets back every schema the server owns. The Agent Media Tools stdio server currently defines 114 tools. That is fine for a frontier model with a huge context window. It is a disaster for a 7B model on your laptop, which will happily invent tool names or spend its whole budget reading JSON schema before the user's question is even parsed.

Easy Mode is already shipped in the stdio MCP server as the fix. Instead of exposing every schema, it exposes a small control surface plus a few local workflows, and the model discovers tools at runtime from a plain-language request. Here is the routing, the privacy gates, and the workflow reference syntax.

What Easy Mode actually changes

Flip one environment variable and the tool list collapses. These numbers come from running the server directly:

$ AMT_EASY_MODE=true node -e "
  const m = require('./mcp-server.js');
  console.log(m.TOOLS.length, m.visibleTools({AMT_EASY_MODE:'true'}).length, m.visibleTools({}).length);
"
114 8 113

With Easy Mode off, the client sees 113 schemas. With AMT_EASY_MODE=true, it sees eight:

ToolRole
find_tools_easyDiscovery — rank the catalog for a plain-language request
run_tool_easyUniversal runner — one interface, any discovered tool
run_workflow_easyChain up to 12 tools with $steps references
easy_mode_executeDurable state: compress, inspect artifacts, read task/run status
create_image_easyLocal image generation (ComfyUI / Stable Diffusion WebUI)
generate_comfy_studio_imageLocal Comfy Studio / ComfyUI generation with optional prompt enhancement
edit_image_easyLocal resize / compress / convert / grayscale
extract_document_easyLocal text, PDF, and image OCR extraction

easy_mode_execute is gated separately by AMT_INTELLIGENCE_ENABLED, which defaults to the Easy Mode value. Set it to false to keep the three control tools and the local workflows but drop the state layer.

Wiring it into an MCP host

Easy Mode is a stdio-server behavior, so it belongs in the client config next to the existing MEDIA_TOOL_URL entry that points the server at your instance:

{
  "mcpServers": {
    "media-tool": {
      "command": "node",
      "args": ["/absolute/path/to/media-tool/mcp-server.js"],
      "env": {
        "MEDIA_TOOL_URL": "http://localhost:3000",
        "AMT_EASY_MODE": "true"
      }
    }
  }
}

For the guided setup against LM Studio or Open WebUI — including the bridge that feeds tool results back to the model — see the Easy Mode for local agents guide.

Step 1 — find_tools_easy: discovery by plain language

The discovery tool takes a request string (up to 2,000 characters), an optional category — image, document, video, audio, web, agent, storage, account, or utility — and an optional limit from 1 to 10, defaulting to 5. Each match returns a compact schema: argument types, descriptions, enums, defaults, and required fields.

Here is a real request over stdio JSON-RPC, asking to shrink a photo:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"find_tools_easy",
  "arguments":{"request":"shrink a photo to under 200 KB without uploading it","limit":3}
}}

And the ranked matches it returns:

edit_image_easy      | image    | local  | score 15
   input: file_path, action, width, height, format, quality, allow_enlarge
extract_document_easy| document | local  | score 15
   input: file_path, max_characters
image_to_prompt      | image    | remote | score 12
   input: image_url, medium, direction, aspect_ratio, framing, subject_count, ...

Scoring is deterministic, which matters when your agent picks something unexpected. Name matches outrank description matches, and a small synonym table maps user vocabulary onto catalog vocabulary (photo → image, excel → xlsx, cron → schedule, speech → audio). Description wording counts too: edit_image_easy ranks first here partly because its own description mentions compressing an image "without uploading it", and dropping the word "photo" lowers its score from 15 to 11. Verb heuristics layer on top: create and set up boost create_* and generate_*, delete and stop flip that preference, and list or browse boosts list_*.

The privacy signal is the one to remember. Words like local, privately, offline, on device, or do not upload give every local-classified tool a large bonus and penalize remote ones. Appending "locally" to the query above moves edit_image_easy from 15 to 24 and pushes the remote tool out of the top ten. If your users care where their bytes go, teach them to say so in the prompt.

Step 2 — run_tool_easy: one interface for everything

Calling a discovered tool means passing its exact name back in. The response is a normalized envelope, so the model always parses the same shape regardless of which tool ran:

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
  "name":"run_tool_easy",
  "arguments":{"tool_name":"base64_encode","arguments":{"text":"agent-media-tools"}}
}}

{
  "success": true,
  "tool": "base64_encode",
  "privacy": "local",
  "result": "YWdlbnQtbWVkaWEtdG9vbHM="
}

Two guardrails are baked in. Meta-tools cannot be invoked through the runner — no recursive run_tool_easy inside run_tool_easy, and unknown names are rejected outright. And every call passes the privacy gate described next.

The privacy gate: local, remote, sensitive_remote

This is the part that makes Easy Mode safe to hand to an autonomous loop. Every tool is classified into one of three buckets, and only the local bucket runs without explicit human opt-in.

The sensitive bucket is broader than people expect. It includes everything that spends or provisions (initiate_purchase, provision_human_account), everything destructive (delete_artifact, delete_schedule), identity claims (claim_identity), approvals and receipts (request_approval, create_receipt), scheduled automation (create_schedule, run_schedule), the job ledger (create_job, claim_job, complete_job), and submit_bug.

A blocked call is not a silent failure. The model gets an instruction it can escalate to a human:

Error: Remote tool create_short_url is disabled.
The human must set AMT_ALLOW_REMOTE_TOOLS=true.

Local image generation has its own independent gate. create_image_easy tries ComfyUI at AMT_COMFYUI_URL, then Stable Diffusion WebUI at AMT_SD_WEBUI_URL, and only falls back to hosted generation when the human set AMT_ALLOW_HOSTED_IMAGE_FALLBACK=true. Otherwise it fails with "No local image generator is available" instead of quietly spending credits — the correct default for autonomous loops.

Step 3 — run_workflow_easy: chaining with $steps

When a task needs several deterministic operations, one workflow call beats three round-trips. Steps are sequential, capped at 12, and each can carry an id that later steps reference. A reference looks like $steps.encoded for a whole result or $steps.encoded.hash for one field inside a JSON result:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
  "name":"run_workflow_easy",
  "arguments":{"steps":[
    {"id":"encoded","tool":"base64_encode","arguments":{"text":"agent-media-tools"}},
    {"id":"decoded","tool":"base64_decode","arguments":{"base64":"$steps.encoded"}}
  ]}
}}

{
  "success": true,
  "steps": [
    {"id":"encoded","tool":"base64_encode","success":true,"result":"YWdlbnQtbWVkaWEtdG9vbHM="},
    {"id":"decoded","tool":"base64_decode","success":true,"result":"agent-media-tools"}
  ],
  "results": {"encoded":"YWdlbnQtbWVkaWEtdG9vbHM=","decoded":"agent-media-tools"}
}

Validation is strict, which is good news for debugging. A workflow must be a non-empty array of at most 12 steps. Step IDs must match [a-zA-Z0-9_-] and be unique — duplicates are rejected before anything executes. Meta-tools are banned as steps. A reference to a step that has not run, or to a field that does not exist in an earlier result, throws Workflow reference path not found instead of passing undefined to the next tool. Every step also passes the same privacy gate as run_tool_easy, so a workflow cannot smuggle a remote call past an unset flag.

Set continue_on_error: true only on genuinely optional steps: failures then land in that step's output and the chain continues. Leave it off and the first failure aborts with Workflow step {id} failed — what you want when step 3 consumes step 2's output.

easy_mode_execute: state without invented IDs

The fourth control tool is a small state machine with four actions:

ActionRequired inputReturns
compress_imageartifact_id or a first-time file_path, plus target_size_bytesCompression result, plus the registered input artifact
inspect_artifactartifact_idStored artifact metadata
get_task_statetask_idTask record
get_workflow_staterun_idWorkflow run record

target_size_bytes is required for compression and must fall between 16,384 bytes and 52,428,800 bytes (16 KB to 50 MB); the optional format is jpeg or webp. Once an image is registered you address it by artifact_id rather than a path, so the model never re-reads a file that has moved.

Treat the ID rules as a contract: these actions accept only IDs the same session previously returned. If your agent loops on inspect_artifact with a made-up ID, that is a prompt bug, not a server bug.

When your agent only speaks HTTP

Easy Mode is a stdio-layer convenience for MCP clients. The hosted MCP transport at /api/mcp requires an agent key — an unauthenticated request gets a 401 — so agents that cannot run a local Node process should call the REST surface instead. The small deterministic utilities are public endpoints, which makes them a sane smoke test before you wire up a key:

$ curl -s "https://agentmediatools.com/api/base64?text=hello%20amt"
{"success":true,"action":"encode","input":"hello amt","output":"aGVsbG8gYW10"}

$ curl -s "https://agentmediatools.com/api/hash?text=amt&algo=sha256"
{"success":true,"input":"amt","algorithm":"sha256",
 "hash":"9ff675fc4e1caf817b16e40944fb7bbd875952d4b1db66e7a842882797303527","length":64}

POST with a JSON body works the same way, which is easier to generate from code than query strings:

import requests

r = requests.post(
    "https://agentmediatools.com/api/units",
    json={"category": "length", "from": "m", "to": "km", "value": 1000},
    timeout=15,
)
print(r.json())
# {'success': True, 'value': 1000, 'from': 'm', 'to': 'km', 'result': 1, 'category': 'length'}

A practical pattern: use Easy Mode locally for cheap, deterministic work — hashing, encoding, timestamps, unit conversion, document extraction, local image edits — and reserve the keyed surface for operations that need hosted compute. The privacy gate makes that split explicit instead of accidental.

Boundaries worth knowing

Point your agent at the full catalog

Run the tools in the browser, or connect over MCP and let discovery do the routing. Free utilities need no key.

Open toolbox Easy Mode guide