instabox-mcp

Change a machine's Secret selection

instabox_update_machine_secrets

Replace the organization proxy and environment secrets a machine can use, updating only the selections you pass while leaving omitted fields unchanged.

Instructions

Replace the org Secrets a machine may use. Each field you pass replaces that whole selection; omitted fields stay as they are. SECURITY: secrets lets code in the machine send those credentials to their allowed hosts, and envSecrets puts real values into the machine. Delivery then updates in the background; refresh with instabox_refresh_machine_secrets.

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": {
      "id": "<id>"
    },
    "name": "instabox_update_machine_secrets"
  }
}

Input Schema

Name	Required	Description
`id`	Yes	Machine ID (m_...) or its unique name
`secrets`	No	Proxy Secret names, or "all" for every current and future proxy Secret; [] selects none
`envSecrets`	No	Explicit env Secret names; [] clears

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 1, 2026

TDQS

A4.4/5.0

Behavior4/5

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

Annotations only declare it is a non-readonly, non-destructive, non-idempotent write; the description adds the critical replace-vs-merge semantics, the security consequence of each field (`secrets` grants outbound credential use, `envSecrets` injects real values), and that delivery is asynchronous and needs a refresh. Missing are permission requirements and failure modes, so not a 5.

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?

Front-loaded with the action, then the merge rule, then the security warning, then the follow-up tool. Three tight sentences with no redundancy.

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 3-parameter mutation with no output schema, the description covers the mutation semantics, the risk profile, and the async follow-up. It is slightly thin on what the call itself returns (e.g. an operation handle) and on required permissions.

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 coverage is 100%, so the baseline is 3; the description earns extra credit by stating the per-field replacement rule and the security meaning of `secrets` vs `envSecrets`, which the schema does not convey. It does not restate the 'all' / empty-array semantics from the schema, which is fine.

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 ('Replace the org Secrets a machine may use'), which clearly separates it from the read-only siblings instabox_get_machine_secrets and instabox_refresh_machine_secrets. The title and description agree on scope (secrets selection, not machine config).

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?

Explains the replacement model ('each field you pass replaces that whole selection; omitted fields stay as they are') and routes the agent to instabox_refresh_machine_secrets after the call. It does not explicitly say when to prefer this over instabox_update_machine or get_machine_secrets, but the context is clear.

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