Skip to main content
Glama

List service instances

list_service_instances
Read-only

List the organisation's managed services (the twin of ankra services list): each instance's name, package, cluster and its name, deployment state, readiness and health, its consumers with their application, cluster and environment names, its latest retirement, and state - its lifecycle in one word. Filter by application_id for the services one application uses, by cluster_id for those running on a cluster, or by state. A page shorter than limit with a next_cursor carries scan_capped true: the read stopped at its row bound, not at the last match, so follow next_cursor before saying nothing more matches. A retirement whose outcome is retired released the name; its data_disposal says whether the service's data may remain (data_kept, unconfirmed) and kept_data names the volumes, the cluster, when Ankra last looked and the Ankra CLI commands to inspect or erase them. Never report such a service as plainly deleted, and say kept_data is what Ankra saw then, not now. Read-only.

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": "list_service_instances"
  }
}

Input Schema

NameRequiredDescriptionDefault
afterNonext_cursor from the previous page, to read the next one.
limitNoPage size, 1-50. Defaults to 25.
stateNoKeep the instances in this state: deploying, deployed (finished; nothing observes its health), serving, degraded, failed, retiring, released, or unknown.
cluster_idNoKeep the instances that run on this cluster (UUID from list_clusters).
application_idNoKeep the instances that serve this application (UUID from list_applications): their reviewed plan names one of its environments as a consumer.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses non-obvious behavior: a short page with next_cursor means scan_capped (a row-bound stop, not end-of-results), and retirements carry data_disposal/kept_data whose meaning and staleness ("what Ankra saw then, not now") are spelled out. It even prescribes reporting language ("Never report such a service as plainly deleted"), which is behavioral context annotations cannot convey.

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?

Purpose and returned fields are front-loaded in the first sentence, with filters, pagination caveat, and retirement caveat following in a logical order. It is a dense single block, though — the retirement/data_disposal passage is long and partially duplicates the state enum vocabulary — so it is efficient but not maximally tight.

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?

With no output schema, the description compensates by enumerating the returned shape (instance fields, consumer details, retirement fields) and explaining the two failure modes an agent would otherwise misread: truncated scans and released-but-data-kept services. For a read-only list tool with five optional params, nothing an agent needs to call it or report on it is missing.

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 five parameters are already documented at the field level, which sets the baseline at 3. The description adds some framing by grouping the three filters into a single "filter by X for Y" sentence, but it introduces no syntax, default, or edge-case detail the schema does not already provide.

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 gives a specific verb and resource ("List the organisation's managed services") and then enumerates the fields each instance carries — name, package, cluster, deployment state, readiness/health, consumers, latest retirement, lifecycle state. It also anchors the tool against a concrete reference ("the twin of `ankra services list`"), so an agent can distinguish it from get_service_instance or list_service_consumers 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 Guidelines4/5

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

It states explicitly how to narrow results — application_id for one application's services, cluster_id for one cluster's, or state — and gives operational instructions for paging ("follow next_cursor before saying nothing more matches"). What it does not do is name a sibling alternative or say when to reach for get_service_instance instead of this list, so it stops short of a full routing guide.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.