Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Uyuni MCP Server List all systems with pending security updates"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
The Uyuni MCP Server is a Model Context Protocol (MCP) server implementation that bridges the gap between Large Language Models (LLMs) and the Uyuni configuration and infrastructure management solution.
This project allows AI agents or MCP-compliant clients (such as Gemini CLI or Claude Desktop) to securely interact with your Uyuni server. The Uyuni MCP server enables users to manage their Linux infrastructure using natural language. Instead of navigating the web UI or writing complex API scripts, you can simply ask your AI assistant to perform tasks like getting system details, checking for updates, or scheduling maintenance.
Key Capabilities This server exposes a suite of tools that allow LLMs to:
Inspect Infrastructure: Retrieve lists of active systems and view system information.
Manage Updates: Identify systems with pending security updates or CVEs and schedule patch applications.
Execute Actions: Schedule patches, system updates and reboots.
It is designed to be run as a container remotely (HTTP) or locally (stdio), offering a streamlined way to integrate AI-driven automation into your system administration workflows.
Related MCP server: PlugLayer MCP Server
list_systems: Fetches a list of active systems from the Uyuni server, returning their names and IDs.
get_system_details: Gets details of the specified system.
get_system_event_history: Gets the event/action history of the specified system.
get_system_event_details: Gets the details of the event associated with the especified server and event ID.
find_systems_by_name: Lists systems that match the provided hostname.
find_systems_by_ip: Lists systems that match the provided IP address.
get_system_updates: Checks if a specific system has pending updates (relevant errata).
summarize_system_updates: Returns low-token summary counts for pending updates of a specific system (optional advisory_types filter).
query_system_updates: Returns paginated pending updates for a specific system with optional CVE expansion and optional advisory_types filter.
check_all_systems_for_updates: Checks all active systems for pending updates.
summarize_fleet_updates: Returns low-token paginated summary of systems with pending updates.
list_systems_needing_update_for_cve: Finds systems requiring a security update for a specific CVE identifier.
list_systems_needing_reboot: Fetches a list of systems from the Uyuni server that require a reboot.
get_unscheduled_errata: Lists applicable and unscheduled patches for a system.
list_activation_keys: Retrieves a list of available activation keys for bootstrapping new systems.
list_all_scheduled_actions: Fetches a list of all scheduled, in-progress, completed, or failed actions.
list_system_groups: Fetches a list of system groups from the Uyuni server.
list_group_systems: Lists the systems in a system group.
schedule_pending_updates_to_system: Checks for pending updates on a system, schedules all of them to be applied.
schedule_specific_update: Schedules a specific update (erratum) to be applied to a system.
add_system: Bootstraps and registers a new system with Uyuni using an activation key.
remove_system: Decommissions and removes a system from Uyuni management.
schedule_system_reboot: Schedules a reboot for a specified system.
cancel_action: Cancels a previously scheduled action, such as an update or reboot.
create_system_group: Creates a new system group in Uyuni.
add_systems_to_group: Adds systems to a system group.
remove_systems_from_group: Removes systems from a system group.
To use the Uyuni MCP Server, follow these two main steps:
Configuring the Server: Set up the connection details for your Uyuni instance.
Running the Server: Choose one of the provided methods to launch the server (e.g., as a container or a local script) and configure your MCP client how to connect to and interact with the server.
Create a file (e.g., uyuni-config.env) to store your environment variables. You can place this file anywhere, but you must reference its path when running the server.
# Required fields
#
# Basic API parameters
UYUNI_SERVER=https://192.168.1.124:8443
# Optional fields
#
# Uyuni credentials for local deployments (not required for OAuth setups)
UYUNI_USER=mcp-user
UYUNI_PASS=password
#
# Set to 'false' to disable SSL certificate verification. Defaults to 'true'.
UYUNI_MCP_SSL_VERIFY=true
# Set to 'true' to enable tools that perform write actions (e.g., POST requests). Defaults to 'false'.
UYUNI_MCP_WRITE_TOOLS_ENABLED=false
# Set the transport protocol. Can be 'stdio' (default) or 'http'.
UYUNI_MCP_TRANSPORT=stdio
# Host and Port to bind when using HTTP transport
UYUNI_MCP_HOST=127.0.0.1
UYUNI_MCP_PORT=8080
# Final public URL to advertise
UYUNI_MCP_PUBLIC_URL=http://127.0.0.1:8080
# OAuth 2.0 authorization server
UYUNI_AUTH_SERVER=https://auth.example.com
# Set the path for the server log file. Defaults to logging to the console.
UYUNI_MCP_LOG_FILE_PATH=/var/log/mcp-server-uyuni.log
# Set the logging level. Can be 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'. Defaults to 'INFO'.
UYUNI_MCP_LOG_LEVEL=DEBUG
# Required to bootstrap new systems into Uyuni via the `add_system` tool.
UYUNI_SSH_PRIV_KEY="-----BEGIN OPENSSH PRIVATE KEY-----\n..."
UYUNI_SSH_PRIV_KEY_PASS=""Security Note on Write Tools: Enabling UYUNI_MCP_WRITE_TOOLS_ENABLED allows the execution of state-changing and potentially destructive actions (e.g., removing systems, applying updates). When combined with UYUNI_MCP_TRANSPORT=http, this risk is amplified, as any client with network access can perform these actions. Only enable write tools in a trusted environment.
Security Note on HTTP Transport: When UYUNI_MCP_TRANSPORT is set to http but UYUNI_AUTH_SERVER is not set, the server runs without authentication. This means any client with network access can execute commands. Only use this mode in a trusted, isolated network environment. For more details, see the Security Policy.
OAuth with Uyuni requires Uyuni support forPOST /manager/api/oidcLogin. Configure Uyuni OIDC support as described below. For implementation details, see https://github.com/uyuni-project/uyuni/pull/11084.
Formatting the SSH Private Key
The UYUNI_SSH_PRIV_KEY variable, used by the add_system tool, requires the entire private key as a single-line string. The newlines from the original key file must be replaced by the literal \n sequence.
You can generate the correct format from your key file (e.g., ~/.ssh/id_rsa) using the following command. You can then copy the output into your config file or environment variable.
awk 'NF {printf "%s\\n", $0}' ~/.ssh/id_rsaTo set it as an environment variable directly in your shell, run:
export UYUNI_SSH_PRIV_KEY=$(awk 'NF {printf "%s\\n", $0}' ~/.ssh/id_rsa)Alternatively, you can also set environment variables instead of using a file.
Choose one of the following methods to run the server.
With this method, the MCP client handles the lifecycle of the container. This is the easiest method for deployment, as it isolates the environment and requires no local dependencies other than a container engine (e.g., Docker).
Pre-built container images are available on the GitHub Container Registry. Refer to your MCP client's documentation for specific configuration syntax.
Client Configuration Examples:
Using an environment file:
Replace /path/to/uyuni-config.env with the absolute path to your configuration file. Replace VERSION with the desired release tag (e.g., v0.2.1) or use latest.
{
"mcpServers": {
"mcp-server-uyuni": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"--env-file", "/path/to/uyuni-config.env",
"ghcr.io/uyuni-project/mcp-server-uyuni:VERSION"
]
}
}
}Using environment variables:
{
"mcpServers": {
"mcp-server-uyuni": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "UYUNI_SERVER=https://192.168.1.124:8443",
"-e", "UYUNI_USER=admin",
"-e", "UYUNI_PASS=admin",
"ghcr.io/uyuni-project/mcp-server-uyuni:VERSION"
]
}
}
}This method is ideal for multi-user environments where you need a persistent, network-accessible server with OAuth 2.0 support.
First, ensure the following environment variables are set in your configuration:
UYUNI_MCP_TRANSPORT=http
UYUNI_MCP_HOST=0.0.0.0 # Or a specific interface
UYUNI_MCP_PORT=8080
UYUNI_MCP_PUBLIC_URL=https://mcp.example.com # Client-facing MCP base URL used for OAuth discovery
UYUNI_AUTH_SERVER=https://auth.example.comUYUNI_MCP_HOST controls where the server binds. UYUNI_MCP_PUBLIC_URL controls the URL advertised to OAuth-capable clients. Do not set the public URL to 0.0.0.0.
Then, run the container:
docker run --env-file /path/to/uyuni-config.env -p 8080:8080 ghcr.io/uyuni-project/mcp-server-uyuni:latestYour MCP client can then connect to the server using its URL.
Client Configuration Example:
{
"mcpServers": {
"mcp-server-uyuni": {
"url": "http://127.0.0.1:8080/mcp",
"type": "http"
}
}
}The server runs on plain HTTP. For production environments, it is strongly recommended to use a reverse proxy (e.g., Nginx, Apache) to provide HTTPS encryption (TLS), handle certificates, and enhance security.
UnsettingUYUNI_AUTH_SERVER in HTTP mode bypasses OAuth, enabling any client on the network to access the server. This is only intended for trusted development environments.
uv (for development)If you are developing or prefer running Python directly, you can use uv.
Prerequisites:
Install uv: https://docs.astral.sh/uv
Clone this repository
Sync dependencies from the root of the repository by running uv sync
Setup and Run:
To use the server in client-managed stdio mode, use the following configuration example:
{
"mcpServers": {
"mcp-server-uyuni": {
"command": "uv",
"args": [
"run",
"--env-file", "/path/to/uyuni-config.env",
"--directory", "/path/to/your/mcp-server-uyuni",
"mcp-server-uyuni"
]
}
}
}To run the server in standalone HTTP mode, use the following command:
uv run --env-file /path/to/uyuni-config.env --directory /path/to/your/mcp-server-uyuni mcp-server-uyuniWhen running the server in HTTP mode (UYUNI_MCP_TRANSPORT=http), it is strongly recommended to secure it with an authentication layer. The server includes support for OAuth 2.0 to authenticate client requests. To enable it, set the UYUNI_AUTH_SERVER environment variable to your identity provider's URL.
Uyuni must be configured to trust the same identity provider as the MCP server. When UYUNI_AUTH_SERVER is set, the MCP server forwards the user's bearer token to Uyuni at POST /manager/api/oidcLogin.
Configure Uyuni in rhn.conf:
web.oidc.enabled = true
web.oidc.idp.issuer = https://auth.example.comIf you want to set the JWKS endpoint explicitly, add:
web.oidc.idp.jwks_path = /realms/your-realm/protocol/openid-connect/certsIf web.oidc.idp.jwks_path is left unset, Uyuni resolves it from the issuer's /.well-known/openid-configuration document.
Uyuni also validates the expected audience and the username claim. The defaults introduced by Uyuni are:
web.oidc.jwt.audience = uyuni-server
web.oidc.jwt.username_claim = preferred_usernameNotes:
web.oidc.idp.issuer must match the token iss claim exactly.
The forwarded token must include a sub claim.
web.oidc.jwt.username_claim must point to a claim whose value matches an existing active Uyuni username.
The forwarded token must include both audiences required by this integration: mcp-server-uyuni for the MCP server and uyuni-server for Uyuni.
If you change web.oidc.jwt.audience in Uyuni, your identity provider must issue the matching audience value.
After updating rhn.conf, restart the relevant Uyuni services according to your deployment procedure, then verify that:
the token issuer matches web.oidc.idp.issuer
the token audience includes uyuni-server
the token contains preferred_username or your configured username claim
the username from that claim already exists in Uyuni
Follow these practices to harden your deployment.
The Uyuni user configured via UYUNI_USER should have the minimum set of permissions required to perform its tasks. Avoid using highly privileged accounts like admin. See "Role-Based Access Control" in Uyuni documentation to fine-tune permissions.
Enabling state-changing tools with UYUNI_MCP_WRITE_TOOLS_ENABLED=true poses a significant risk. Only enable this in trusted environments and when all other security measures, such as authentication and HTTPS, are in place.
Avoid hardcoding secrets like passwords (UYUNI_PASS) or SSH keys (UYUNI_SSH_PRIV_KEY) in your configuration files, especially if they are checked into version control. Use a secrets management system (e.g., HashiCorp Vault, cloud provider secret stores) or inject them as environment variables at runtime. Ensure configuration files containing secrets (like uyuni-config.env) are not committed to Git.
For production environments, configure structured logging to a file for monitoring and auditing:
Set UYUNI_MCP_LOG_FILE_PATH to a secure location (e.g., /var/log/mcp-server-uyuni.log).
Set UYUNI_MCP_LOG_LEVEL to INFO or WARNING.
Regularly review logs for unusual or unauthorized activity.
We would love to hear from you! Any idea you want to discuss or share, please do so at https://github.com/uyuni-project/uyuni/discussions/10562
If you encounter any bug, be so kind to open a new bug report at https://github.com/uyuni-project/mcp-server-uyuni/issues/new?type=bug
Thanks in advance from the Uyuni team!
This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.
This is an open-source project provided "AS IS" without any warranty, express or implied. Use at your own risk. For full details, please refer to the License section.
Check all active systems for pending updates.
Inputs: optional include_updates, include_cves, system_limit, system_offset, updates_per_system.
Best for fleet scan; set include_updates=true to include per-system update items.
system_limit is capped at 200 for response paging.
Returns: items with systems that have pending updates (plus optional update details) and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| include_updates | No | ||
| include_cves | No | ||
| system_limit | No | ||
| system_offset | No | ||
| updates_per_system | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behavioral traits: the system_limit is capped at 200 for paging, and the return structure includes items and meta. It does not cover rate limits or auth needs, but the information given is sufficient for basic understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with three sentences that front-load the purpose and then add usage and behavioral details. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists (though not shown) and the description mentions the return format, the key behaviors are covered. The five optional parameters have defaults, and the sibling tools are diverse, but the description sufficiently orients the agent for basic invocation. Minor gaps in parameter semantics prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 lists all five parameters and gives partial semantics: include_updates adds per-system items, system_limit is capped. However, it does not explain include_cves, system_offset, or updates_per_system in detail, leaving some meaning implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool checks all active systems for pending updates, using the verb 'check' and resource 'all active systems'. It further clarifies it's best for fleet scan, distinguishing it from sibling tools that target individual systems or summaries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when to use the tool ('best for fleet scan') and how to configure it ('set include_updates=true'), but does not explicitly exclude scenarios or mention alternative tools. This gives clear usage guidance without exhaustive exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find systems by IP address.
Inputs: ip_address; optional limit, offset.
limit is capped at 500.
Returns: items with matching systems (system_name, system_id, ip) and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| ip_address | Yes | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must reveal behavioral traits. It notes that 'limit is capped at 500', which is a constraint, and describes the return format. However, it omits authentication requirements, rate limits, or side effects. Adequate but incomplete for a read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise: one sentence for purpose, one listing inputs and constraints, one for returns. No unnecessary words, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 params, output schema exists), the description covers the main aspects: purpose, inputs, a constraint (limit cap), and return structure. Could mention pagination or error handling, but overall complete enough for use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 lists parameters (ip_address, limit, offset) and explains the limit cap, adding meaning beyond the schema. However, it does not explain the format of ip_address or the behavior of offset, leaving gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool's purpose: find systems by IP address. It uses a specific verb 'Find' and resource 'systems by IP', distinguishing it from siblings like 'find_systems_by_name' and 'list_systems'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies usage for IP-based search and mentions optional parameters (limit, offset) for pagination, but lacks explicit guidance on when to use this tool versus alternatives like 'find_systems_by_name' or 'list_systems'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find systems by hostname.
Inputs: name; optional limit, offset.
Use this first when user input is a partial hostname.
If multiple systems match, ask the user to choose one system_id.
limit is capped at 500.
Returns: items with matching systems (system_name, system_id) and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses the limit cap of 500, the return structure (items with system_name and system_id, plus meta), and implies a read-only nature by searching. It doesn't explicitly state it's non-destructive, but the context suggests it. Overall adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at four sentences. It front-loads the core purpose, enumerates inputs clearly, and includes behavioral constraints and output format without any filler. Every sentence contributes meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, no annotations, and an output schema (as per context signals), the description covers all needed aspects: purpose, usage guidance, parameter semantics, behavioral constraints (limit cap), output structure, and workflow hint. It is complete for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 must add meaning. It identifies 'name' as hostname, clarifies that 'limit' and 'offset' are optional, and adds that 'limit' is capped at 500. This provides essential semantic context beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool finds systems by hostname, using partial hostname input. It distinguishes itself from sibling tools like 'find_systems_by_ip' by specifying hostname search, and it's positioned as the first step when user input is a partial hostname.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use this first when user input is a partial hostname', providing clear when-to-use guidance. It also advises that if multiple systems match, the agent should ask the user to choose a system_id, offering a concrete workflow step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get details for one system.
Inputs: system_identifier (system_name or system_id).
Name not found: resolve with find_systems_by_name, then pass system_id.
Returns: system_id, system_name, last_boot, uuid, cpu, network, installed_products.
Use system_id when possible.
| Name | Required | Description | Default |
|---|---|---|---|
| system_identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It describes inputs (name or ID), recommends ID, and lists output fields. Lacks disclosure of error conditions or permission requirements, but for a read-only tool 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, each serving a purpose: purpose, input format, fallback behavior, output. Front-loaded with purpose. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, description covers all needed: purpose, input options, fallback, output fields, and best practice. Complete and actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one parameter with anyOf string/integer but no description. Description clarifies it can be system_name or system_id, emphasizes preference for system_id, and explains fallback. Adds substantial meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description explicitly states 'Get details for one system' (clear verb+resource). It distinguishes from siblings like list_systems (lists many) and find_systems_by_name (resolves names). Specifies return fields, reinforcing purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: use system_id when possible, and if name not found, resolve with find_systems_by_name then pass system_id. This clearly advises when to use 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.
Get one event detail.
Inputs: system_identifier (system_name or system_id), event_id.
Name not found: resolve with find_systems_by_name, then pass system_id.
Returns: event object including status, timestamps, result fields, and optional additional_info.
event_id should come from get_system_event_history.
| Name | Required | Description | Default |
|---|---|---|---|
| system_identifier | Yes | ||
| event_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry the burden. It describes a read operation (getting event details) and mentions the return object fields. It does not explicitly state it is read-only, but it implies no side effects. Minor improvement would be to state it does not modify data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with four lines of essential info. Each sentence adds value: purpose, inputs, error resolution, return fields, source of event_id. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description still describes the return object (status, timestamps, result fields, additional_info). It also explains how to handle unresolved system identifiers. For a simple read tool, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It explains system_identifier can be system_name or system_id, and event_id should come from get_system_event_history. This adds significant semantic value beyond the schema's raw types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets one event detail, with specific inputs and a note that event_id should come from get_system_event_history. This differentiates it from siblings like get_system_event_history, which lists events, and get_system_details, which gets system details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides guidance: use event_id from get_system_event_history, and if system name is not found, resolve with find_systems_by_name. This tells the agent when to use other tools, fulfilling the usage guidelines dimension well.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List events for one system.
Inputs: system_identifier (system_name or system_id); optional offset, limit, earliest_date.
Name not found: resolve with find_systems_by_name, then pass system_id.
Returns: newest-first event list with id, history_type, status, summary, completed.
Use get_system_event_details for one event.
| Name | Required | Description | Default |
|---|---|---|---|
| system_identifier | Yes | ||
| offset | No | ||
| limit | No | ||
| earliest_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the tool returns a newest-first event list with specific fields (id, history_type, status, summary, completed). It mentions the input parameters and their defaults, but does not describe edge cases like system not existing (though it does handle name not found via resolution). Overall, it gives sufficient behavioral insight for a read-only listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet informative, using five sentences to convey purpose, inputs, error handling, return format, and alternative tool. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately specifies the return format (newest-first list with five fields). It covers pagination parameters, error resolution, and sibling tool alternatives. For a list tool with 4 parameters, it is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 explains that system_identifier can be system_name or system_id, and that offset, limit, and earliest_date are optional. It also provides guidance on resolving name not found. However, it does not specify the format for earliest_date, which could be ambiguous. Still, it adds significant meaning beyond the sparse schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List events for one system,' specifying the action and resource. It distinguishes itself from sibling tools like get_system_event_details, which is for a single event, and other system listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it lists events for one system, and advises using get_system_event_details for individual events. It also includes error handling steps: if the system identifier is a name not found, resolve with find_systems_by_name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get pending updates for one system.
Inputs: system_identifier (system_name or system_id; prefer system_id).
Name not found: resolve with find_systems_by_name, then pass system_id.
Best for compact default update view.
Returns: compact update list plus counts and meta.
Default behavior omits CVEs for lower token usage.
For pagination and CVE expansion, use query_system_updates.
| Name | Required | Description | Default |
|---|---|---|---|
| system_identifier | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It reveals that by default CVEs are omitted for lower token usage, that it returns a compact update list with counts and meta, and that `system_identifier` can be name or ID. Could mention if any side effects or permissions needed, but as a read operation this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Multiple sentences but each provides useful information. Front-loaded with purpose. Could trim phrasing, but no redundancy. Efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter and existence of output schema (though not shown), the description covers what the tool returns, default behavior, alternatives, and input handling. No gaps 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 1 parameter with 0% coverage. Description adds meaning by clarifying that `system_identifier` accepts either system name or system ID, with preference for ID, and explains the fallback. This compensates well for the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get pending updates for one system' (verb + resource). It distinguishes from sibling `query_system_updates` by noting this is for a compact default view, while the sibling handles pagination and CVE expansion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use this tool ('Best for compact default update view') and when to use alternatives ('For pagination and CVE expansion, use query_system_updates'). Also provides resolution path for name not found via `find_systems_by_name`, and recommends preferring `system_id` over `system_name`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List unscheduled errata for one system.
Inputs: system_id.
This tool accepts numeric system_id only.
Returns: errata list for that system.
| Name | Required | Description | Default |
|---|---|---|---|
| system_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description states that it returns an errata list but does not disclose behavioral aspects such as read-only nature, error handling, pagination, or side effects. The constraint on system_id is noted but insufficient for full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three short sentences covering purpose, input, and output. No extraneous words and information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 required parameter, with output schema), the description covers the essential information: input requirement and return type. It does not mention potential limitations like pagination or default behavior, but the presence of an output schema mitigates the need for detailed return documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one integer parameter (system_id) with 0% description coverage. The description adds meaning by specifying 'numeric system_id only', reinforcing the type constraint. However, it does not explain the parameter's purpose beyond its name, so it adds moderate value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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 (unscheduled errata), and the scope (for one system). It distinguishes from sibling tools like get_system_updates or list_systems_needing_update_for_cve by specifying 'unscheduled errata'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a constraint (numeric system_id only) but does not explicitly guide when to use this tool versus alternatives. The input constraint is helpful but lacks context for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List activation keys available to the current user.
Inputs: none.
Returns: list of objects with key and description.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the return format (list of objects with key and description) and states no inputs. With no annotations provided, it does not mention side effects, authentication, or pagination, but for a simple read-only list, it is minimally sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short, purposeful sentences with no extraneous information. It is front-loaded with the action and resource, then details inputs and outputs efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and the presence of an output schema (as per context), the description adequately covers the return format. There are no missing details for a simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description does not need to add parameter meaning. A score of 4 is appropriate as the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and resource 'activation keys', and specifies the scope 'available to the current user'. It distinguishes from sibling tools (which deal with systems, groups, updates) by focusing on a unique resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving the user's activation keys. It does not provide explicit when-to-use or alternatives, but given the unique purpose and zero parameters, it is clear and adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query scheduled actions.
Inputs: optional limit, offset, action_types, scheduler.
action_types and scheduler are optional exact-match filters; prefer values from meta.observed_action_types and meta.observed_schedulers.
limit is capped at 500; use meta.next_offset to page.
Returns: items with scheduled actions and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| action_types | No | ||
| scheduler | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description compensates well by disclosing pagination behavior, filter exact-match nature, and limit cap. It avoids contradictions and adds value beyond defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: three sentences front-loading the core action, then detailing parameters and behavior with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers essential aspects (pagination, filters, defaults) for a list operation. Output schema is present, so return values are implicit. Minor gap: no mention of error conditions or rate limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description adds meaning to all parameters: explains usage of limit, offset, exact-match filters for action_types and scheduler, and suggests values from meta fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries scheduled actions, effectively communicating the verb-resource relationship. It distinguishes itself from sibling tools that focus on systems and updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on optional filters and pagination (limit capped at 500, use meta.next_offset). However, it does not explicitly state when not to use this tool or compare to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List systems in one group.
Inputs: group_name.
Returns: list of system_id and system_name.
| Name | Required | Description | Default |
|---|---|---|---|
| group_name | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that it returns a list of system_id and system_name, indicating a read-only operation. However, it lacks details on pagination, error handling (e.g., if the group does not exist), or whether the list is exhaustive. No annotations provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, front-loading the purpose and immediately covering inputs and outputs. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, list operation), the description covers the essential elements. However, it could mention that the group must exist or provide examples, and it does not explain the output schema beyond field names. Sibling tools add context but are not referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions the parameter 'group_name' but adds no semantic details beyond its name. The input schema has 0% description coverage, so the description should compensate with format or constraints. It does not specify whether it expects a display name or an ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists systems in one group, specifies the input parameter, and describes the output. It distinguishes from sibling tools like list_systems (all systems) and other specific queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing systems in a single group, but does not explicitly state when to use this tool over alternatives (e.g., use list_systems for cross-group listings). No guidance on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List system groups.
Inputs: none.
Returns: list with id, name, description, and system_count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description states inputs and outputs explicitly, which is moderately transparent for a simple read operation. However, it does not mention permissions or other behavioral constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise: two sentences conveying purpose and return structure. Front-loaded with the action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0 parameters and an output schema, the description covers the essential elements. It adds return field details beyond the schema, which is helpful. Could mention ordering or limits, but not critical for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters in schema; description confirms 'Inputs: none.' Schema coverage is 100% trivially. Description adds no additional parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List system groups,' with a specific verb and resource. It distinguishes from siblings like list_group_systems (which lists systems in a group) and other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives. No prerequisites, when-not-to-use, or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List active systems in Uyuni.
Inputs: optional `limit`, `offset`.
`limit` is capped at 500.
Returns: `items` with active systems (`system_name`, `system_id`) and `meta`.
Note: use `system_id` for other system tools.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist; the description discloses that the tool lists 'active' systems, provides return fields, and caps limit at 500. However, it does not explain what 'active' means, pagination behavior beyond limit/offset, or permissions required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with three sentences that front-load the core purpose, then provide parameter and return structure details without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple list operation with an output schema, the description covers input constraints, return fields, and a practical usage hint. It lacks only minor details like error handling or filtering capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds value by noting limit is capped at 500 and inputs are optional. However, it does not explain offset semantics or expected data types beyond the schema defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List active systems in Uyuni,' specifying verb and resource. It distinguishes from sibling tools by focusing on a general listing, and provides a practical hint about using system_id for other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions optional inputs and a limit cap, but does not explicitly clarify when to use this tool versus alternatives like find_systems_by_name or check_all_systems_for_updates. The note about system_id offers some integration guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List systems that require reboot.
Inputs: optional limit, offset.
limit is capped at 500.
Returns: items with systems requiring reboot (system_id, system_name, reboot_status) and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 output format ('items' with specific fields) and pagination constraints (limit capped at 500). It does not explicitly state read-only behavior, but for a list tool 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: three sentences with no filler. It front-loads the primary purpose and adds necessary details without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list with pagination) and the presence of an output schema (context signal), the description covers the key aspects: what it returns, pagination behavior, and cap. It is adequate for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for parameters (0% coverage), but the description adds that `limit` is capped at 500, which goes beyond the schema. It also explains that `limit` and `offset` are inputs for pagination, partially 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists systems requiring reboot. It uses a specific verb ('list') and resource ('systems that require reboot'), distinguishing it from siblings like 'list_systems' (all systems) and 'check_all_systems_for_updates'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to see systems needing reboot) but does not explicitly state when to use it over alternatives or when not to use it. No exclusions or alternative guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List systems affected by a CVE.
Inputs: cve_identifier; optional limit, offset.
limit is capped at 500.
Returns: items with unique affected systems (system_id, system_name) and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| cve_identifier | Yes | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavioral traits such as limit capped at 500 and that returned items are unique. However, lacks information on side effects, permissions, or rate limits. No annotations provided to complement or contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, no wasted words. Front-loaded with main purpose, followed by parameter summary and return format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 (indicated by context signals), the description sufficiently explains inputs and return structure. For a filtered list tool with pagination, it covers essential aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, so description adds value by explaining the purpose of each parameter (cve_identifier required, limit and offset optional with defaults and cap). Adds context beyond raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists systems affected by a CVE, with specific inputs and outputs. It is distinguishable from siblings like list_systems (list all systems) and list_systems_needing_reboot.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. For example, it doesn't mention when to use list_systems_needing_update_for_cve vs check_all_systems_for_updates or other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query pending updates for one system.
Inputs: system_identifier (system_name or system_id); optional limit, offset, include_cves, advisory_types.
Name not found: resolve with find_systems_by_name, then pass system_id.
Best for pagination and optional CVE expansion.
Pagination behavior: limit <= 0 returns no items (counts still available);
positive limit is capped at 200.
Returns: updates with pending updates for the system and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| system_identifier | Yes | ||
| limit | No | ||
| offset | No | ||
| include_cves | No | ||
| advisory_types | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully bears the burden of behavioral disclosure. It details pagination behavior (limit <=0 returns no items, positive limit capped at 200), input resolution via another tool, and return structure (updates and meta).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative and reasonably concise, around 100 words. It starts with the core purpose and flows logically into inputs, then a usage note, then pagination behavior. Could benefit from slight restructuring for easier scanning (e.g., bullet points), but overall effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and an output schema, the description covers inputs, pagination behavior, and return structure. It mentions the output schema indirectly. It does not cover error cases or edge cases beyond pagination, but the output schema likely covers the return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 must compensate. It explains each parameter: system_identifier (name or id), limit, offset, include_cves, advisory_types. It also explains the effect of limit and offset, providing meaning well beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries pending updates for one system. It uses a specific verb ('Query') and resource ('pending updates'), and the context distinguishes it from sibling tools like check_all_systems_for_updates (which handles all systems).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on when to use this tool, including resolving system names via find_systems_by_name and noting it is best for pagination and optional CVE expansion. However, it does not explicitly contrast with every sibling (e.g., get_system_updates), so it is clear but not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize fleet update status.
Inputs: optional system_limit, system_offset.
system_limit is capped at 200.
Returns: paged list of systems with update counts in items and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| system_limit | No | ||
| system_offset | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses pagination with 'system_limit' capped at 200 and a paged list response, but no annotations are present. It does not cover safety, authentication, or side effects, so the burden falls on the description, which is partially met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the purpose and efficiently add input/output specifics without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 optional parameters and an output schema, the description covers inputs, pagination, and output structure ('items' and 'meta'). It lacks sibling differentiation but is otherwise adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining 'system_limit' and 'system_offset' as optional controls for pagination, including the limit cap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Summarize fleet update status,' clearly defining the tool's purpose. However, it does not explicitly differentiate from the sibling 'summarize_system_updates,' which likely focuses on individual systems.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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 like 'summarize_system_updates' or other fleet analysis tools. The description lacks any context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize pending updates for one system.
Inputs: system_identifier (system_name or system_id); optional advisory_types.
Name not found: resolve with find_systems_by_name, then pass system_id.
Best for counts only.
advisory_types accepts: Security Advisory, Product Enhancement Advisory, Bug Fix Advisory.
Returns: update counts and meta.
| Name | Required | Description | Default |
|---|---|---|---|
| system_identifier | Yes | ||
| advisory_types | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses return type ('update counts and meta') and accepted advisory types, but doesn't mention permissions or side effects. Adequate but could be more transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with 5 sentences, front-loaded purpose. Minor redundancy ('Inputs:' prefix) but overall efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters and existence of output schema, description covers inputs, resolution, and output type. Sufficient for selection and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet description adds significant meaning: explains 'system_identifier' can be name or id and suggests resolution method, lists valid advisory_types values, and marks it optional. Adds value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Summarize pending updates for one system', using a specific verb and resource. It distinguishes from sibling tools like 'summarize_fleet_updates' by specifying 'one system'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises 'Best for counts only' and provides a resolution step using 'find_systems_by_name', guiding when to use and how to prep inputs. Lacks explicit when-not-to-use but clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tools have overlapping purposes, especially around updates (multiple tools for checking updates on individual systems and fleet), but descriptions clearly differentiate them by context (compact vs paginated, fleet vs individual). Some ambiguity remains for agents unfamiliar with the specific use cases.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., find_systems_by_name, get_system_details, list_systems, summarize_fleet_updates). No deviations or mixed conventions.
18 tools is well-scoped for the domain of system management (systems, groups, updates, events, actions, activation keys). Each tool serves a clear purpose without unnecessary duplication.
The tool set covers reading and querying (systems, updates, events, groups, activation keys) comprehensively, but lacks tools for performing actions (e.g., applying updates, rebooting, modifying groups). This may be intentional for a read-only server, but it leaves gaps for full lifecycle management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/uyuni-project/mcp-server-uyuni'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
