Enables managing Docker containers and performing security scans on images.
Allows querying clusters, managing pods and deployments, and monitoring service health across namespaces.
Provides tools for querying infrastructure metrics and checking service health and performance.
Enables infrastructure as code management, including running plans and inspecting resources.
Integrates security scanning capabilities for container images and infrastructure configurations to identify vulnerabilities.
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., "@InfraClaude check why the api-server pod is crashing and show the latest logs"
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.
Give Claude superpowers over your infrastructure — MCP Server for Kubernetes, Docker, Terraform, Prometheus, and Security tools.
InfraClaude is an MCP (Model Context Protocol) server that exposes infrastructure management tools to Claude. Through InfraClaude, Claude Code can query Kubernetes clusters, manage Docker containers, check Prometheus metrics, run Terraform plans, and perform security scans — all through natural language.
┌─────────────────────────────────────────────────────────┐
│ Claude Code / Claude Desktop │
│ │
│ User: "Check if any pods are crashlooping" │
│ │ │
│ MCP Client │
└─────────────────────────┼────────────────────────────────┘
│ MCP Protocol (stdio)
▼
┌─────────────────────────────────────────────────────────┐
│ InfraClaude MCP Server │
│ │
│ ┌───────────┐ ┌──────────┐ ┌────────────┐ │
│ │ Kubernetes │ │ Docker │ │ Prometheus │ │
│ │ 16 tools │ │ 9 tools │ │ 5 tools │ │
│ └───────────┘ └──────────┘ └────────────┘ │
│ ┌───────────┐ ┌──────────┐ ┌────────────┐ │
│ │ Terraform │ │ Security │ │ System │ │
│ │ 5 tools │ │ 3 tools │ │ 4 tools │ │
│ └───────────┘ └──────────┘ └────────────┘ │
│ │
│ Safety Layer: Command Guard → RBAC → Audit Logger │
└─────────────────────────────────────────────────────────┘
Plus: Claude Code Hooks + Custom SkillsRelated MCP server: AWS Sage
42+ infrastructure tools across Kubernetes, Docker, Prometheus, Terraform, Security, and System
Safety-first design — 4-tier risk classification (Safe → Caution → Dangerous → Blocked)
Audit logging — every operation logged for compliance
Claude Code hooks — pre/post tool-use safety checks and automation
Custom skills — K8s troubleshooting, incident response, Docker debugging, security review
MCP resources — cluster info, service health, infrastructure summary
MCP prompts — guided troubleshooting, capacity planning, security audit workflows
# Clone and build
git clone https://github.com/batu-sonmez/infraclaude.git
cd infraclaude
npm install
npm run build
# Add to Claude Code (~/.claude/claude_code_config.json)
{
"mcpServers": {
"infraclaude": {
"command": "node",
"args": ["/path/to/infraclaude/dist/index.js"],
"env": {
"KUBECONFIG": "~/.kube/config",
"PROMETHEUS_URL": "http://localhost:9090"
}
}
}
}Then in Claude Code:
"Show me all pods in production"
"Why is my pod crashing?"
"Run a security audit on the default namespace"
"What's the CPU usage of my cluster?"
"Scan the nginx:latest image for vulnerabilities"Set up a local demo environment with intentionally broken pods:
make demo-setupThen try the demo scenarios.
InfraClaude classifies every operation by risk level:
Level | Action | Example |
Safe | Always allowed |
|
Caution | Allowed with warning |
|
Dangerous | Requires confirmation |
|
Blocked | Never allowed |
|
System namespaces (kube-system, kube-public) have additional protections.
See Safety Documentation for details.
Tools Reference — all 42+ tools documented
Component | Technology |
MCP Server | TypeScript + @modelcontextprotocol/sdk |
Kubernetes | @kubernetes/client-node |
Docker | dockerode |
Prometheus | Native fetch API |
Terraform | CLI wrapper |
Security | Trivy, Gitleaks CLI |
Testing | Vitest |
CI/CD | GitHub Actions |
MIT — see LICENSE.
Show logs from Docker Compose services
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | Directory containing docker-compose.yml | |
| service | No | Specific service name | |
| tail | No | Number of lines (default: 100) |
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 'Show logs' but doesn't disclose behavioral traits like whether it streams or returns static logs, requires specific permissions, has rate limits, or affects system state. This leaves gaps for a tool that interacts with system services.
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 a single, efficient sentence with zero waste. It's front-loaded and appropriately sized for the tool's complexity, making it easy to parse quickly.
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 annotations and no output schema, the description is minimal but covers the basic purpose. For a tool with 3 parameters and system interaction, it should ideally include more on behavior or output format to be complete, but it meets a bare minimum for clarity.
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 100%, so the schema fully documents parameters. The description adds no additional meaning beyond implying logs are from services, but doesn't explain parameter interactions or defaults beyond what's in the schema. Baseline 3 is appropriate as the schema handles the heavy lifting.
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 ('Show logs') and resource ('from Docker Compose services'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'docker_container_logs' or 'system_logs', which would require more specificity about the Docker Compose context.
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. With siblings like 'docker_container_logs' and 'system_logs' available, the description lacks context on Docker Compose-specific usage, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show status of Docker Compose services
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | Directory containing docker-compose.yml |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Show status' implies a read-only operation, it doesn't specify what 'status' includes (running/stopped/restarting), whether it shows all services or filtered ones, output format, or any execution constraints. This leaves significant behavioral gaps for a tool that interacts with Docker services.
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 at just 5 words, front-loading the essential information with zero wasted text. Every word contributes directly to understanding the tool's function, making it highly efficient despite its brevity.
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 Docker operations tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what 'status' means in practical terms, what the output looks like, how it differs from related Docker tools, or any operational considerations. The context demands more detail than provided.
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 adds no parameter information beyond what's already in the schema, which has 100% coverage for the single 'directory' parameter. The baseline score of 3 reflects adequate but minimal value addition, as the schema already fully documents the parameter's purpose and type.
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 ('Show status') and resource ('Docker Compose services'), making the tool's purpose immediately understandable. However, it doesn't distinguish this from similar sibling tools like 'docker_list_containers' or 'docker_compose_logs', which reduces its differentiation value.
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 no guidance on when to use this tool versus alternatives. With multiple Docker-related sibling tools available, there's no indication of whether this is for Compose-specific status, how it differs from general container listing tools, or any prerequisites like requiring a docker-compose.yml file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch logs from a Docker container
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name | |
| tail | No | Number of lines from end (default: 100) | |
| since | No | Unix timestamp to start from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('fetch logs') but doesn't cover critical aspects like authentication requirements, rate limits, output format (e.g., stream vs. static), error handling, or whether it's a read-only operation. This is a significant gap for a tool interacting with system resources.
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 a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and avoids unnecessary elaboration, making it easy for an agent to parse quickly.
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 complexity of interacting with Docker containers and the lack of annotations and output schema, the description is insufficient. It doesn't explain what the logs contain, how they're formatted, or potential side effects (e.g., if fetching logs impacts container performance). For a tool with no structured behavioral hints, this leaves too many unknowns for reliable agent 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 100%, with clear descriptions for all parameters (id, tail, since). The description doesn't add any semantic details beyond what's in the schema, such as examples or constraints. This meets the baseline score of 3 since the schema adequately documents the parameters.
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 ('fetch logs') and resource ('from a Docker container'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'docker_compose_logs' or 'k8s_get_pod_logs', which handle similar logging functions in different contexts.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'docker_compose_logs' for Docker Compose environments or 'k8s_get_pod_logs' for Kubernetes pods, leaving the agent to infer usage context 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.
Get real-time CPU, memory, and network stats for a container
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name |
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 states the tool retrieves 'real-time' stats, implying dynamic data, but doesn't cover critical aspects like whether this is a one-time snapshot or continuous stream, permissions required, rate limits, or error conditions (e.g., if container isn't running).
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 a single, efficient sentence that front-loads the core purpose ('Get real-time CPU, memory, and network stats for a container'). There's no wasted verbiage or redundancy, making it highly scannable and direct.
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 tool with no annotations and no output schema, the description is insufficient. It lacks details on return format (e.g., JSON structure, units for metrics), behavioral traits (e.g., streaming vs. snapshot), and error handling. Given the complexity of system metrics, more context is needed for effective 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?
The input schema has 100% description coverage, with the 'id' parameter clearly documented as 'Container ID or name'. The description doesn't add any parameter details beyond this, so it meets the baseline for high schema coverage without compensating 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 tool's purpose with a specific verb ('Get') and resource ('real-time CPU, memory, and network stats for a container'), making it immediately understandable. It distinguishes from siblings like docker_inspect_container (detailed configuration) or docker_list_containers (listing containers), though it doesn't explicitly name these alternatives.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., container must be running), compare to similar tools (e.g., docker_inspect_container for static info), or specify use cases (e.g., monitoring vs. debugging).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a Docker container
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Container ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'gets' information, implying a read-only operation, but does not specify if it requires specific permissions, returns structured JSON, handles errors (e.g., invalid container ID), or has rate limits. For a tool with no annotations, this is a significant gap in 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 a single, clear sentence with zero waste—it directly states the tool's purpose without fluff. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly.
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 complexity of inspecting a Docker container (which can return extensive configuration and state data), the description is incomplete. There are no annotations, no output schema, and the description lacks details on return format, error handling, or behavioral traits. This makes it inadequate for an agent to fully understand how to use the tool effectively.
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 100% description coverage, with the parameter 'id' documented as 'Container ID or name'. The description does not add any meaning beyond this, such as examples or constraints (e.g., partial IDs are accepted). Since the schema does the heavy lifting, the baseline score of 3 is appropriate, but no extra value is provided.
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 ('Get') and resource ('detailed information about a Docker container'), making the purpose specific and understandable. It distinguishes from siblings like docker_list_containers (which lists containers) and docker_inspect_image (which inspects images). However, it could be more precise about what 'detailed information' entails, such as configuration, state, or network 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing a running container), exclusions (e.g., not for stopped containers), or comparisons to siblings like docker_container_stats (for real-time metrics) or docker_inspect_network (for network details). This lack of context makes it harder for an agent to choose appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a Docker image
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Image name or ID |
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 states this is a read operation ('Get'), implying it's non-destructive, but doesn't cover aspects like authentication needs, rate limits, error conditions, or the format/scope of the 'detailed information' returned. This leaves significant gaps for a tool with no annotation coverage.
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 a single, efficient sentence with zero waste. It's front-loaded with the core purpose and appropriately sized for a simple tool, making it easy to parse quickly.
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 lack of annotations and output schema, the description is incomplete. It doesn't explain what 'detailed information' includes, potential behavioral traits, or usage context. For a tool with no structured data beyond the input schema, more descriptive content is needed to adequately guide an agent.
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 description coverage is 100%, with the single parameter 'name' documented as 'Image name or ID'. The description doesn't add any meaning beyond this, such as examples or constraints, so it meets the baseline of 3 where the schema does the heavy lifting.
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 'Get detailed information about a Docker image' clearly states the verb ('Get') and resource ('Docker image'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'docker_inspect_container' or 'docker_list_images', which would require more specificity to earn a 5.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'docker_inspect_container' for container details or 'docker_list_images' for listing images, nor does it specify prerequisites or contexts for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed info about a Docker network including connected containers
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Network ID or name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While it indicates this is a read operation ('Get'), it doesn't mention permission requirements, rate limits, error conditions, or what format the detailed info will be returned in. The description provides basic intent but lacks important operational context.
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 a single, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized for a single-parameter tool and front-loads the essential 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?
For a read-only tool with 100% schema coverage but no annotations and no output schema, the description provides adequate basic context about what information will be returned (network details and connected containers). However, it doesn't address important operational aspects like error handling or response format that would be helpful for an AI agent.
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 100% with the single parameter 'id' well-documented as 'Network ID or name'. The description doesn't add any additional parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
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 'Get' and the resource 'detailed info about a Docker network including connected containers'. It specifically distinguishes itself from sibling tools like docker_inspect_container and docker_inspect_image by focusing on networks rather than containers or images.
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 detailed network information is needed, but doesn't explicitly state when to use this tool versus alternatives like docker_list_networks (for listing) or docker_inspect_container (for container details). No explicit exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Docker containers with their status, image, and ports
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Show all containers (default: only running) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions what information is listed but doesn't cover aspects like permissions required, rate limits, output format, pagination, or whether it's a read-only operation. For a tool with no annotations, this leaves significant gaps in understanding its behavior.
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 a single, efficient sentence that front-loads the core action and key outputs. There's no wasted verbiage, and it directly communicates the essential information without unnecessary elaboration.
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 low complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose but lacks details on behavior, usage context, and output format, which are important for an agent to invoke it correctly in a crowded toolset. It meets a bare minimum but has clear gaps.
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 100%, so the schema fully documents the single parameter ('all'). The description doesn't add any parameter-specific details beyond what's in the schema, such as default behavior implications. With high schema coverage, a baseline score of 3 is appropriate as the description doesn't compensate but also doesn't need to.
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 ('Docker containers') with specific attributes ('status, image, and ports'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'docker_compose_ps' or 'docker_container_stats', which might also list containers in different contexts.
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. With many sibling tools (e.g., 'docker_compose_ps' for Compose-managed containers, 'docker_container_stats' for performance metrics), the description lacks context about use cases, prerequisites, or exclusions, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List local Docker images with repository, tag, and size
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Show all images including intermediate |
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 what information is returned (repository, tag, size) but doesn't disclose behavioral aspects like whether this is a read-only operation, if it requires specific permissions, how results are formatted, or if there are rate limits. The description is minimal and lacks operational context.
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 a single, efficient sentence that clearly states the tool's purpose. It's front-loaded with the core functionality and includes specific output details without 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 simple read operation with one parameter fully documented in the schema, the description provides basic purpose but lacks context about behavior, output format, and usage guidelines. Without annotations or output schema, more detail would be helpful, though the simplicity of the tool keeps it from being severely inadequate.
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 100%, so the schema fully documents the single parameter 'all'. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for high schema coverage.
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') and resource ('local Docker images') with specific output fields (repository, tag, size). It distinguishes from siblings like docker_list_containers by focusing on images, but doesn't explicitly differentiate from other image-related tools like docker_inspect_image.
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 is provided. The description doesn't mention when to choose docker_list_images over docker_inspect_image or other sibling tools, nor does it specify prerequisites or context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Docker networks with driver and scope
| Name | Required | Description | Default |
|---|---|---|---|
No 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 of behavioral disclosure. While 'List' implies a read-only operation, the description doesn't address important behavioral aspects like whether authentication is required, if there are rate limits, what format the output takes, or if there are any side effects. For a tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.
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 a single, efficient sentence that communicates the essential information without any wasted words. It's appropriately sized for a simple listing tool and front-loads the core functionality. Every word earns its place in conveying what the tool does.
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 zero-parameter listing tool with no output schema, the description provides adequate but minimal information. It tells what the tool does and what information it returns, but lacks details about behavioral characteristics that would be important for an agent to use it correctly. Without annotations or output schema, the description should ideally provide more context about the return format and any constraints.
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 tool has zero parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, and it doesn't need to compensate for any schema gaps. The mention of 'driver and scope' in the output is helpful context about what information will be returned.
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') and resource ('Docker networks'), specifying the verb+resource combination. It adds useful detail about what information is included ('with driver and scope'), which helps distinguish it from a basic list. However, it doesn't explicitly differentiate from sibling tools like 'docker_list_containers' or 'docker_list_images' beyond the network focus.
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 about when to use this tool versus alternatives. The description doesn't mention when this tool is appropriate, what prerequisites might exist, or how it differs from related tools like 'docker_inspect_network' or other listing tools. The user must infer usage from the name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a node as unschedulable (cordon) — prevents new pods from being scheduled
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Node name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only covers basic behavior: it marks a node unschedulable. It doesn't disclose critical traits like whether this is a reversible operation (though implied by sibling 'uncordon'), permission requirements, rate limits, or what happens to existing pods (they continue running). For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding safety and 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It front-loads the core action ('Mark a node as unschedulable') and immediately clarifies the effect ('prevents new pods from being scheduled'), making it easy to parse quickly.
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 one parameter with full schema coverage and no output schema, the description adequately explains the tool's purpose. However, as a mutation tool with no annotations, it lacks details on behavioral traits like idempotency, error conditions, or response format, which would help an agent use it correctly. It's minimally viable but has clear gaps in safety and operational context.
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 100% with one parameter ('name' as 'Node name'), so the schema already documents it fully. The description adds no additional parameter semantics beyond what the schema provides, such as format examples or constraints. Baseline 3 is appropriate when the schema does all the work.
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 specific action ('Mark a node as unschedulable') and resource ('node'), with the parenthetical '(cordon)' providing precise Kubernetes terminology. It distinguishes from its sibling 'k8s_uncordon_node' by specifying the opposite effect, and from other k8s tools by focusing on node scheduling rather than describing, getting, or deleting resources.
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 context by stating 'prevents new pods from being scheduled,' suggesting this tool is used when you want to stop new workloads on a node (e.g., for maintenance). However, it doesn't explicitly state when to use this versus alternatives like 'k8s_delete_pod' for removing existing pods, or mention prerequisites like needing node name from 'k8s_get_nodes.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a specific pod (it will be recreated if managed by a controller)
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name | |
| namespace | No | Kubernetes namespace (default: 'default') |
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 a key behavioral trait: deletion may not be permanent if the pod is controller-managed, which is crucial for understanding the tool's effect. However, it lacks details on permissions required, error handling, or confirmation prompts, leaving some behavioral aspects unclear.
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 a single, efficient sentence that front-loads the core action ('Delete a specific pod') and adds a critical behavioral note without unnecessary words. Every part of the sentence earns its place by providing essential 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's complexity as a destructive operation with no annotations and no output schema, the description is reasonably complete. It covers the main action and a key caveat, but could be more comprehensive by including details like return values or error conditions. However, for a tool with only two parameters and high schema coverage, it provides sufficient context for basic 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 100%, with both parameters ('name' and 'namespace') well-documented in the schema. The description does not add any additional meaning or context about the parameters beyond what the schema provides, such as format examples or constraints, so it meets the baseline for high schema coverage.
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 ('Delete') and resource ('a specific pod'), making the purpose explicit. It also distinguishes this tool from sibling tools like 'k8s_describe_pod' or 'k8s_get_pods' by specifying it performs deletion rather than inspection or listing.
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 by mentioning that pods 'will be recreated if managed by a controller,' which suggests when this tool might be less effective, but it does not provide explicit guidance on when to use it versus alternatives like 'k8s_rollback_deployment' or 'k8s_scale_deployment' for managing pods indirectly. No clear exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed node info including capacity, allocatable resources, conditions, and taints
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Node name |
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 states the tool retrieves information ('Get'), implying it's a read-only operation, but doesn't disclose behavioral traits such as authentication requirements, rate limits, error handling, or output format. For a tool with no annotations, this leaves significant gaps in understanding how it behaves beyond basic purpose.
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 a single, efficient sentence that front-loads the core action ('Get detailed node info') and lists key details without unnecessary words. Every part earns its place by specifying the information retrieved, making it easy to scan and understand quickly.
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 moderate complexity (a read operation with one parameter) and no annotations or output schema, the description is minimally complete. It covers the purpose and key data points but lacks behavioral context and usage guidance. For a tool without structured safety or output information, more detail would be beneficial to fully inform an agent.
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 100% description coverage, with the 'name' parameter documented as 'Node name'. The description doesn't add any parameter-specific semantics beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
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 ('Get') and resource ('detailed node info'), specifying what information is retrieved (capacity, allocatable resources, conditions, taints). It distinguishes from siblings like 'k8s_get_nodes' by focusing on detailed information for a specific node rather than listing nodes. However, it doesn't explicitly contrast with 'k8s_describe_pod' for similar describe operations on different resources.
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. While the description implies it's for detailed node information, it doesn't mention when to choose this over 'k8s_get_nodes' (for listing) or 'k8s_top_nodes' (for resource usage), nor does it specify prerequisites like needing node names from other tools. The context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific pod including containers, resources, and events
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name | |
| namespace | No | Kubernetes namespace (default: 'default') |
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 states this is a read operation ('Get detailed information'), which implies non-destructive behavior, but doesn't disclose critical behavioral traits like authentication requirements, rate limits, error conditions, or output format. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves.
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 a single, efficient sentence that front-loads the core purpose ('Get detailed information about a specific pod') and adds useful scope details ('including containers, resources, and events'). Every word earns its place with zero waste or 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 moderate complexity (read operation with 2 parameters), 100% schema coverage, but no annotations or output schema, the description is minimally adequate. It covers the purpose and scope but lacks behavioral details (e.g., output format, error handling) that would be needed for full completeness, especially without annotations to fill gaps.
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 100%, with clear descriptions for both parameters ('name' and 'namespace'). The description doesn't add any parameter-specific semantics beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema adequately documents parameters.
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 ('Get detailed information') and resource ('about a specific pod'), specifying the scope ('including containers, resources, and events'). It distinguishes from generic list tools like 'k8s_get_pods' by focusing on detailed information for a specific pod, though it doesn't explicitly differentiate from similar describe tools like 'k8s_describe_node'.
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 detailed pod information is needed, but provides no explicit guidance on when to use this versus alternatives like 'k8s_get_pods' (for listing) or 'k8s_get_pod_logs' (for logs). It mentions the scope of information returned, which helps contextualize its purpose, but lacks clear when/when-not instructions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List deployments with replica status, strategy, and age
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Kubernetes namespace (default: 'default') | |
| label_selector | No | Label selector to filter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions what information is listed ('replica status, strategy, and age'), which adds some context beyond the basic 'list' action. However, it lacks details on permissions needed, rate limits, pagination, error handling, or whether it's a read-only operation (though 'get' in the name implies safety). For a tool with zero annotation coverage, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action ('List deployments') and specifies key details ('replica status, strategy, and age'). There is zero waste or redundancy, making it highly concise and well-structured for quick understanding.
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 moderate complexity (listing deployments with status details), no annotations, no output schema, and 100% schema coverage, the description is minimally adequate. It covers the purpose and output content but lacks behavioral context, usage guidelines, and details on return values. For a read operation with no output schema, it should ideally describe the response format or structure to be more 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?
The schema description coverage is 100%, with both parameters ('namespace' and 'label_selector') well-documented in the schema. The description does not add any parameter-specific information beyond what the schema provides, such as examples or formatting details. According to the rules, with high schema coverage (>80%), the baseline score is 3 when no param info is in the description.
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's purpose with a specific verb ('List') and resource ('deployments'), and specifies what information is included ('replica status, strategy, and age'). It distinguishes itself from sibling tools like 'k8s_get_pods' and 'k8s_get_services' by focusing on deployments. However, it doesn't explicitly differentiate from 'k8s_rollout_status' which also relates to deployments, preventing a perfect score.
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 no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'k8s_get_pods' for pod listings or 'k8s_rollout_status' for deployment status details, nor does it specify prerequisites such as required permissions or cluster context. Usage is implied by the action 'List deployments,' but no explicit context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cluster events filtered by namespace and type (Normal/Warning)
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Kubernetes namespace (default: 'default') | |
| type | No | Event type: 'Normal' or 'Warning' | |
| field_selector | No | Field selector for filtering | |
| limit | No | Max number of events (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but provides minimal behavioral insight. It mentions filtering but doesn't cover permissions needed, rate limits, pagination behavior, or what happens if parameters are omitted (defaults are only in schema). For a read operation in a complex system like Kubernetes, this is inadequate.
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 a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and includes key filtering details without unnecessary elaboration.
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 Kubernetes tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It lacks behavioral context (e.g., safety, permissions), usage guidance, and details on return format or error handling, leaving significant gaps for an AI agent.
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 100%, so the schema fully documents all parameters. The description adds marginal value by highlighting namespace and type filtering, but doesn't explain semantics beyond what's in the schema (e.g., how field_selector works or limit implications). Baseline 3 is appropriate.
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') and resource ('cluster events') with filtering criteria ('by namespace and type'). It distinguishes from some siblings like k8s_get_pods or k8s_get_services by specifying events, but doesn't explicitly differentiate from all possible event-related tools (though none are listed).
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 is provided. The description doesn't mention prerequisites, context, or compare it to other tools like k8s_describe_pod for detailed event views or system_logs for broader logging.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all cluster nodes with status, roles, and version
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it's a list operation, implying read-only behavior, but does not disclose critical details like permissions needed, rate limits, output format, or pagination. This is inadequate for a tool with no annotation coverage.
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 a single, efficient sentence that front-loads the core action ('List all cluster nodes') and adds clarifying details ('with status, roles, and version') without any wasted words. It is appropriately sized for a simple tool.
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 annotations and no output schema, the description is incomplete. It lacks information on behavioral aspects (e.g., permissions, rate limits) and output details (e.g., format, structure), which are essential for an agent to use this tool effectively in a Kubernetes context.
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 tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description does not add parameter details, which is appropriate, earning a baseline score of 4 for this context.
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 all cluster nodes') and specifies what information is included ('with status, roles, and version'), making the purpose specific and complete. It distinguishes itself from sibling tools like 'k8s_describe_node' (detailed view) and 'k8s_top_nodes' (resource usage).
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 node overviews, but does not explicitly state when to use this tool versus alternatives like 'k8s_describe_node' (for detailed node info) or 'k8s_top_nodes' (for resource metrics). No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch logs from a pod with options for tail lines, time range, and container selection
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name | |
| namespace | No | Kubernetes namespace (default: 'default') | |
| container | No | Container name (for multi-container pods) | |
| tail | No | Number of lines from the end (default: 100) | |
| since | No | Time duration (e.g., '5m', '1h', '2d') | |
| previous | No | Get logs from previous container instance |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It mentions options like tail lines and time range but doesn't disclose critical traits: whether this is a read-only operation, potential rate limits, authentication requirements, output format (e.g., text stream), or error conditions (e.g., if the pod doesn't exist).
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 a single, efficient sentence that front-loads the core action ('fetch logs') and lists key options without unnecessary words. Every part earns its place, making it easy to scan and understand quickly.
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 tool with 6 parameters, no annotations, and no output schema, the description is incomplete. It lacks context on behavioral aspects (e.g., safety, errors), usage guidelines, and output details, which are crucial for an AI agent to invoke this tool correctly in a Kubernetes environment.
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 100%, so the schema fully documents all 6 parameters. The description adds marginal value by summarizing key options ('tail lines, time range, and container selection'), but doesn't provide additional semantics beyond what's in the schema, such as usage examples or constraints not captured in 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 verb ('fetch logs') and resource ('from a pod'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'docker_container_logs' or 'system_logs', which also fetch logs from different sources, leaving some ambiguity about when to choose this specific Kubernetes tool.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing Kubernetes cluster access), compare it to sibling tools like 'k8s_describe_pod' for debugging, or specify scenarios where fetching logs is appropriate versus other diagnostic tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pods in a Kubernetes namespace with their status, restarts, and age
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Kubernetes namespace (default: 'default') | |
| label_selector | No | Label selector to filter pods (e.g., 'app=nginx') | |
| field_selector | No | Field selector (e.g., 'status.phase=Running') |
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 the returned fields (status, restarts, age) but lacks critical behavioral details: it doesn't specify if this is a read-only operation, whether it requires specific permissions, if there are rate limits, the output format (e.g., table, JSON), or pagination handling. For a tool with no annotations, this leaves significant gaps in understanding its behavior.
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 a single, efficient sentence that front-loads the core action ('List pods') and includes key details (location, returned fields). There is no wasted text, repetition, or unnecessary elaboration, making it highly concise and well-structured for quick understanding.
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 moderate complexity (listing with optional filters), 100% schema coverage, and no output schema, the description is minimally adequate. It covers the basic purpose but lacks behavioral context (e.g., safety, permissions, output format) and usage guidelines, which are important for a tool interacting with a Kubernetes cluster. Without annotations or output schema, more detail would improve completeness.
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 100%, so the schema fully documents the three parameters (namespace, label_selector, field_selector). The description adds no parameter-specific information beyond implying a listing action, which the schema already covers through parameter descriptions. This meets the baseline of 3 for high schema coverage without additional 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 pods') and resource ('in a Kubernetes namespace'), specifying what information is returned ('status, restarts, and age'). It distinguishes from other k8s tools like 'k8s_describe_pod' or 'k8s_get_pod_logs' by focusing on listing with specific fields, though it doesn't explicitly differentiate from 'k8s_get_deployments' or 'k8s_get_services' beyond the resource type.
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. It doesn't mention prerequisites (e.g., needing cluster access), compare to sibling tools like 'k8s_describe_pod' for detailed info or 'k8s_get_pod_logs' for logs, or specify scenarios where it's preferred. The description only states what it does, not when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List services with type, cluster IP, ports, and age
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Kubernetes namespace (default: 'default') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states this is a list operation but doesn't disclose behavioral traits like pagination, rate limits, permission requirements, or whether it returns all services or a subset. 'List services' implies read-only, but this isn't explicitly confirmed.
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 a single, efficient sentence that's front-loaded with the core action. Every word contributes meaning 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?
For a simple list tool with 1 parameter and no output schema, the description is minimally adequate. However, with no annotations and multiple similar siblings, it should provide more context about scope, limitations, and differentiation.
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 100%, so the schema already documents the namespace parameter. The description doesn't add any parameter-specific information beyond what's in the schema. With 0 parameters mentioned in description, baseline 3 is appropriate.
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 ('services'), and specifies what information is included (type, cluster IP, ports, age). However, it doesn't explicitly differentiate from sibling tools like 'k8s_get_pods' or 'k8s_get_deployments' beyond the resource name.
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 about when to use this tool versus alternatives. The description doesn't mention prerequisites, context, or exclusions. With multiple k8s_get_* siblings, this is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rollback a deployment to the previous revision
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deployment name | |
| namespace | No | Kubernetes namespace (default: 'default') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a mutation ('Rollback') but doesn't disclose critical behaviors: whether it requires admin permissions, if it's destructive to current deployment state, potential downtime, rate limits, or what happens on success/failure. This is inadequate for a mutation tool with zero annotation coverage.
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 a single, efficient sentence with zero waste—front-loaded with the core action and resource. Every word earns its place, making it easy to parse quickly.
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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It lacks behavioral details (e.g., side effects, error handling) and output expectations, which are crucial for safe agent operation in a Kubernetes context with siblings like k8s_delete_pod.
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 100%, with clear parameter docs in the schema. The description adds no parameter-specific information beyond implying 'deployment' relates to the 'name' parameter. Baseline 3 is appropriate as the schema handles parameter semantics effectively.
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 ('Rollback') and target resource ('a deployment'), specifying it goes 'to the previous revision'. It distinguishes from siblings like k8s_scale_deployment or k8s_get_deployments by focusing on revision reversal, though it doesn't explicitly contrast them.
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. It doesn't mention prerequisites (e.g., needing a previous revision), exclusions, or related tools like k8s_rollout_status for monitoring rollbacks, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the rollout status of a deployment
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deployment name | |
| namespace | No | Kubernetes namespace (default: 'default') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the tool 'checks' status, implying a read-only operation, but doesn't clarify what 'rollout status' includes (e.g., progress percentages, error messages, timestamps), whether it's real-time or cached, or if there are rate limits or authentication requirements. For a tool with no annotations, this leaves significant behavioral gaps.
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 a single, efficient sentence with zero wasted words—it directly states the tool's purpose without redundancy. It's front-loaded and easy to parse, making it highly concise and well-structured for quick understanding.
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 complexity of Kubernetes operations and lack of annotations or output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., status details, success/failure indicators), behavioral aspects like error handling, or how it integrates with sibling tools (e.g., k8s_rollback_deployment). For a tool with no structured output documentation, this leaves the agent guessing about results and usage context.
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 100%, with both parameters ('name' and 'namespace') clearly documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema, such as examples or constraints. However, since the schema fully covers the parameters, the baseline score of 3 is appropriate—the description doesn't compensate but doesn't need to.
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 ('check') and resource ('rollout status of a deployment'), making the purpose immediately understandable. It distinguishes from siblings like k8s_get_deployments (which lists deployments) and k8s_rollback_deployment (which performs an action). However, it doesn't specify what 'rollout status' entails (e.g., progress, health, completion), leaving some ambiguity.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a deployment to exist), differentiate from similar tools like k8s_get_deployments (which might show deployment details), or specify use cases (e.g., monitoring updates, troubleshooting). Without this context, the agent must infer usage 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.
Scale a deployment to a specified number of replicas
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Deployment name | |
| namespace | No | Kubernetes namespace (default: 'default') | |
| replicas | Yes | Desired number of replicas |
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 scaling but lacks critical behavioral details: it doesn't specify that this is a mutation (potentially destructive), what permissions are required, whether it's idempotent, how it handles errors, or if there are rate limits. For a Kubernetes scaling tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence with zero waste—it directly states the tool's purpose without fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.
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 complexity of a Kubernetes scaling operation, no annotations, and no output schema, the description is incomplete. It lacks information on behavioral traits (e.g., mutation effects, error handling), usage context, and return values. For a tool that modifies cluster state, this minimal description leaves too many gaps for safe and effective 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 100%, so the schema already documents all parameters (name, namespace, replicas) with descriptions. The description adds no additional parameter semantics beyond implying 'replicas' is the target count. Baseline is 3 when the schema does the heavy lifting, and the description doesn't compensate with extra details like format constraints or examples.
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 ('scale') and resource ('deployment') with a specific outcome ('to a specified number of replicas'). It's unambiguous but doesn't explicitly differentiate from sibling tools like 'k8s_rollback_deployment' or 'k8s_get_deployments', which would require mentioning it's a scaling operation rather than status checking or rollback.
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. For example, it doesn't mention prerequisites (e.g., needing a deployment to exist), when not to use it (e.g., for other resource types), or how it relates to siblings like 'k8s_get_deployments' for checking current replicas. The description only states what it does, not when to apply it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show CPU and memory usage for all cluster nodes (requires metrics-server)
| Name | Required | Description | Default |
|---|---|---|---|
No 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. While it mentions the metrics-server requirement (useful context), it doesn't disclose other behavioral traits such as whether this is a read-only operation, what format the output takes, whether it shows real-time or historical data, or any rate limits. For a metrics tool with zero annotation coverage, this leaves significant gaps.
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 a single, efficient sentence that front-loads the core purpose ('Show CPU and memory usage for all cluster nodes') and includes essential context ('requires metrics-server') without any wasted words. Every element earns its place.
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 moderate complexity (metrics display), lack of annotations, and no output schema, the description is somewhat complete but has gaps. It covers the purpose and prerequisite well, but doesn't explain the output format or behavioral details. For a tool that presumably returns structured metrics data, more context about the return values would be helpful.
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 tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the lack of parameters. The description doesn't need to add parameter information, and it appropriately focuses on the tool's purpose and prerequisites instead. A baseline of 4 is appropriate 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 specific action ('Show CPU and memory usage') and target resource ('for all cluster nodes'), distinguishing it from siblings like k8s_get_nodes (which lists nodes without metrics) and k8s_top_pods (which shows metrics for pods). It provides a precise verb+resource combination.
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 when to use this tool ('Show CPU and memory usage for all cluster nodes') and includes a critical prerequisite ('requires metrics-server'), which helps differentiate it from alternatives like k8s_get_nodes that don't require metrics-server. It clearly defines the tool's specific context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show CPU and memory usage for pods (requires metrics-server)
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Kubernetes namespace (default: 'default') |
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 mentions the prerequisite 'requires metrics-server', which is valuable context about dependencies. However, it doesn't disclose other behavioral traits like whether this is a read-only operation, what format the output takes, potential rate limits, or error conditions.
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 - a single sentence that communicates the core purpose and a critical prerequisite. Every word earns its place with zero waste. It's front-loaded with the main functionality.
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 this is a monitoring/read tool with no annotations and no output schema, the description provides basic completeness by stating what it does and a key prerequisite. However, for a tool that presumably returns metrics data, more context about output format or behavior would be helpful. It's adequate but has clear gaps.
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 100% with one parameter clearly documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't need to.
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's purpose: 'Show CPU and memory usage for pods' - a specific verb (show) and resource (pods) with what metrics (CPU and memory). It distinguishes from siblings like k8s_get_pods (which lists pods) and k8s_describe_pod (which provides detailed configuration), though it doesn't explicitly mention these distinctions.
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 some usage context with 'requires metrics-server', indicating a prerequisite. However, it doesn't explicitly state when to use this tool versus alternatives like k8s_top_nodes (for node metrics) or when not to use it. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a node as schedulable (uncordon) — re-enables pod scheduling
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Node name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It states the action but doesn't disclose critical behavioral traits like required permissions, whether this is a safe operation, potential side effects, or what happens if the node is already uncordoned. The description is minimal and lacks operational context.
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 with just one sentence that front-loads the core purpose. Every word earns its place, and there's no redundant information or 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?
For a single-parameter mutation tool with no annotations and no output schema, the description is minimally adequate. It states what the tool does but lacks details about behavioral implications, success/failure responses, or prerequisites. Given the complexity of Kubernetes operations, more context would be beneficial.
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 100% for the single parameter 'name' (described as 'Node name'), so the baseline is 3. The description adds value by implicitly confirming this parameter refers to the node being uncordoned, elevating the score slightly above baseline.
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 specific action ('Mark a node as schedulable (uncordon)') and resource ('node'), with the parenthetical clarifying the Kubernetes term. It distinguishes from its sibling 'k8s_cordon_node' by specifying the opposite operation.
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 context by stating it 're-enables pod scheduling,' suggesting it should be used after a node has been cordoned. However, it doesn't explicitly state when NOT to use it or mention alternatives like 'k8s_cordon_node' by name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all currently firing Prometheus alerts
| Name | Required | Description | Default |
|---|---|---|---|
No 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 of behavioral disclosure. While 'List' implies a read-only operation, it doesn't specify whether this tool requires authentication, has rate limits, returns real-time data, or includes metadata like alert durations. For a monitoring tool with zero annotation coverage, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality ('List all currently firing Prometheus alerts'). There is no wasted verbiage or redundant information, making it highly concise 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 the tool's simplicity (0 parameters, no output schema), the description is minimally adequate. However, it lacks context about the return format (e.g., JSON structure, alert fields) and behavioral traits like error handling or dependencies. Without annotations or output schema, the description should ideally provide more operational context for a monitoring 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?
The tool has 0 parameters with 100% schema description coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate. A baseline of 4 is applied since no parameters exist, and the description doesn't introduce confusion about inputs.
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 ('currently firing Prometheus alerts'), making the purpose specific and unambiguous. It distinguishes itself from sibling tools like prom_alert_rules (which likely lists alert rules rather than active alerts) and prom_instant_query/prom_range_query (which are for querying metrics).
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., Prometheus server availability), nor does it differentiate from similar tools like prom_alert_rules or general query tools. Usage context is implied 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.
List all Prometheus alert rules and their current state
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool lists rules and states, implying a read-only operation, but does not disclose behavioral traits such as required permissions, rate limits, pagination, or error handling. This is a significant gap for a tool with no annotation coverage.
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 a single, efficient sentence that front-loads the purpose ('List all Prometheus alert rules and their current state') with zero wasted words. It is appropriately sized for a simple tool.
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 (0 parameters, no output schema, no annotations), the description is minimally adequate. However, it lacks details on output format (e.g., structure of rules and states) and behavioral context, which would be helpful for an AI agent to use it correctly without annotations.
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 parameters with 100% coverage, so no parameter documentation is needed. The description does not add parameter details, which is appropriate, but it could marginally enhance semantics by clarifying scope (e.g., all namespaces). Baseline is 4 for zero parameters.
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 specific action ('List all') and resource ('Prometheus alert rules and their current state'), distinguishing it from sibling tools like prom_active_alerts (which likely shows only active alerts) and prom_instant_query/prom_range_query (which are for querying metrics). It precisely defines scope without redundancy.
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 alert rules and states, providing clear context. However, it does not explicitly state when to use this versus alternatives like prom_active_alerts or general query tools, nor does it mention prerequisites or exclusions, leaving some guidance gaps.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a PromQL instant query and return current values
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | PromQL query expression |
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 states the tool executes a query and returns current values, but lacks critical details such as authentication requirements, rate limits, error handling, or what 'current values' entail (e.g., format, timestamps). This is inadequate for a tool that likely interacts with a monitoring system.
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 a single, efficient sentence that front-loads the core action. There's no wasted verbiage, though it could benefit from slightly more detail given the lack of annotations and output schema.
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 complexity of querying a monitoring system, no annotations, and no output schema, the description is insufficient. It doesn't explain return values, error conditions, or behavioral traits, leaving significant gaps for an AI agent to use the tool effectively.
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 adds no parameter-specific information beyond what the input schema provides, which has 100% coverage. It mentions 'PromQL instant query' but doesn't elaborate on the 'query' parameter's syntax or examples. The baseline score of 3 reflects that the schema does the heavy lifting, but the description doesn't enhance understanding.
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 ('Execute a PromQL instant query') and the resource ('PromQL'), making the purpose understandable. However, it doesn't explicitly differentiate from its sibling 'prom_range_query', which is a notable gap since both are Prometheus query 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 no guidance on when to use this tool versus alternatives like 'prom_range_query' or other monitoring tools in the sibling list. There's no mention of prerequisites, context, or exclusions, leaving usage entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a PromQL query over a time range and return series data
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | PromQL query expression | |
| start | No | Start time (ISO 8601, default: 1h ago) | |
| end | No | End time (ISO 8601, default: now) | |
| step | No | Query step (e.g., '60s', '5m', default: '60s') |
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 the action and return type ('return series data') but lacks critical behavioral details: no information about authentication requirements, rate limits, error handling, response format, or whether this is a read-only operation. For a query tool with no annotations, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and clearly states the purpose. Every element earns its place.
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 annotations and no output schema, the description is minimally adequate but incomplete. It covers the basic purpose and distinguishes from one sibling, but lacks behavioral context (auth, limits, errors) and output details. For a query tool with 4 parameters and no structured safety hints, it should do more.
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 100%, so the schema already fully documents all 4 parameters. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain PromQL syntax or provide examples). Baseline 3 is appropriate when schema does all the work.
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 ('Execute a PromQL query') and the resource ('series data'), with the specific scope 'over a time range'. It distinguishes from sibling 'prom_instant_query' by specifying range queries, but doesn't explicitly mention all siblings like 'prom_active_alerts' or 'prom_alert_rules'.
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 time-range queries versus instant queries (sibling 'prom_instant_query'), but doesn't explicitly state when to choose this tool over alternatives like 'prom_active_alerts' or provide any exclusion criteria. Usage context is implied rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show Prometheus scrape target health status
| Name | Required | Description | Default |
|---|---|---|---|
No 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 of behavioral disclosure. It states 'show' which implies a read-only operation, but doesn't specify whether it requires authentication, rate limits, or what the output format looks like. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
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 a single, efficient sentence that directly states the tool's purpose without any unnecessary words. It's front-loaded and wastes no space, making it highly concise 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 the tool has no parameters and no output schema, the description adequately covers the basic purpose. However, without annotations or output details, it lacks information on behavioral traits like authentication needs or return format, making it minimally complete but with clear gaps for practical 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?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter details, and it appropriately doesn't mention any, earning a baseline score for tools with no parameters.
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 'show' and the resource 'Prometheus scrape target health status', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like prom_active_alerts or prom_alert_rules, which also show Prometheus-related information but focus on different aspects.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage based on the name alone without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a directory for leaked secrets and credentials using Gitleaks
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | Directory to scan (default: current directory) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool performs a scan but doesn't describe what happens during execution (e.g., is it read-only or does it modify files?), output format, error handling, performance implications, or security considerations. This leaves significant gaps for an agent to 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and tool name, making it easy for an agent to parse quickly. Every word serves a clear purpose.
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 complexity of a security scanning tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the scan returns (e.g., findings, report format), how to interpret results, or any behavioral aspects. For a tool that could have significant operational impact, more context is needed to guide proper usage.
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 100% description coverage, with the single parameter 'directory' clearly documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema. According to the rules, when schema coverage is high (>80%), the baseline score is 3 even without param details in the description.
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 ('scan') and target ('directory for leaked secrets and credentials') using the specific tool 'Gitleaks'. It distinguishes itself from sibling tools by focusing on security scanning rather than Docker, Kubernetes, Prometheus, or system operations. However, it doesn't explicitly differentiate from 'security_trivy_scan' (another security tool), which might cause some ambiguity.
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 no guidance on when to use this tool versus alternatives like 'security_trivy_scan' or other security tools. It doesn't mention prerequisites, typical use cases, or scenarios where this tool is preferred over others. The agent must infer usage from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit Kubernetes namespace for security misconfigurations (privileged containers, missing limits, RBAC issues)
| Name | Required | Description | Default |
|---|---|---|---|
| namespace | No | Kubernetes namespace to audit (default: 'default') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the action 'audit' and types of misconfigurations but does not disclose critical traits such as whether it requires specific RBAC permissions, if it performs read-only operations (implied but not stated), potential rate limits, output format, or error handling. This leaves significant gaps for a security auditing 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 a single, efficient sentence that front-loads the core purpose ('Audit Kubernetes namespace for security misconfigurations') and provides specific examples without unnecessary elaboration. Every word contributes to understanding the tool's function, making it appropriately sized 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 the complexity of security auditing and the lack of annotations and output schema, the description is incomplete. It does not cover behavioral aspects like permissions needed, safety profile (e.g., read-only vs. destructive), or what the audit output entails. For a tool with no structured data beyond the input schema, more context is needed to adequately guide an AI agent.
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 100% description coverage, with the 'namespace' parameter documented as 'Kubernetes namespace to audit (default: 'default')'. The description adds no additional parameter semantics beyond what the schema provides, such as format constraints or examples. With high schema coverage, the baseline score of 3 is appropriate, as the description does not compensate but also does not detract.
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 'audit' and the resource 'Kubernetes namespace', specifying the purpose as checking for 'security misconfigurations' with concrete examples like 'privileged containers, missing limits, RBAC issues'. This distinguishes it from sibling tools that perform different operations on Kubernetes resources (e.g., k8s_get_pods, k8s_describe_pod) or other security tools (e.g., security_gitleaks_scan).
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 no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., required permissions, cluster access), exclusions (e.g., what it does not audit), or comparisons to other security tools like security_trivy_scan. Usage is implied only by the tool's name and description, lacking explicit context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a container image for vulnerabilities using Trivy
| Name | Required | Description | Default |
|---|---|---|---|
| image | Yes | Container image to scan (e.g., 'nginx:latest') | |
| severity | No | Severity filter (default: 'HIGH,CRITICAL') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool scans for vulnerabilities but doesn't disclose behavioral traits like what happens during scanning (e.g., network access, resource usage), output format, error conditions, or whether it's read-only or has side effects. This leaves significant gaps for a security scanning 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 a single, efficient sentence with zero waste. It's front-loaded with the core purpose and uses clear, direct language without unnecessary elaboration.
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 annotations and no output schema, the description is incomplete for a security scanning tool. It lacks details on what the scan returns (e.g., vulnerability list, severity breakdown), how results are structured, or any behavioral context like execution time or dependencies. This makes it inadequate for informed tool selection.
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 100%, so the schema already documents both parameters ('image' and 'severity') adequately. The description doesn't add any meaning beyond what the schema provides, such as examples of severity values beyond the default or scanning limitations. Baseline 3 is appropriate when schema does the heavy lifting.
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 ('Scan') and resource ('container image') with the specific tool ('using Trivy'). It distinguishes from most siblings by focusing on vulnerability scanning rather than Docker/Kubernetes operations, though it doesn't explicitly differentiate from 'security_gitleaks_scan' and 'security_k8s_audit' which are also security 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 is provided about when to use this tool versus alternatives. The description doesn't mention when scanning is appropriate, prerequisites, or how it differs from other security tools like 'security_gitleaks_scan' or 'security_k8s_audit' on the same server.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show disk usage for the system or a specific path
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Specific path to check (optional, shows all filesystems if omitted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it 'shows' disk usage, implying a read-only operation, but doesn't disclose behavioral traits like output format (e.g., human-readable vs. structured data), permissions needed, performance impact, or error handling. For a tool with zero annotation coverage, this is inadequate.
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 a single, efficient sentence that front-loads the core purpose ('Show disk usage') and clarifies scope ('for the system or a specific path'). There is zero wasted text, making it easy to parse quickly.
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 annotations and no output schema, the description is incomplete. It lacks details on what disk usage metrics are shown (e.g., total, used, free space), output format, or error conditions. For a system monitoring tool with potential complexity, this leaves significant gaps for an AI agent to use it effectively.
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 100%, with the parameter 'path' fully documented in the schema. The description adds minimal value by mentioning 'specific path to check' and default behavior when omitted, but doesn't provide additional semantics like path format examples or filesystem constraints. Baseline 3 is appropriate given high schema coverage.
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 'show' and resource 'disk usage', specifying it can be for 'the system or a specific path'. It distinguishes from siblings like system_logs or system_network_connections by focusing on disk metrics. However, it doesn't explicitly differentiate from potential disk-related tools not present in the sibling list.
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 is provided. The description mentions optional path parameter usage but doesn't explain scenarios for system-wide vs. path-specific checks or relate to other monitoring tools like system_processes. Usage context is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read system logs from journalctl or a log file
| Name | Required | Description | Default |
|---|---|---|---|
| unit | No | Systemd unit name (e.g., 'nginx', 'docker') | |
| lines | No | Number of lines to show (default: 50) | |
| path | No | Path to a log file (alternative to journalctl) |
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 reading logs but lacks critical behavioral details: required permissions (e.g., sudo), whether it's safe or destructive, output format, error handling, or rate limits. This is inadequate for a tool that likely needs elevated access.
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 a single, efficient sentence with zero waste. It's front-loaded with the core purpose and specifies sources without unnecessary elaboration, making it easy to parse quickly.
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 annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like safety, permissions, or output format, which are crucial for a system tool. The schema handles parameters well, but overall context for safe and effective use is lacking.
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 100%, so parameters are well-documented in the schema. The description adds no additional meaning beyond implying 'unit' and 'path' correspond to journalctl and log file sources, but this is minimal value. Baseline 3 is appropriate as the schema does the heavy lifting.
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 ('Read') and resource ('system logs'), specifying the sources ('journalctl or a log file'). It distinguishes from sibling tools like 'docker_container_logs' by focusing on system-level logs rather than container-specific ones, though it doesn't explicitly contrast with them.
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 is provided. While it implies usage for system logs (vs. container logs in siblings), there's no explicit direction on choosing between journalctl and file paths, or when to prefer this over similar tools like 'system_processes'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show active network connections and listening ports
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Filter by connection state (e.g., 'listening') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'show' implies a read-only operation, it doesn't specify whether this requires elevated permissions, what output format to expect, if it's real-time or cached data, or any rate limits. For a system-level tool with zero annotation coverage, this is a significant gap in 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 a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core purpose, making it easy to parse. Every part of the sentence earns its place by conveying essential 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 lack of annotations and output schema, the description is incomplete for a system-level tool. It doesn't explain what the output contains (e.g., connection details, protocols, addresses), potential side effects, or error conditions. For a tool that could expose sensitive network information, more context is needed to ensure safe and effective 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?
The schema description coverage is 100%, with the single parameter 'state' fully documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides (e.g., examples of other states like 'established'). This meets the baseline score of 3 for high schema coverage.
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's purpose: 'Show active network connections and listening ports'. It uses specific verbs ('show') and resources ('network connections', 'listening ports'), making the function evident. However, it doesn't explicitly differentiate from sibling tools like 'system_processes' or 'system_logs', which prevents a perfect score.
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 no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, exclusions, or comparisons with sibling tools (e.g., 'system_processes' for process-level info or 'docker_list_networks' for container networking). This lack of context leaves the agent to infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List top processes sorted by CPU or memory usage
| Name | Required | Description | Default |
|---|---|---|---|
| sort_by | No | 'cpu' or 'memory' (default: 'memory') | |
| limit | No | Number of processes to show (default: 20) |
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 sorting and limiting but lacks critical behavioral details: whether this is a real-time snapshot or historical data, permissions required, potential performance impact, output format, or error conditions. For a system monitoring tool with zero annotation coverage, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List top processes') and adds essential detail ('sorted by CPU or memory usage'). There is no wasted verbiage, repetition, or unnecessary elaboration.
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 complexity of system monitoring, lack of annotations, and no output schema, the description is incomplete. It doesn't explain what 'top processes' means (e.g., current snapshot, aggregated metrics), return format, or behavioral constraints. For a tool that could have significant system interaction, more context is needed.
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 100%, so the schema fully documents both parameters (sort_by and limit) with their types, descriptions, and defaults. The description adds no additional parameter semantics beyond implying sorting by CPU/memory, which is already covered in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
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 top processes') and the resource ('processes'), with specific criteria ('sorted by CPU or memory usage'). It distinguishes from sibling tools like system_disk_usage or system_network_connections by focusing on processes, but doesn't explicitly differentiate from potential similar tools not present in the list.
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. The description doesn't mention prerequisites, context (e.g., monitoring vs. troubleshooting), or comparisons to sibling tools like system_logs or docker_container_stats, leaving the agent to infer usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Terraform output values
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | Directory containing Terraform files | |
| name | No | Specific output name (optional, shows all if omitted) |
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 states 'Read' implying a read-only operation, but doesn't disclose behavioral traits such as whether it requires Terraform initialization, what happens if the directory is invalid, or if there are rate limits. This leaves significant gaps for a tool with no annotation coverage.
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 a single, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to scan and understand quickly.
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 annotations and no output schema, the description is minimal but covers the basic purpose. For a read operation with two parameters, it's adequate but lacks details on behavior, error handling, or return format, which could help an agent use it correctly in context with sibling tools.
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 100%, so the schema fully documents both parameters. The description doesn't add any meaning beyond what the schema provides (e.g., it doesn't explain what 'output values' are in Terraform context or provide examples). Baseline 3 is appropriate when the schema does the heavy lifting.
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 'Read Terraform output values' clearly states the verb ('Read') and resource ('Terraform output values'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'terraform_state_show' or 'terraform_plan', which also involve reading Terraform data, so it misses full sibling distinction.
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. The description doesn't mention sibling tools like 'terraform_state_show' or 'terraform_plan', nor does it explain prerequisites or context for reading output values versus other Terraform operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run terraform plan to preview infrastructure changes (read-only, safe)
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | Directory containing Terraform files |
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 effectively communicates that the operation is read-only and safe, which is crucial for a Terraform plan tool that previews changes without applying them. However, it lacks details on execution time, output format, or potential side effects like state locking.
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 a single, efficient sentence that front-loads the core action ('Run terraform plan') and includes essential qualifiers in parentheses. Every word earns its place, with no redundancy or unnecessary elaboration.
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 tool with one parameter (fully documented in schema), no annotations, and no output schema, the description provides adequate context by clarifying the tool's purpose and safety. It could be more complete by mentioning typical output or linking to Terraform documentation, but it covers the essentials given the low 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?
The input schema has 100% description coverage, with the single parameter 'directory' clearly documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema, so it meets the baseline of 3 for high schema coverage without compensating 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 specific action ('Run terraform plan') and resource ('preview infrastructure changes'), with the parenthetical adding important context about safety. It distinguishes from siblings like terraform_output, terraform_state_list, and terraform_validate by focusing on change previewing rather than output retrieval, state inspection, or validation.
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 context through 'preview infrastructure changes' and '(read-only, safe)', suggesting it's for checking changes before applying them. However, it doesn't explicitly state when to use this versus alternatives like terraform_validate for syntax checking or terraform_state_show for current state inspection, nor does it mention 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 all resources in the Terraform state
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | Directory containing Terraform files |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a listing operation, implying read-only behavior, but doesn't mention whether this requires specific permissions, whether it reads from local or remote state, what happens if the state is locked, or what format the output takes. For a state inspection tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple listing tool and front-loads the essential 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?
For a single-parameter listing tool with no output schema, the description provides the basic purpose but lacks important context. It doesn't explain what the output looks like (list format, resource identifiers, state versions), doesn't mention error conditions (missing state file, invalid directory), and doesn't provide usage guidance relative to sibling tools. Given the complexity of Terraform state management, this leaves gaps in understanding how to effectively use the 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?
Schema description coverage is 100%, so the schema already documents the single 'directory' parameter. The description doesn't add any parameter-specific information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in description.
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') and resource ('all resources in the Terraform state'), making the purpose immediately understandable. It distinguishes from sibling tools like terraform_state_show (which shows specific resources) by emphasizing 'all resources'. However, it doesn't specify the verbosity level or format of the listing.
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 about when to use this tool versus alternatives. While it's clear this lists resources, there's no mention of prerequisites (like requiring a Terraform state file), comparison to terraform_state_show (which shows details of specific resources), or when this listing would be preferred over other state inspection methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show details of a specific resource in Terraform state
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | Directory containing Terraform files | |
| resource | Yes | Resource address (e.g., 'aws_instance.web') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a read operation ('show details'), but doesn't mention whether it requires specific permissions, what format/details are returned, potential errors, or any rate limits. This leaves significant gaps for a tool that interacts with Terraform state.
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 a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for this tool's complexity and front-loads the essential 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?
For a read-only tool with 2 parameters and 100% schema coverage, the description is minimally adequate but has clear gaps. Without annotations or output schema, it should explain more about what 'details' are returned, error conditions, or behavioral characteristics. The description alone doesn't provide complete context for safe and effective 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 100%, so the schema already documents both parameters thoroughly. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it doesn't explain relationships between parameters, provide examples beyond the schema's resource example, or clarify edge cases.
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 ('show details') and target ('specific resource in Terraform state'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'terraform_state_list' or 'terraform_output', which prevents a perfect score.
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 about when to use this tool versus alternatives. The description doesn't mention prerequisites, appropriate contexts, or comparisons with sibling tools like 'terraform_state_list' (which lists resources) or 'terraform_output' (which shows outputs).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate Terraform configuration and check formatting
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes | Directory containing Terraform files |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'validate' and 'check formatting' imply a read-only analysis operation, it doesn't specify whether this tool makes any changes, what permissions are required, whether it's safe to run repeatedly, what happens with invalid configurations, or what the output format looks like. For a tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 just two verb phrases that directly convey the core functionality. Every word earns its place, and the structure is front-loaded with the essential information. There's no wasted text or unnecessary elaboration.
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 purpose (configuration validation), lack of annotations, and absence of an output schema, the description is insufficiently complete. It doesn't explain what constitutes successful validation versus errors, what specific checks are performed, or what format results are returned in. For a validation tool with no structured output documentation, the description should provide more context about expected outcomes.
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 100% with the single 'directory' parameter fully documented in the schema. The description doesn't add any parameter-specific information beyond what's already in the schema, but with complete schema coverage, the baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
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's purpose with specific verbs ('validate', 'check formatting') and resource ('Terraform configuration'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like terraform_plan or terraform_state_list, which also work with Terraform configurations but 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.
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. There are several Terraform-related sibling tools (terraform_plan, terraform_output, terraform_state_list, terraform_state_show), but the description doesn't indicate whether this should be used before planning, after changes, or in what specific validation context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes with clear boundaries between domains (Docker, Kubernetes, Prometheus, Security, System, Terraform). However, there is some overlap between docker_compose_logs and docker_container_logs, and between k8s_get_pods and k8s_describe_pod, which could cause minor confusion. Overall, the descriptions help clarify differences, but the sheer number of tools increases cognitive load.
Tool names follow a highly consistent snake_case pattern with clear domain prefixes (docker_, k8s_, prom_, security_, system_, terraform_) and descriptive verb_noun combinations. This predictable structure makes it easy to understand each tool's purpose and domain at a glance, with no deviations in naming conventions.
With 43 tools, this server feels overloaded for a single MCP server. While the tools cover multiple infrastructure domains, the count is excessive and will overwhelm agents. A more focused approach with separate servers for Docker, Kubernetes, monitoring, etc., would be more appropriate. The scope is too broad for effective tool selection.
Within each domain, the tool coverage is quite comprehensive. Docker has inspection, listing, and monitoring tools; Kubernetes covers pod management, scaling, rollouts, and monitoring; Prometheus includes queries and alerts; Security has scanning tools; System provides diagnostics; and Terraform covers state and planning. Minor gaps exist (e.g., no Docker container creation/management, no Kubernetes pod creation), but agents can work around these given the broad coverage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for building and testing AI agents with multi-model experimentation and insights.
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
The Remote MCP server acts as a standardized bridge between LLM applications (like Claude, ChatGPT, and Cursor) and external services, enabling AI agents to access external tools and resources. Its primary capability is providing a centralized search tool to discover other MCP servers and their respective tools. Unlike local implementations, it runs remotely with OAuth authentication and permission controls for security.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/batu-sonmez/infraclaude'
If you have feedback or need assistance with the MCP directory API, please join our Discord server