Skip to main content
Glama

native_surfaces

Reports native ways to drive an app—CLI, URL scheme, executable, or Store AUMID—so agents can use deterministic control before simulating clicks. Read-only.

Instructions

Report the native ways an application can be driven: a command line it ships, a URL scheme it registers, a registered executable, or a Store AUMID. These are cheaper and more deterministic than driving the window, so look here before clicking. Read-only.

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": {
      "app": "<app>"
    },
    "name": "native_surfaces"
  }
}

Input Schema

NameRequiredDescriptionDefault
appYesthe application display name
schemesNoURL schemes to look for
cli_namesNoCLI names to look for
exe_namesNoApp Paths entries to look for

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.2.0

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the full behavioral burden: it states the operation is read-only and describes what kinds of native surfaces are reported. It does not cover failure behavior, permission requirements, or return formatting, but for a simple discovery read it discloses the essential safety and scope characteristics.

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?

Three tightly written sentences with zero waste. The purpose is front-loaded, the native surface types follow naturally, and the routing advice plus read-only note close the description efficiently.

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 four-parameter read-only discovery tool with no output schema, the description is largely complete: it explains what is discovered and why it matters. It could optionally say more about what happens when no surface is found, but the essential call context is present.

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

Parameters3/5

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

Schema description coverage is 100%, so all four parameters are already documented in the input schema. The description reinforces the overall purpose but adds no parameter-specific semantics such as matching rules, case sensitivity, or how the optional lookup filters interact with the app name.

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 uses a specific verb and resource: 'Report the native ways an application can be driven,' then enumerates four concrete surfaces (command line, URL scheme, executable, Store AUMID). This clearly distinguishes it from sibling interaction tools like click, browser_click, and type_text by framing it as a discovery step before window automation.

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?

It gives explicit guidance to prefer this tool before clicking because native surfaces are 'cheaper and more deterministic than driving the window.' This establishes a clear when-to-use condition relative to GUI automation. It lacks named alternatives or explicit when-not-to-use cases, but the routing intent is strong.

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