Balena MCP

balena_list_releases

Read-onlyIdempotent

List releases for a fleet, team, or organization by ID. Use skip and top parameters to page through release records and retrieve the exact set you need.

Instructions

List releases for a fleet.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "balena_list_releases"
  }
}

Input Schema

Name	Required	Description
`top`	No
`skip`	No
`parent_id`	No	Fleet, team, or organization ID when applicable

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.0Sep 23, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond the basic listing action, such as pagination behavior (top/skip) or whether results are ordered. It doesn't contradict annotations.

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

Conciseness4/5

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

The description is a single, efficient sentence that states the core purpose without waste. It could be slightly more informative about pagination or scoping, but it earns its place as a concise summary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list tool with annotations covering safety, the description is minimally adequate. However, it lacks guidance on how parent_id affects results (fleet vs team vs org), pagination behavior, and how it relates to sibling list tools. The absence of an output schema means the agent gets no return-format hints, but the description doesn't compensate.

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 only 33% (only parent_id has a description). The description itself doesn't explain top or skip parameters, but their names and defaults (25, 0) are fairly self-explanatory as pagination controls. The parent_id description in the schema is clear, but the tool description doesn't add meaning beyond that.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List releases for a fleet' uses a specific verb and resource, clearly identifying the operation. It distinguishes itself from sibling tools like balena_get_release (single release) and balena_list_services (different resource), though it doesn't explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a read-only listing operation for a fleet, which is clear enough for basic use. However, it provides no explicit guidance on when to use this tool versus alternatives like balena_get_release or balena_list_services, nor does it mention the optional parent_id parameter's role in scoping.

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

Deploy Server