Skip to main content
Glama
adidshaft

Grok Gadgets Gateway

by adidshaft
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

gadgets_command

Destructive

Run a capability on a connected gadget using JSON arguments, then return the final command status or a command ID for polling if the device is slow.

Instructions

Ask a gadget to run one command capability with JSON arguments.

The call waits up to 3 seconds for the device's report and returns the final status when it arrives. If command.status is still accepted or dispatched, the device is slow: poll gadgets_command_status with command.command_id instead of sending the command again.

command_id is optional. For a new action, omit it: the gateway creates a unique ID and returns it as command.command_id. Within 10 minutes and the same gateway process, repeating that ID with identical arguments returns the original receipt with duplicate=true, or stale_command_id if the receipt was evicted. It does not run again. Changed arguments return duplicate_conflict. Never reuse an ID for a new action. Retry protection is not durable: after a restart or outside that window, inspect state before acting. Do the same if a lost reply left you without a command ID. Never create a new ID to retry an uncertain action.

command.status: accepted = queued; dispatched = delivered, waiting for the device; executed / failed = the device reported a result (a report, not physical proof); not_delivered = the device never received it, so sending it again as a new action is safe; timed_out / unconfirmed = outcome unknown, so read state before acting again.

Input Schema

NameRequiredDescriptionDefault
argumentsYes
device_idYes
capabilityYes
command_idNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv0.1.0-alpha.2
    • addedInput schema / properties / command_id / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / command_id / default
      Added value: +null
    • removedInput schema / properties / command_id / type
      Removed value: -"string"
    • changedInput schema / required
      Previous value: -[
-  "device_id",
-  "capability",
-  "arguments",
-  "command_id"
-]New value: +[
+  "device_id",
+  "capability",
+  "arguments"
+]
  2. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations, the description discloses that the call waits up to 3 seconds, returns a final status when available, and explains the duplicate/stale/conflict semantics of command_id. It also clarifies that executed/failed means 'a report, not physical proof' and that retry protection is not durable, which is valuable context for a destructive, non-idempotent command tool.

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 description is long but front-loads the core action, then proceeds through command_id semantics and status meanings in a logical order. Every paragraph adds distinct operational value for safely invoking a destructive command tool.

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 complex command-execution tool with no output schema, the description covers behavioral semantics and status outcomes very well. It is slightly incomplete on output shape and on the non-command_id parameter formats, but its rich retry and status guidance makes it largely sufficient.

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 coverage is 0%, so the description must carry parameter meaning. It thoroughly explains command_id (optional, duplicate behavior, stale/conflict cases) but only minimally addresses device_id, capability, and arguments, leaving those required parameters without format or selection guidance.

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 states a specific verb and resource: 'Ask a gadget to run one command capability with JSON arguments.' It also distinguishes this tool from the sibling gadgets_command_status by explicitly telling the agent to poll that tool when the command is still pending.

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 when-to-use and when-not-to-use guidance: poll gadgets_command_status instead of resending a command, omit command_id for new actions, never reuse an ID for a new action, and inspect state before retrying after uncertain outcomes. The status-specific guidance for not_delivered, timed_out, and unconfirmed further clarifies safe next steps.

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