Skip to main content
Glama

start_app

Launches another app on an existing instance’s display so you can run a second tool beside the browser or restart an app that quit.

Instructions

Start ANOTHER app on an existing instance's display (same window/cursor) — e.g. a second tool next to the browser, or a restart of an app that quit. For a new, separate window use launch_app; to open a file in an app use open_file.

Returns {"ok", "instance", "command", "pid"}; fails (isError) if the instance is down, the command is unparsable/missing, or the app exits immediately (stderr tail quoted; app_log(instance) has more — logs of apps started here are appended to it). Browsers get the same X11/profile/CDP handling as launch_app. The app starts asynchronously: wait_for_stable() or screenshot() after a moment to confirm it drew.

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": {
      "command": "<command>"
    },
    "name": "start_app"
  }
}

Input Schema

NameRequiredDescriptionDefault
commandYes
instanceNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.6.1

TDQS

A4.6/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses the return keys, the exact failure conditions (instance down, unparsable/missing command, immediate exit), where stderr tails surface, the app_log linkage, browser-specific X11/profile/CDP handling, and the asynchronous start semantics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The scope constraint and sibling routing are front-loaded in the first two sentences, followed by return/failure behavior and then the async caveat. Dense but every sentence adds decision-relevant information, with zero filler.

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 process-launching tool with side effects and no annotations, this covers the critical ground: what it does, what can go wrong, where diagnostics land, and what to do immediately after starting. Return values are restated even though an output schema exists, which is redundant but not harmful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% for two parameters, so the description must compensate and only partly does. "Instance" is given semantic grounding (an existing instance's display) but no guidance on valid values or how to discover them, and the "command" parameter's format — shell string vs. executable plus args — is never specified beyond being failable when unparsable.

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?

The description leads with a precise verb+resource+scope: "Start ANOTHER app on an existing instance's display (same window/cursor)". It immediately distinguishes itself from launch_app (new separate window) and open_file (open a file in an app), so an agent can separate it from siblings without opening any schema.

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?

It gives explicit routing rules: use launch_app for a new separate window, use open_file to open a file, and use this tool for a second tool on the same display or a restart of an app that quit. It also names the alternative observation tools (wait_for_stable, screenshot) for the post-start step.

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