portainer-mcp

by ginkida

Overview Schema Source Related Servers Score Discussions Admin

Python

Remote

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.8.0
Disambiguation4/5
Tools are grouped by resource (stack, container, service, network, volume, image) and each pairs a resource with a distinct action, so most choices are clear. A few adjacent tools could still be confused (portainer_status vs portainer_docker_info, stack_status vs services_list, and the three log-scanning variants), but their descriptions draw workable boundaries.
Naming Consistency4/5
Nearly all tools follow the portainer_<resource>_<action> snake_case pattern, with plural list verbs (containers_list) and singular inspect verbs (container_inspect). Exceptions like portainer_status, portainer_docker_disk_usage, portainer_service_tasks, and portainer_container_logs break the action suffix pattern but remain readable.
Tool Count2/5
With 53 tools this is a very large surface for an agent to reason over, even though the Docker/Portainer domain genuinely has many resource types. It exceeds the comfortable 3–15 range by a wide margin and will make tool selection and prompt context heavier.
Completeness4/5
Docker resource coverage is strong: stacks, containers, services, images, volumes, and networks all have list/inspect plus lifecycle actions, and service/stack wait tools close rollout dead ends. Gaps are mostly in Portainer-admin resources (users, endpoints, registries, secrets/configs are read-only) and there is no container create, but agents can work around most of these via stacks.
Average 3.9/5 across 53 of 53 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 12 commits in the last 12 weeks
- Last stable release on September 7, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavioral traits. It only states 'Get details', implying a read operation, but provides no information about side effects, permissions, rate limits, or what 'details' entails. The tool name suggests inspection, but the description adds minimal safety context.
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 extremely concise—only two sentences. It is front-loaded with the purpose. However, it lacks any structural elements like bullet points or sections, which could improve readability. The brevity is appropriate for a simple tool but could still be more informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, return values need not be explained. However, the description omits any context about when to inspect a specific endpoint (e.g., after listing) or what data is returned. For a tool with one parameter and no annotations, more contextual guidance would help an agent decide to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter endpoint_id has a one-line description that adds little beyond the schema (integer, required). With 0% schema description coverage, the description should provide deeper context (e.g., how to find the ID), but it merely repeats the obvious.
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 clearly states 'Get details of a specific Portainer environment (endpoint).' This specifies the action (get details) and the resource (specific endpoint), distinguishing it from the sibling tool 'portainer_endpoints_list' which lists all endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when or why to use this tool versus alternatives. It does not mention prerequisites (e.g., obtaining endpoint_id from endpoints_list) or contexts where this is preferred over other inspect tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It states that the tool retrieves information but does not indicate whether it is read-only, what permissions are needed, or that no side effects occur.
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 short and uses a structured 'Args:' block. It is not verbose, but it could be more concise by removing the redundant 'Args:' header when not needed.
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?
The tool has an output schema, so description need not explain returns. However, it does not clarify what 'detailed information' entails, nor the relationship to the endpoint. For a simple inspect tool, it is minimally adequate.
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?
With 0% schema description coverage, the description adds some meaning: network_id is defined as 'Network ID or name', and endpoint_id as 'Target endpoint ID (uses default if omitted)'. This goes beyond the raw schema but still lacks depth (e.g., how to find endpoint_id).
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 clearly states 'Get detailed information about a Docker network,' which is a specific verb+resource. Among sibling tools, network_inspect is distinct from network_connect, create, disconnect, remove, and list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like portainer_networks_list (which lists networks) or other inspect tools. The description does not mention prerequisites, use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose the destructive nature of the operation, but it only says 'Delete a stack.' There is no mention of irreversibility, potential side effects on associated resources, permission requirements, or failure conditions. This is a significant gap for a destructive 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 extremely concise: a one-sentence purpose followed by a compact argument list. It is front-loaded with the action and avoids any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists (signal indicates it), the description does not mention what the tool returns, nor does it provide any context about the deletion process, such as whether it stops running containers first or requires the stack to be stopped. Without annotations, this is insufficient for a destructive operation; an agent might not know if it can safely call it or what to expect.
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?
The description adds meaning beyond the schema by explaining each parameter in plain language: 'stack_id: The ID of the stack to delete' and 'endpoint_id: Endpoint ID (derived from the stack itself if omitted).' The note about endpoint_id being derived is helpful, but it does not cover error handling or value constraints. Given the schema already provides titles, this adds moderate value.
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 clearly states the action: 'Delete a stack.' It identifies the resource and the operation, and the verb 'delete' distinguishes it from sibling tools like deploy, update, start, stop, inspect, etc. An agent can unambiguously know this is the tool for removing a stack.
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 usage by the name and the verb, but it does not provide explicit guidance on when to use it vs. alternatives, nor any exclusions or prerequisites (e.g., stack must exist, or that it is irreversible). It relies on the tool name for differentiation, which is adequate but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a state-changing action but does not disclose what stopping a stack actually does (e.g., whether it scales services to zero, retains data, is reversible, or affects running containers). With no annotations, the behavioral side effects are largely unspecified.
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 extremely concise, with a single purpose statement and two brief parameter explanations. No unnecessary words or redundant information are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description omits important context about the operation's effects, whether it is idempotent, how to recover afterward, and what the output/response indicates. Since no output schema is provided and no annotations are present, the description carries the full burden but leaves these gaps.
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?
The parameter descriptions add some meaning beyond the raw schema, especially endpoint_id ('derived from the stack itself if omitted'), which clarifies an important default behavior. However, stack_id's description mostly restates the parameter name, so the added semantic value is only partial.
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 clearly states a specific verb ('stop') and resource ('a running stack'), and the sibling list includes start, update, delete, and inspect operations, making it easy to distinguish this tool from related stack operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use stop versus other stack lifecycle operations such as start, update, or delete. It does not explain scenarios, prerequisites, or why one might stop a stack instead of removing it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description fails to disclose behavioral traits like idempotency, side effects, or failure modes. The minimal text does not warn about potential issues (e.g., starting an already running container).
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 extremely concise, using two sentences and a bullet list. It is front-loaded with the core purpose and efficiently structured.
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 start operation with an output schema, the description is adequate but lacks mention of edge cases (e.g., container already running) and error scenarios. It covers essential purpose but not completeness.
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?
The Args section adds meaning beyond the schema by clarifying that container_id can be a name and endpoint_id defaults to null. However, with 0% schema coverage, more detail (e.g., format, required) would be beneficial.
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 clearly states the action 'Start a stopped container' with a specific verb and resource. It distinguishes from sibling tools like stop, restart, and remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool over alternatives, prerequisites (e.g., container must be stopped), or behavior if the container is already running.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden for behavioral disclosure. It only states the action without detailing whether the stop is graceful or forceful, or if there are side effects (e.g., stopping dependent containers).
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?
Extremely concise: two sentences covering purpose and parameters. No unnecessary words; every sentence earns its place.
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?
The tool is simple (stop container) and has an output schema, so return values needn't be explained. However, given no annotations, the description lacks safety or side-effect information, making it marginally adequate.
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 description must compensate. It adds minimal value by stating 'Container ID or name' for container_id (already implied) and 'uses default if omitted' for endpoint_id. However, this is limited.
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 clearly states the action 'Stop a running container,' specifying the verb (stop) and resource (container). It distinguishes from sibling tools like portainer_container_start or portainer_container_restart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., stop vs. restart or remove). It does not indicate prerequisites or contexts where stopping is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must cover behavioral traits. It only states the basic operation without disclosing side effects, permissions, or failure modes (e.g., what if container already connected).
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?
Extremely concise with two short sentences that front-load the purpose. Every word is necessary.
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?
An output schema exists, partially compensating for missing return value details. However, the description lacks information about error scenarios or expected behavior, leaving gaps in completeness.
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%. The description adds minimal value by noting that endpoint_id defaults to null if omitted, but otherwise simply repeats parameter names without additional context or constraints.
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 clearly states the action 'Connect a container to a network', identifying the verb and resources. It distinguishes itself from sibling tools like portainer_network_disconnect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or conditions that might make it inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose side effects (e.g., container downtime, configuration reload), permissions, or error states. For a mutative action, this is a significant gap.
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 two sentences: one for action, one for parameter list. No unnecessary words, front-loaded with purpose. Maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is mutative with no annotations and simple parameters, the description should cover prerequisites, return behavior, or side effects. It lacks these, making it incomplete for an agent to use reliably.
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%, but the description adds meaning by noting container_id is ID or name, and endpoint_id defaults to default. However, it does not explain how endpoint_id is used or whether other parameters exist, providing only moderate added value.
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 clearly states 'Restart a container', which is a specific verb-resource pair. Among sibling tools like start and stop, restart is uniquely identified.
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 provides parameter hints but no guidance on when to use restart versus start or stop. Implied usage is clear but no explicit context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavior. Only states 'list all'; lacks details on pagination, rate limits, error handling, or output format.
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?
Single sentence with no redundancy. Every word is necessary and efficient.
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 simple zero-parameter tool with output schema, description is nearly complete. However, it could mention that it returns a list of endpoints.
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?
No parameters; schema coverage is 100% (trivially). Baseline is 3 per rules. Description adds no parameter info beyond schema.
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?
Description clearly states verb ('List') and resource ('all Portainer environments (endpoints)'). It distinguishes from sibling tools like 'portainer_endpoint_inspect' which inspects a single endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. Implies listing all, but no context on filtering or when to use 'portainer_endpoint_inspect' instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose any behavioral traits (e.g., read-only, pagination) beyond the basic listing action.
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?
Extremely concise and to the point with no wasted words; front-loaded appropriately.
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?
Given zero parameters and output schema exists, description adequately conveys the tool's function; could mention output format.
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?
No parameters, schema coverage 100%. Baseline 3 per rule; description adds no param info.
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?
Description clearly states 'List all Portainer users' with specific verb and resource, distinguishing it from sibling tools like portainer_user_inspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; does not mention sibling tools or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description should disclose behavioral traits like read-only nature, permissions, or error handling. It merely states 'Get detailed information' and does not mention that it is a safe, read-only operation or any side effects.
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 extremely concise with two sentences, no redundancy. The purpose is stated first, followed by parameter explanations. Every part earns its place.
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?
Given the presence of an output schema, the description need not explain return values. However, it lacks context on error scenarios, default endpoint behavior, and that the operation is read-only. Still, it is minimally adequate for a simple inspect tool.
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?
The description adds meaning beyond the schema by explaining container_id as 'Container ID or name' and endpoint_id as 'Target endpoint ID (uses default if omitted)'. This compensates for the 0% schema description coverage, though more details about endpoint defaults could be added.
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 clearly states the tool retrieves detailed information about a container, distinguishing it from siblings like container removal or listing. The verb 'Get' and resource 'detailed information about a container' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as portainer_container_logs for logs or portainer_containers_list for container listing. It only lists arguments without any contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits, but it only lists parameters. It does not mention whether removal requires the container to be stopped, whether force removal is destructive, or any irreversible side effects. This is insufficient for an agent to fully understand the tool's behavior.
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 extremely concise with a clear front-loaded purpose statement followed by a clean parameter list. No extraneous text exists; every sentence earns its place.
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?
Given the tool's simplicity (3 parameters, one required, has output schema), the description is mostly adequate but lacks important behavioral context. An agent might not know if the tool can remove a running container without force, or what errors to expect. The presence of an output schema somewhat mitigates the need for return value info, but missing behavioral details reduces completeness.
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 description coverage is 0%, so the description must provide parameter semantics. It does so adequately: clarifies container_id as 'ID or name', force as 'Force removal of a running container (default false)', and endpoint_id as 'Target endpoint ID (uses default if omitted)'. This adds meaning beyond the parameter names.
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 'Remove a container.' This is a clear and specific verb+resource combination. It effectively distinguishes this tool from sibling tools like portainer_container_stop or portainer_container_restart, which deal with different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as stopping or restarting a container. The description lacks any context for appropriate usage or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states the action of removal. Does not disclose consequences (e.g., what happens if image is in use, irreversible changes). Lacks important behavioral context for a destructive operation.
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?
Two efficient sentences: first clearly states purpose, second covers parameters. No unnecessary words, front-loaded with key information.
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?
While the tool is simple, the description omits output details (despite presence of output schema) and lacks safety notes. For a destructive action, more context on side effects or prerequisites would improve completeness.
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?
Despite 0% schema description coverage, the description adds meaning: it clarifies image_id format ('Image ID or name:tag') and endpoint_id behavior ('uses default if omitted'). This compensates for the schema's lack of documentation.
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 clearly states 'Remove a Docker image.' It uses a specific verb (Remove) and resource (Docker image), distinguishing it from sibling tools like inspect, pull, list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as portainer_image_inspect or portainer_images_list. No context about prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose any behavioral traits such as ordering, pagination, permissions, or whether it lists all stacks globally or per endpoint. For a list tool, behavior like scope or limits should be mentioned.
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 a single, concise sentence that captures the purpose without any wasted words. It is appropriately front-loaded and efficient.
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?
The tool has no parameters and an output schema exists (though not shown), but the description is still minimal. It does not mention what the output contains (e.g., IDs, names, statuses) or any potential limitations. Adequate for a simple list but could be more informative.
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?
The tool has zero parameters, so the description does not need to add meaning beyond the input schema. Baseline score of 4 is appropriate as there is nothing to describe.
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 'List all Portainer stacks' clearly states the action (list) and the resource (stacks). It is specific and distinguishes from sibling tools like portainer_stack_inspect or portainer_stack_deploy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as for getting details of a specific stack or deploying a stack. The description only states what it does, not when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It lists arguments with defaults but does not describe what happens on success/failure, whether existing volumes cause errors, or any required permissions. Minimal behavioral context.
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?
Very concise, front-loaded with the purpose, followed by a clear list of arguments. No unnecessary words.
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?
Lacks information on error behavior, prerequisites, or side effects. Given output schema exists, return values not needed, but more details on behavior would improve completeness for a creation tool.
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 0%, so description compensates by explaining each parameter: name (required), driver (default 'local'), labels (key-value pairs), endpoint_id (default if omitted). Adds meaning beyond schema types and defaults.
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 clearly states 'Create a Docker volume' which is a specific verb and resource. Among sibling tools, there are volume_inspect, volume_remove, volumes_list, making this distinct. No title needed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. It simply states what it does without context like prerequisites or when not to use it (e.g., if volume exists).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must disclose behaviors. It only states it gets information, omitting details on error handling, permissions, or side effects. The tool is likely read-only, but this is not explicitly stated.
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 extremely concise: a single line for purpose and a brief parameter breakdown. No redundant text; front-loaded with the core function.
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?
Given the tool's simplicity and presence of an output schema, the description is largely complete. It could mention that details are returned as JSON, but this is implied by 'detailed information'. For a low-complexity tool, the description suffices.
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?
The description adds significant meaning beyond the schema: it explains image_id format ('ID or name:tag') and clarifies endpoint_id as optional with a default. Schema coverage is 0%, but the description compensates well.
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 clearly states the tool retrieves detailed information about a Docker image, with a specific verb ('Get') and resource ('detailed information about a Docker image'). This distinguishes it from sibling tools like list or pull.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., portainer_images_list for listing images). The description does not indicate prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation via the verb 'List', but it does not explicitly state that no modifications occur or mention any side effects. Since no annotations are provided, the description carries the full burden for transparency; the lack of an explicit safety note is a minor gap.
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 extremely concise, containing a one-line summary and a simple Args list. Every sentence adds value, and the structure is clean and scannable.
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?
Given the simplicity of the tool (one optional parameter, no nested objects), the description is largely complete. It specifies the resource, the returned attributes, and the parameter behavior. It omits output schema details and error handling, but these are not essential for a list operation and can be inferred from the schema.
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?
The single parameter endpoint_id is described as 'Target endpoint ID (uses default if omitted)', providing a basic functional explanation. However, it does not explain what an endpoint is, how to obtain a valid ID, or the impact of omitting it beyond using a default. Schema coverage is 0%, so this limited description only partially compensates.
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 clearly states the verb 'List' and the resource 'Swarm nodes', specifying the attributes returned (role, availability, state, resources). This is unambiguous and distinguishes the tool from other list tools in the sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as portainer_docker_info or portainer_services_list. The description does not mention typical use cases or selection criteria, leaving the agent to infer from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral transparency. It does not explicitly state that the operation is read-only, nor does it mention any side effects, safety guarantees, or error conditions (e.g., if the endpoint is not a Swarm). The lack of such disclosure leaves the agent guessing about potential impacts.
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 concise (two sentences) and well-structured, with the core purpose front-loaded. The additional explanation about services vs. tasks and cron-driven services adds useful context without becoming verbose. It slightly exceeds minimalism but remains efficient.
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?
The description mentions the output concept (replica counts) and a special case (cron-driven services), providing enough context for typical usage. It does not address edge cases like non-Swarm endpoints or error handling, but given the output schema exists and the core purpose is clear, it is largely complete for common scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for parameter explanations. It does not describe 'endpoint_id' or 'stack_filter' at all; only the parameter names are given. While the names are self-explanatory to an experienced user, the description provides no details on expected formats, semantics, or interaction between the parameters, leaving significant room for misinterpretation.
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 clearly states the action ('List') and the resource ('Swarm services') with an outcome ('running/desired replica counts'). It differentiates from sibling tools by explaining the primary view for services and contrasting with containers as tasks, making the purpose unambiguous.
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?
The description provides context on when to use this tool — it is the primary view for Swarm services, and it notes the special case of cron-driven services. However, it does not explicitly state when to prefer alternatives like service_inspect or service_tasks, though the context implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions force removal and default behavior but omits side effects, error conditions, or permission requirements. The destructive nature is implied but not elaborated.
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 concise and front-loaded with the main action. The parameter list is clear, though could be slightly more structured or include a brief statement on return value.
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?
Given an output schema exists (not shown), the description covers removal basics but lacks context on success/error responses or example usage. It is adequate for a simple removal tool but not fully complete.
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 description coverage is 0%, so the description adds meaning beyond the input schema by explaining each parameter's purpose and default behavior. This adequately compensates for the lack of schema descriptions.
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 clearly states 'Remove a Docker volume,' specifying the verb and resource. It effectively distinguishes from sibling tools like portainer_volume_create, portainer_volume_inspect, and portainer_volumes_list.
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 lists parameters and default behaviors but lacks explicit guidance on when to use this tool vs alternatives, such as prerequisites or situations where other tools are better suited. Usage context is implied but not directly addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the behavioral burden. It communicates a read-only log retrieval action and explains the endpoint fallback behavior, but it does not disclose authentication needs, potential output size or truncation, or any operational constraints beyond the endpoint default.
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 front-loaded with a one-line purpose followed by a compact, scannable Args list. There is no filler, repetition of schema titles, or unnecessary prose.
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 tool with five parameters, no schema descriptions, and no annotations, the description documents every parameter and the endpoint default behavior. An output schema exists, so return-value details are not required; the main remaining gap is usage guidance relative to sibling tools, which is already penalized under usage_guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter in plain language. It provides defaults and max for tail, accepted formats for since, timestamp behavior, and endpoint fallback semantics, which is substantial added value beyond the bare schema.
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 clearly states the operation as 'Get container logs,' which is a specific verb-resource pair, and the Args list makes the target container explicit. It does not explicitly differentiate itself from sibling log tools such as portainer_container_logs_grep or portainer_service_logs, so it does not fully satisfy sibling distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool instead of alternatives like portainer_container_logs_grep, portainer_service_logs, or portainer_stack_logs_errors. The agent is left to infer selection purely from the tool name and the generic operation statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only says 'live stats' with no mention of safety, impact, rate limits, or whether it's read-only. Minimal behavioral disclosure.
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?
Extremely concise with one-line purpose and two-line args explanation. Front-loaded and no extraneous text.
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?
Covers purpose and parameters adequately but lacks usage context and behavioral details. Output schema exists, so return info is not needed. Adequate but could be improved.
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 0%, so description must explain params. It provides clear mapping for both container_id and endpoint_id, adding value beyond schema types.
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?
Description clearly states 'Get live CPU, memory, and network stats for a container' with specific verb and resource, distinguishing it from sibling tools like inspect or logs.
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?
No guidance on when to use vs alternatives or prerequisites; only mentions default for endpoint_id. Implicit but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits, but it only states the action and parameters. Missing side effects (e.g., container loses connectivity) or prerequisites.
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?
Extremely concise and well-structured: one-line purpose followed by a clear parameter list. Every sentence is warranted.
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?
Adequate for a simple action with four parameters and output schema present, but lacks behavioral context and edge cases (e.g., container not connected).
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 description coverage is 0%, so the description must compensate. It adds meaning by briefly explaining each parameter (e.g., 'Network ID or name', 'force disconnect (default false)').
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 clearly states the action 'Disconnect a container from a network', which is specific and distinguishes it from sibling tools like portainer_network_connect.
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?
No explicit guidance on when to use or when not to use, but the purpose is clear enough for an agent to infer usage context. Lacks exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only mentions 'Remove' without side effects, error conditions, or requirements (e.g., network not in use). For a destructive operation, this is insufficient.
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?
Extremely concise: two lines for description and a simple arg list. Every sentence is necessary and information is front-loaded.
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?
Tool is simple with two params and an output schema exists, so description doesn't need return values. However, it lacks usage guidelines and behavioral details, making it barely adequate for safe use.
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 0%, but the description explains both parameters: network_id can be ID or name, endpoint_id is optional with default. This adds meaning beyond the schema's type definitions.
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 clearly states 'Remove a Docker network.' which is a specific verb and resource, distinguishing it from sibling tools like network_create, network_inspect, etc.
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?
No explicit guidance on when to use this tool versus alternatives (e.g., network_disconnect) or prerequisites (e.g., network must be disconnected from all containers). Usage is implied but not clarified.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavior. It mentions the action 'start' but omits side effects, prerequisites, error handling, or idempotency. For a mutation tool, this is a significant gap.
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 extremely concise, with a single-purpose sentence followed by clear parameter explanations. No redundant wording; every sentence adds value and the purpose is front-loaded.
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?
Given the simplicity of the action and the presence of an output schema, the description covers the essential purpose and parameters. However, it lacks any mention of failure modes, prerequisites, or behavior when the stack is already running, leaving the agent without complete context for a state-changing operation.
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?
With 0% schema description coverage, the description compensates by explaining both parameters: stack_id as the target stack, and endpoint_id with a note that it is derived from the stack if omitted. This adds meaningful context beyond the schema's bare titles and types.
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 clearly states the action 'Start a stopped stack' with a specific verb and resource. It distinguishes from sibling tools like portainer_stack_stop and portainer_stack_deploy by its focus on starting an already-existing, stopped stack.
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 usage when a stack is stopped, but does not explicitly compare with alternatives or state conditions for non-use. It lacks guidance on when to prefer this over deploy/update or when to avoid it, such as if the stack is already running.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions that the command runs via sh -c and returns output, but does not disclose potential side effects, authentication needs, or execution behavior (e.g., synchronous, timeout).
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 brief with two sentences and a bullet list of arguments. It is front-loaded with the purpose and contains no unnecessary words.
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?
Given 5 parameters (2 required) and an output schema exists, the description covers most aspects. It lacks behavioral details like error handling or return format, but output schema compensates.
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 description coverage is 0%, so the description must add meaning. It explains that command runs via sh -c and provides examples for user. Missing details for workdir and endpoint_id, but overall adds significant value beyond schema.
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 clearly states 'Execute a command inside a running container and return its output.' This specific verb-resource combination distinguishes it from sibling tools like inspect, logs, or start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when to prefer exec over logs or start. No scenarios or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses default behavior for endpoint_id and that reference_filter is a server-side Docker filter, but does not explicitly state that the operation is read-only or mention any side effects, permissions, or response details. With no annotations, the description provides moderate transparency.
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 brief and front-loaded with the main purpose. The argument list is clear but slightly verbose (e.g., 'Target endpoint ID (uses default if omitted)'). Could be more terse, but no wasted sentences.
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?
Given the tool's simplicity and the presence of an output schema, the description covers the core purpose and parameter semantics. It lacks mention of read-only nature or authentication requirements, but these are partially implied by the action. Mostly complete for a list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully explains both parameters: endpoint_id (target endpoint, defaults if omitted) and reference_filter (filter by image reference, with examples). This adds significant meaning beyond the bare schema.
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 clearly states the action ('List'), resource ('Docker images'), and scope ('on an endpoint'). It distinguishes itself from sibling tools like portainer_image_inspect (single image), portainer_image_pull (download), and portainer_image_remove (deletion).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., portainer_image_inspect for details on one image). The description does not provide when-not-to-use or compare with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions default behavior for endpoint_id and that name_filter is a server-side Docker filter, which is good. However, it does not disclose pagination, error states, or any limitations like return format or access restrictions.
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 very concise: a one-line purpose followed by two lines for each parameter. It is well-structured and front-loaded, with no redundant information.
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?
The description covers the arguments adequately but lacks broader context such as error handling, authentication requirements, whether the result is filtered by user permissions, or any prerequisites for the endpoint. Given the simplicity of the tool and the presence of an output schema, it is somewhat complete but could be improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully explains both parameters: endpoint_id's usage and default, and name_filter's substring filtering and server-side nature. This adds significant meaning beyond the schema's type and title.
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 clearly states the action ('List') and resource ('Docker networks') along with the scope ('on an endpoint'). This distinguishes it from sibling tools like portainer_network_inspect or portainer_network_create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives, such as inspecting a single network or creating one. The description does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool only returns names and metadata and never values, which is a behavioral trait. However, it does not explicitly state that the operation is read-only or safe, nor does it mention any permissions or side effects. Since there are no annotations, the description carries the full burden but falls short of comprehensive disclosure.
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 concise and well-structured, with two sentences: one for the main action and one for the parameter. There is no redundant information, and the phrasing is direct and efficient.
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 simple list operation, the description covers the essential aspects: what it lists, the parameter meaning, and the output limitation. It does not mention the output schema or prerequisites, but these are not critical for a tool of this complexity. The description is sufficiently complete for an agent to use it correctly.
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?
The description explains the endpoint_id parameter as 'Target endpoint ID' and notes that it defaults if omitted. This adds meaning beyond the raw schema (which only lists type and default), clarifying the parameter's purpose and optionality.
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 clearly states the action ('List Swarm secrets') and specifies the scope ('names and metadata only — never the values'), which makes its purpose unambiguous and distinguishes it from other list tools like portainer_containers_list or portainer_networks_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives. While the purpose is clear, the description does not mention conditions for use or contrast with other list tools, leaving the agent to infer usage contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description only says 'Get detailed information'. Does not disclose safety (read-only), authentication needs, error behavior, or other traits. With zero annotation coverage, description should provide more behavioral context.
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?
Extremely concise, front-loaded purpose, parameter list with clear one-liners. No unnecessary words.
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?
With an output schema present, the description doesn't need to explain return values. Covers basic usage adequately. Slight gap in error scenarios or prerequisites, but acceptable for an inspect tool.
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?
Adds meaning beyond schema: clarifies endpoint_id as 'Target endpoint ID' and explains default behavior ('uses default if omitted'). For volume_name, only restates schema, but overall improves understanding. Schema coverage is 0% so description compensates well.
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?
Clearly states 'Get detailed information about a Docker volume' with a specific verb and resource. Distinguishes from sibling tools like volume_create, volume_remove, and volumes_list.
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?
Implied usage for inspecting volume details, but no explicit when-to-use, when-not-to-use, or alternative tool guidance. Siblings include inspect for other resources, but no differentiation mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states 'List', implying a read-only operation, but does not explicitly mention safety, authorization needs, rate limits, or any side effects. The minimal disclosure leaves gaps for an agent.
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 extremely concise: one sentence stating the purpose, followed by a clean bullet-style parameter listing. Every sentence is useful, and the main verb is front-loaded.
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?
Given that an output schema exists, the description does not need to detail return values. It adequately covers the tool's purpose and parameters. However, it could mention that the operation is a list (implying multiple volumes returned) or any ordering/pagination, but this is minor.
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?
The input schema has 0% description coverage, so the description carries the burden. It clearly defines both parameters: endpoint_id (target endpoint, defaults if omitted) and name_filter (substring filter). This adds meaningful context beyond the schema's bare types.
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 clearly states 'List Docker volumes on an endpoint', specifying the action and resource. It distinguishes from siblings like portainer_volume_inspect (inspect specific volume) and portainer_volume_remove (remove volumes).
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 explains the parameters (endpoint_id defaults, name_filter substring), but does not explicitly state when to use this tool versus alternatives like portainer_volume_inspect or when not to use it. It provides basic guidance but lacks explicit when/when-not contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only operation ('Get'), which is inferred. No behavioral traits such as authorization requirements, rate limits, or side effects are disclosed. Without annotations, the description provides minimal transparency beyond the basic read nature.
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 extremely concise: one line for purpose and one line for parameter. Every word serves a purpose, and the essential information is front-loaded. No redundancy or filler.
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 simple disk usage query, the description covers the what and the parameter. Since an output schema exists, return values are not required. The only minor gap is the lack of explanation about the output structure or behavior when endpoint_id is invalid, but overall it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, endpoint_id, is fully explained: it's optional and defaults to the user's default endpoint if omitted. The schema provides no description (0% coverage), so the description compensates completely, adding clarity that the agent would otherwise lack.
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 clearly identifies the tool's purpose: getting Docker disk usage including containers, images, volumes, and build cache. The verb 'Get' and specific resource list make it unambiguous and distinct from sibling tools like portainer_container_stats or portainer_docker_info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, fallbacks, or exclusions. Sibling tools with overlapping functionality (e.g., portainer_docker_info) are not differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only lists parameters and their meanings; it does not mention that this is a read-only operation, potential large output, pagination, or any side effects. The phrase 'all its tasks, across nodes' adds some scope detail but insufficient behavioral context.
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 concise and well-structured. The purpose is stated in one sentence, followed by a clean Args list with each parameter on its own line. No redundant information; every sentence provides value.
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?
Given that an output schema exists (so return format is defined there), the description is nearly complete for a logs tool. It covers all parameters and their formats. Minor gaps include lack of mention about pagination or error behavior, but these are less critical given the output schema and simple nature of the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only source of parameter meaning. It thoroughly explains each parameter: service_id accepts ID or name, tail has a default and max, since accepts multiple formats, timestamps is a boolean, and endpoint_id falls back to default. This fully compensates for the lack of schema descriptions.
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 clearly states the tool retrieves logs for a Swarm service, explicitly including all tasks across nodes. This distinguishes it from container or stack log tools, and the verb+resource+scope are specific and unambiguous.
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 when to use this tool (for Swarm service logs) but does not explicitly mention alternatives or conditions for not using it. Sibling tools like portainer_container_logs and portainer_stack_logs_errors are not referenced, so an agent must infer the appropriate choice from the scope alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly states that content is never returned, which informs about data exposure and implies a read-only nature. Since no annotations are present, this transparency is valuable and largely sufficient.
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 concise and to the point, with a clear main statement followed by a brief args note. No unnecessary words or repetitive information are present.
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 simple list operation, the description provides sufficient context: the resource type, the scope via endpoint_id, and the returned data type. It does not cover output formatting or pagination, but these are not critical for a basic listing.
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?
The only parameter, endpoint_id, is explained as 'Target endpoint ID (uses default if omitted)' in the description. This adds meaning beyond the raw schema, which has no description, and clarifies the parameter's role.
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 clearly states the action (list), the resource (Swarm configs), and a key restriction (names and metadata only, never content). This is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not mention suitable scenarios or comparisons to sibling tools, so the user must infer applicability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only describes what the tool does but does not state that it is a read-only, idempotent operation or mention any side effects, safety, or authentication requirements.
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 extremely concise: two short sentences with bulleted args. The purpose is front-loaded, and every word adds value. No unnecessary details.
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?
Given the tool's simplicity (one optional parameter, output schema exists), the description adequately covers the purpose and parameter. It could mention error conditions or endpoint validation, but for minimal context it is complete.
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?
The description adds meaning to the endpoint_id parameter by explaining it is a target ID and defaults to omitted, which is not present in the schema (0% coverage). This provides useful guidance beyond the raw schema.
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 clearly states 'Get Docker system information for an endpoint' with examples (OS, CPU, memory, containers count), distinguishing it from sibling tools that focus on containers, images, networks, etc.
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?
The description implies when to use (when system-level info is needed) and explains the endpoint_id parameter usage, but does not explicitly mention when not to use or list alternatives like portainer_endpoint_inspect for endpoint metadata.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses default driver ('bridge') and mentions 'overlay for Swarm' and internal restriction, but it omits side effects (e.g., error on duplicate network), idempotency, permissions, and the return value (though an output schema exists, it's not described).
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 concise: one-line purpose followed by a bulleted parameter list. Every sentence adds value, and it's front-loaded with the action. No unnecessary words.
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?
The description covers parameter semantics well, but lacks behavioral details (e.g., what happens if network already exists, error handling) and usage guidance (e.g., when to use this vs other network tools). The output schema exists but is not referenced, leaving the agent to infer return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description explains all parameters: name (required), driver (default 'bridge', 'overlay' for Swarm), internal (restricts external access), labels (optional key-value), endpoint_id (target endpoint, default omitted). This adds meaningful context beyond the schema.
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 clearly states 'Create a Docker network,' using a specific verb and resource. It distinguishes itself from sibling tools like network_connect, network_disconnect, network_inspect, network_remove, and networks_list, all of which serve different purposes.
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 usage by listing parameters and providing a driver hint (overlay for Swarm), but it does not explicitly state when to use this tool versus alternatives, nor does it specify prerequisites or conditions such as requiring an existing endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states 'Get details' without explicitly indicating it is a read-only operation, nor does it mention any authentication requirements, error handling, or side effects.
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 extremely concise with one sentence and an Args line, front-loaded with the purpose, containing no unnecessary words.
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 simple read tool with one parameter and an existing output schema, the description captures the core purpose. However, it could mention it is a read operation and provide brief context about what details are returned.
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?
The schema has 0% description coverage, but the description adds 'The ID of the user to inspect' for the user_id parameter, clarifying its role beyond the schema's type and requirement.
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 clearly states 'Get details of a specific Portainer user', using a specific verb (get) and resource (details of a user), and implies singularity which distinguishes it from the sibling 'portainer_users_list' which lists users.
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?
The description implicitly indicates usage for retrieving a single user's details, but lacks explicit when-not-to-use or alternative guidance. The context of siblings like 'portainer_users_list' aids differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose key behaviors: env variables are 'substituted into the compose file by Portainer' and endpoint_id 'uses default if omitted'. However, it does not mention permissions, whether the deployment is asynchronous, or if the stack is immediately started. This leaves some behavioral aspects uncovered.
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 concise and front-loaded with the core purpose in one sentence, followed by a clean, well-formatted args list. Every sentence and line adds value with no redundancy. The structure makes it easy for an agent to quickly parse the essential information.
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?
Given an output schema exists, the description need not explain return values. It covers the purpose, all parameters, and key behaviors. It could mention prerequisites like authentication or that the stack is created and started, but these are typical for a deploy operation and not critical. Overall, it is sufficient for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must fully explain each parameter. It does so clearly: name ('Name of the new stack'), compose_content ('Docker Compose file content (YAML string)'), env ('Stack environment variables... e.g. {"DB_PASSWORD": "..."}'), and endpoint_id ('Target endpoint ID (uses default if omitted)'). This adds significant meaning beyond the bare schema.
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 clearly states the tool's purpose: 'Deploy a new stack from a docker-compose string.' This identifies the verb (deploy), resource (stack), and method (from a compose string), distinguishing it from sibling operations like update, delete, or start. It is specific and unambiguous.
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 the tool is for creating new stacks via 'Deploy a new stack', but it does not explicitly mention when not to use it or point to alternatives such as portainer_stack_update for existing stacks. No exclusions or alternative routing are provided, leaving the agent to infer usage context from the tool name and sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It discloses core behavior: regex matching, case-insensitivity, tail pre-filtering, context lines, time filtering, timestamps, and endpoint selection. However, it omits edge-case behavior such as invalid regex handling, empty result behavior, permission requirements, or error conditions. For a read-only tool with no annotations, this is adequate but not thorough.
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 well-structured with a lead sentence, a use-case note, and a parameter list. It is slightly verbose but each sentence earns its place. The most critical purpose and usage are front-loaded, and the parameter details are concise. No redundant information.
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?
Given the output schema exists, the description need not explain return values. All seven parameters are semantically explained, including defaults and constraints. The tool is moderately complex, and the description covers all relevant inputs and behavior. It lacks mention of potential errors or limits on pattern complexity, but for typical usage it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fully compensates by explaining every parameter in the Args section: container_id, pattern (case-insensitive), tail (lines to fetch before filtering, defaults and max), context_lines (default and max), since (formats), timestamps, and endpoint_id. It adds meaning beyond the schema's type-only definitions.
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 clear verb-resource pair: 'Search container logs for lines matching a regex pattern.' It differentiates itself from sibling portainer_container_logs (which presumably returns full logs) by focusing on filtered results with optional context, and explicitly notes the use case of finding errors/status codes without downloading full logs.
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?
The description gives a clear context for use: 'Useful for finding specific errors, status codes, or keywords without downloading the full log.' It implies when to prefer this over a full-log tool, though it does not explicitly name alternatives or say when not to use. The sibling list includes portainer_container_logs and portainer_stack_logs_errors, so an agent could infer the distinction, but the description could be more explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description details the error patterns searched (HTTP 4xx/5xx, exceptions, panics, etc.) and notes logs are fetched from every running container with the stack prefix. It does not explicitly state that the tool is read-only, but the absence of annotations is compensated by clear behavioral description.
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 concise with a clear opening sentence, a list of error patterns, and an Args section. It is front-loaded but contains minor redundancy in listing error pattern examples both in prose and bullet points.
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?
Given the tool's complexity and lack of schema descriptions, the description adequately covers purpose, usage, parameters, and behavior. An output schema exists, so return values need not be detailed. Minor gaps, such as whether the tool stops on first error, do not hinder completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds full meaning for all three parameters: stack_name as prefix, tail with default and max, endpoint_id as optional. This exceeds the bare schema.
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 clearly states the tool scans all running containers in a stack for errors, with a specific verb and resource. It distinguishes itself from sibling log tools by focusing on stack-wide error detection.
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 usage for stack error scanning but does not explicitly state when to use this tool over alternatives like portainer_container_logs_grep. No exclusions or contextual guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of revealing behavior. It clearly discloses that credential-looking environment values are masked unless reveal_env=true, which is a key behavioral trait.
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 succinct, with a clear purpose statement and a well-organized parameter list. No unnecessary filler is present.
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?
The description mentions the output includes spec, update status, and endpoint, which gives a good sense of the return content. It does not detail the output schema, but the presence of an output schema and the explicit description of returned fields make it sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no descriptions, but the description explains all three parameters: service_id (ID or name), reveal_env (unmask credentials), and endpoint_id (target endpoint). This fully compensates for the 0% schema coverage.
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 clearly states that the tool retrieves the full Swarm service definition, including spec, update status, and endpoint. This distinguishes it from related tools like service logs, tasks, or updates.
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 use for inspecting a service's full definition but does not explicitly contrast it with alternatives such as service_tasks or service_logs. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description names the core action and necessary precondition, but without annotations it does not disclose potential side effects, error behavior, permission requirements, or whether the rollback is asynchronous (though the wait follow-up implies it). This is adequate but not rich.
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 brief and direct, with the main action stated first, a concise precondition, and a helpful follow-up hint. No filler or 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 simple rollback operation, it covers the essential context: what it does, when it applies, and next step. Since an output schema exists, not detailing the return value is acceptable. Minor omissions like possible errors are not critical here.
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?
Although the schema has no formal descriptions, the inline Args text adds useful meaning: service_id can be a name or ID, and endpoint_id defaults to a target if omitted. This goes beyond the raw schema types.
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 clearly states the tool's purpose: 'Roll a Swarm service back to its previous spec', with an explicit docker command reference and the resource type (Swarm service). It is easily distinguished from sibling tools like service_update and service_inspect.
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?
The description provides a clear precondition ('Works only while Swarm still holds a PreviousSpec, i.e. after at least one update') and directs the user to follow up with portainer_service_wait, which is actionable guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the internal process: 'Reads the current spec and version, applies the requested changes and submits the spec back (rolling update per the service's UpdateConfig).' It also details behavior for force_restart ('re-creates the tasks even if the spec is unchanged') and how image tag resolution works ('Swarm resolves the tag to its current digest at update time'). This is rich behavioral context beyond the schema.
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 well-structured with a clear opening sentence, a brief operational overview, and a bulleted list of parameters. It front-loads the primary purpose and includes necessary details without redundancy. It is a bit longer than minimal, but each sentence serves a purpose (e.g., explaining the :latest edge case, which is important). No wasted words.
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?
Given the tool's complexity (6 parameters, one required, update operation) and the presence of an output schema (so return values need not be explained), the description is complete. It covers required fields, the follow-up tool, parameter nuances, and operational behavior. It does not mention potential side effects or failure handling, but those are minor given the output schema and the clear workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does so thoroughly: each parameter is explained with meaningful detail. For example, image is given an example format, registry_id explains auto-detection and 0 meaning none, endpoint_id notes default behavior, and force_restart is equated to 'docker service update --force'. This fully addresses the parameter semantics gap.
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 opens with 'Update a Swarm service: change its image, scale it, or force a restart.' This states a clear verb (update), resource (Swarm service), and enumerates the specific operations. It distinguishes from siblings like portainer_service_rollback (which reverts to a previous spec) and portainer_service_inspect (read-only). The purpose is unambiguous.
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?
The description provides explicit usage context: it states the required parameter set ('At least one of image / replicas / force_restart is required') and instructs to 'Follow up with portainer_service_wait to know when the rollout converged.' It explains how to use it for rolling out a new build with a :latest tag. However, it does not explicitly contrast with alternatives like portainer_service_rollback or portainer_stack_update, so it lacks explicit when-not-to-use guidance. This is a minor gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry behavioral disclosure. It does by explaining the masking of credential-looking values (REDACTED) and the conditional reveal_env behavior, plus the consequence of a masked file being rejected by the update tool. This is important and non-obvious behavior. It doesn't explicitly state read-only, but the verb 'Get' and tool name 'inspect' imply it.
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 concise and well-structured: a one-sentence purpose, a critical behavioral note, then a short Args section. It front-loads the purpose and the masking behavior, which is essential. The Args section is slightly redundant with the schema, but since the schema lacks descriptions, it earns its place.
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?
The tool has an output schema, so return value details are covered. The description covers the key behavioral aspects (masking, reveal_env) and the interaction with the update tool, which is a common pitfall. For a simple read-only inspect with two parameters, this is sufficiently complete. Missing error conditions or pagination are not critical here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the parameters. It does: stack_id is defined as 'The ID of the stack to inspect' and reveal_env as 'Return credential values unmasked (default false)'. This adds clear meaning beyond the bare schema, fully compensating for the lack of schema descriptions.
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 opens with a clear verb+resource: 'Get details of a stack including its compose file content.' This distinguishes it from sibling tools like portainer_stacks_list (listing stacks) and portainer_stack_status (status only), and it goes beyond a generic statement by specifying the compose file content as a key output.
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?
The description provides a concrete usage guideline: 'Always inspect with reveal_env=true before resending the compose file through portainer_stack_update — a masked file is rejected.' This tells the agent exactly when to set reveal_env. It doesn't explicitly contrast with other inspect tools, but the sibling context and the tool's name make the primary use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of transparency. It discloses the type of information returned (connection status, auth status, endpoint count, Swarm cluster flag) and implies a read-only operation. It does not explicitly state side effects or failure modes, but for a status-checking tool, the behavior is adequately described.
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 extremely concise, consisting of two sentences that pack all necessary information without redundancy. It front-loads the primary purpose and adds a useful contextual note. No wasted words.
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?
The description covers what the tool does, what it reports, and why it matters (decision between service- and container-level tools). Combined with the presence of an output schema (though not shown), the agent has enough context to use the tool effectively. The note about 'first thing' provides strategic context that enhances completeness.
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?
The tool has zero parameters, and the input schema is empty. Per the baseline rule for 0 parameters, a score of 4 is appropriate. The description correctly omits any parameter details since none exist.
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 clearly states the tool's function: check Portainer connection and authentication status, plus report endpoint count and Swarm cluster status. This is a specific, well-defined purpose that distinguishes it from the many sibling tools (e.g., it's not about managing containers or networks). The phrase 'the first thing an agent needs' further clarifies its role.
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?
The description gives implicit usage guidance by positioning the tool as a preliminary check for deciding between service-level and container-level tools. While it doesn't explicitly say 'use this when you need to verify connectivity or cluster mode,' the context is sufficient for an agent to infer when to invoke it. It lacks explicit alternatives but the hint about decision-making is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for disclosing behavior. It clearly states this is a destructive action ('remove stopped containers, unused images or build cache') and explicitly warns that volumes are never pruned to prevent data loss. It also details the distinction between dangling and all images via the all_images parameter. It doesn't mention permissions or error handling, but for a prune tool, it covers the essential destructive aspects thoroughly.
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 organized with a clear opening summary, a note about volumes, a usage hint, and an Args section. It's slightly longer than necessary but every section serves a purpose: the volume warning is critical, the disk_usage suggestion is helpful, and the args list is concise. The key information is front-loaded, making it easy to scan. A tighter wording could reduce length, but it's not padded.
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?
Given the tool's destructive nature and three parameters, the description covers the main operational aspects: what it prunes, how targets differ, how all_images modifies behavior, and endpoint selection. It also suggests checking disk usage first. The presence of an output schema covers return-value documentation. It doesn't mention edge cases like invalid targets or partial failures, but those are less critical for an agent deciding whether to call the tool. Overall, it's complete enough for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must fully compensate. It does so by explaining each parameter: target with its valid values ('containers', 'images', 'build_cache'), all_images with its effect ('also remove tagged images not used by any container' and default behavior), and endpoint_id ('Target endpoint ID (uses default if omitted)'). This adds significant meaning beyond the raw types in the schema.
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 opens with 'Reclaim disk space: remove stopped containers, unused images or build cache', which is a specific verb+resource statement that clearly identifies the tool's purpose. It also explicitly distinguishes from portainer_volume_remove by stating volumes are never pruned, and references portainer_docker_disk_usage as a complementary tool. This makes it easy for an agent to differentiate from siblings.
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?
The description provides explicit when-to-use guidance: 'Volumes are never pruned by this tool (that destroys data); use portainer_volume_remove for a specific volume' and 'Check portainer_docker_disk_usage first to see what is reclaimable.' It also explains the meaning of the 'target' parameter values, giving clear context for when each is appropriate. This leaves no ambiguity about when to invoke this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the read-only nature through 'List', explains what the task error contains with concrete examples, and describes limit behavior ('newest per slot first'). This adds meaningful behavioral context beyond the schema.
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 compact and front-loaded with the core purpose, followed by a high-value diagnostic note and concise parameter explanations. There is no filler; every sentence adds either selection guidance or invocation detail.
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?
The description is complete for a list operation with three parameters and an output schema. It covers what the tool returns, when to use it, how parameters behave, and diagnostic interpretation of the error field. The output schema handles return format details, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description's Args section fully compensates: service_id is 'Service ID or name', limit is 'Max tasks to return, newest per slot first (default 50, max 500)', and endpoint_id is 'Target endpoint ID (uses default if omitted)'. Every parameter receives semantic meaning beyond its schema type and title.
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 opens with a specific verb and resource: 'List a service's tasks with state, node and error', which clearly identifies what the tool does. It also names the Docker equivalent (`docker service ps`) and is distinct from sibling tools like service logs, service inspect, or services list.
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 provides explicit guidance on when to use the tool: 'The first place to look when replicas are not coming up', and explains that the task error carries scheduler/container start failures. It does not list exclusions or explicitly name alternatives, but the usage context is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains the polling behavior, the three stop conditions, the return summary fields (converged, reason, timed_out, recent task errors), and the timeout clamping. It does not mention auth or rate limits, but these are less critical for a wait operation and the description covers the essential behavioral aspects.
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 concise and well-structured. It front-loads the core purpose, then lists args with brief explanations. Every sentence adds value, with no fluff or redundancy.
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?
The description is complete for an agent to call the tool correctly. It covers the purpose, parameters, behavior, and return information (the output schema presumably defines the return structure). No critical information is missing, such as prerequisites or error handling, given the simple nature of a wait operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does so excellently: service_id is explained as 'Service ID or name', timeout_seconds is described with default and clamping range, and endpoint_id is clarified as 'Target endpoint ID (uses default if omitted)'. This adds meaning far beyond the bare schema titles.
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 clearly states the tool's purpose: waiting for a service rollout to converge after an update/rollback. It specifies the verb ('wait'), the resource ('service rollout'), and the context ('after an update/rollback'). It also details the termination conditions, distinguishing it from inspection or task-listing tools.
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?
The description implicitly guides usage by specifying 'after an update/rollback', which clearly ties it to portainer_service_update and portainer_service_rollback. However, it does not explicitly name alternatives (e.g., portainer_stack_wait for stacks) or state when NOT to use it, so it misses the explicit exclusions needed for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It discloses polling behavior, termination conditions (healthy, paused on failure, timeout), and the return structure. It also mentions timeout clamping (5..PORTAINER_LONG_TIMEOUT), which is a useful behavioral detail. It does not cover error handling or auth, but for a wait operation this is adequate.
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 compact and well-structured: a purpose sentence, a behavior sentence, and an Args list. No filler. The key purpose is front-loaded, and the Args section is formatted for easy scanning.
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 an output schema present, the description needn't detail return values beyond what it does (mentions converged, reason, timed_out). It covers purpose, usage, behavior, and all parameters. It even names the polling target (portainer_stack_status). For a wait tool, nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must document parameters. The Args section does this well: stack_name (namespace/project), timeout_seconds (default, clamp), endpoint_id (default if omitted). This adds significant meaning beyond the bare schema, making parameter usage clear.
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-resource pair: 'Wait for a stack's rollout to converge after stack_update.' It clearly differentiates from siblings like portainer_stack_inspect or portainer_stack_update, and even mentions the return fields (converged, reason, timed_out) which further clarifies its role.
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 clearly states the trigger context: 'after stack_update.' This tells an agent when to invoke it. It also references polling portainer_stack_status, giving a hint of dependency. However, it does not explicitly name alternatives or when not to use it (e.g., portainer_service_wait for services), so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The word 'List' implies a read-only operation with no side effects, and the description clarifies that credentials are not returned but rather used by Portainer. No annotations are present, but the description is reasonably transparent for a simple listing operation.
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 two concise sentences with no redundant information. It front-loads the core purpose and then provides essential downstream usage detail.
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?
For a no-parameter listing tool, the description fully covers what is returned and how to use the result. No additional context is needed for correct invocation.
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?
The tool takes no parameters, so the baseline is 4. The description adds useful context by listing the output fields (id, name, URL, type), which is sufficient given the zero-parameter input schema.
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?
Clearly states the tool lists registries configured in Portainer and enumerates the returned fields (id, name, URL, type). This distinguishes it from other list tools for different resources.
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?
Explicitly explains how to use the output: use the id as registry_id in portainer_image_pull or portainer_service_update so Portainer supplies stored credentials. This gives concrete downstream guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It clearly indicates a non-mutating list operation and mentions server-side filtering, but it does not explicitly state that no state changes occur; the verb 'list' strongly implies read-only behavior.
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 compact and well-structured: a one-sentence purpose, a relevant Swarm caveat, and a brief parameter list. There is no redundant or extraneous content.
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?
Given that a full output schema exists, the description does not need to detail return fields. It provides enough context for an agent to choose the tool, select an endpoint, apply filters, and understand when to prefer an alternative tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are described in prose despite the schema having no per-parameter descriptions. endpoint_id's default behavior, show_all's effect, name_filter's substring matching, and stack_filter's exact-match semantics are all clearly explained.
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 clearly states the operation is to list containers on an endpoint and that the result includes stack and service information. It also distinguishes this tool from container-level actions and from service/stack listing tools by name and intent.
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?
The description explicitly advises preferring portainer_services_list or stack_status on Swarm endpoints, with a rationale that containers are transient task instances there. It also gives practical filter guidance for including stopped containers, filtering by name substring, and filtering by stack.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It goes beyond the basic 'pull' action by explaining credential handling (Portainer supplies credentials, no password passes through the model), the semantics of registry_id=0 (anonymous), the mutual exclusivity of registry_id and registry_auth, and the exact format of registry_auth (base64 JSON forwarded as X-Registry-Auth). This is rich, actionable behavioral context that prevents misuse.
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 well-structured: a lead paragraph covering the core purpose and credential flow, followed by a clean Args list. Each sentence adds value – no filler. The critical security note ('No password ever passes through the model') is front-loaded. Despite its length, it remains focused and easy to scan.
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?
Given the tool's complexity (5 parameters, auth logic, registry resolution) and an output schema existing, the description covers everything needed: how to select a registry, how to pass explicit auth, what defaults exist, and security constraints. There are no apparent gaps that would prevent an agent from calling this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It does: the 'Args' section explains every parameter – image_name, tag (with default), registry_id (auto-detected, 0=anonymous), registry_auth (base64 JSON, mutual exclusivity), and endpoint_id (default behavior). This adds significant meaning beyond the bare schema, which only lists names and types.
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 clearly states 'Pull a Docker image from a registry' – a specific verb and resource that distinguishes it from sibling tools like portainer_image_inspect, portainer_image_remove, or portainer_images_list. The scope (registry interaction) is unambiguous, so an agent can immediately tell what this tool does.
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?
The description provides strong guidance on how to use the tool correctly: it explains automatic registry detection, when to use registry_id vs registry_auth, and when anonymous pull is appropriate. It stops short of explicitly naming alternative tools for other image operations (e.g., 'use portainer_images_list to list images'), but the operational context is clear enough for an agent to decide when pulling is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavior. It explains that env variables are preserved and merged, that prune defaults to the current setting, that detach_from_git converts to file-based stacks, and that compose_content must not contain [REDACTED]. These are crucial operational details beyond what the schema provides.
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 information-dense yet well-structured: the core purpose is stated first, followed by critical behavioral notes, then a bullet-like list of args. Every sentence adds value, and the content is front-loaded with the most important context about env preservation and pull_image.
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?
Given the tool's complexity (8 parameters, including env merge logic and git detachment), the description covers all necessary operational details. An output schema exists, so return values need no explanation. Edge cases such as :latest image updates and git-backed stacks are addressed, making the description complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain every parameter. It does so comprehensively: each argument has a dedicated line with purpose, examples, and conditions (e.g., env example, prune Swarm-only, detach_from_git requirement, endpoint_id auto-derived). This far exceeds minimal parameter documentation.
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 opens with 'Update (redeploy) an existing stack,' which clearly identifies the verb (update/redeploy), the resource (existing stack), and differentiates from sibling tools like portainer_stack_deploy (which creates new stacks). It is specific and unambiguous.
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?
The description provides clear usage context, such as when to pass pull_image for :latest images and when detach_from_git is required. It also explains that omitting all optional arguments performs a plain redeploy. However, it does not explicitly contrast with portainer_stack_deploy or other stack operations, so it misses an explicit 'use this instead of X' statement, though the purpose statement implies it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden and does so excellently. It discloses the exact output contents, the fallback to container states on Compose, cron-driven behavior, and the failure-reporting logic (only failures newer than the last good task). This is thorough behavioral transparency beyond basic read-only hints.
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 well-structured: a crisp opening summary, followed by usage guidance, behavioral details, and a clean Args block. Every sentence earns its place, and the key purpose is front-loaded. It is concise yet information-dense without redundancy.
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?
The description covers purpose, usage context, environment-specific behavior, and parameter semantics. Given an output schema exists (as indicated), the description does not need to explain return values. It is complete for an agent to correctly select and invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description's Args section fully explains both parameters: stack_name as 'Stack name (Swarm namespace / Compose project)' and endpoint_id as 'Target endpoint ID (uses default if omitted)'. This adds significant meaning beyond the raw schema, making the parameters self-explanatory.
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 clearly states the tool's purpose: 'Health summary of a stack' with specific details about replicas, update state, and task failures. It also differentiates itself from siblings by saying 'Start here when asked is stack X ok / why is X down', distinguishing it from inspect, logs, and other stack tools.
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?
The description provides explicit when-to-use guidance: 'Start here when asked is stack X ok / why is X down'. It also explains behavior across Swarm and Compose environments, giving the agent clear context for invocation. While it doesn't name alternative tools, the directive is strong and unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

portainer-mcp MCP server – quality and maintenance score on Glama

Copy to your README.md:

[![portainer-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/ginkida/portainer-mcp/badges/card.svg)](https://glama.ai/mcp/servers/ginkida/portainer-mcp)

Score Badge

Copy to your README.md:

[![portainer-mcp MCP server – quality and maintenance score on Glama](https://glama.ai/mcp/servers/ginkida/portainer-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ginkida/portainer-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ginkida/portainer-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server