Skip to main content
Glama
Iqram09

kong-ai-gateway-mcp

by Iqram09
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Check upstream target health

check_upstream_health
Read-onlyIdempotent

Check Kong's health verdict for each upstream target to diagnose 503 errors and see if the backend pool can serve traffic. Reports HEALTHY, UNHEALTHY, DNS_ERROR, or HEALTHCHECKS_OFF.

Instructions

Reports Kong's own health verdict for each target of an upstream.

USE WHEN: a route returns 503, or you have ruled out authentication and routing and need to know whether the backend pool is actually serving. Reach this tool from a service whose host names a Kong upstream.

CRITICAL DISTINCTION between the verdicts this returns: HEALTHY probed and responding UNHEALTHY address is correct, backend is failing -> availability problem DNS_ERROR address cannot be resolved -> configuration problem HEALTHCHECKS_OFF Kong is not probing at all -> health is UNKNOWN, not healthy

Do not read HEALTHCHECKS_OFF as "fine". It means no information.

RETURNS: targets each with target, health, weight and a meaning line; plus healthchecksEnabled, verdict and canServeTraffic.

LIMITATIONS: reports the gateway's view only, and that view is only as fresh as Kong's last probe or proxied request for this upstream. A freshly created or rebuilt target is reported HEALTHY before the first probe runs, and an idle upstream can show a stale HEALTHY for a target that is actually down. If a HEALTHY verdict contradicts other evidence (e.g. 503s), say so rather than treating it as proof the backend is up.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
upstreamYesUpstream name, id, or `upstream:<name>` reference. When a service's `host` field names a Kong upstream, pass that host value here.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.9/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, non-destructive behavior, but the description adds substantial operational context: the meaning of each verdict, the critical warning that HEALTHCHECKS_OFF means unknown rather than healthy, staleness limitations, and the possibility of contradictory evidence. This far exceeds 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.

Conciseness5/5

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

The description is front-loaded with purpose, then structured into USE WHEN, verdict distinctions, RETURNS, and LIMITATIONS. Despite its length, every section earns its place and uses formatting to aid scanning.

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

Completeness5/5

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

Even without an output schema, the description explains the return fields (targets, healthchecksEnabled, verdict, canServeTraffic) and the nuance of each verdict. Nothing an agent needs to interpret results or decide when to call this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds practical mapping guidance: 'When a service's host field names a Kong upstream, pass that host value here.' That helps the agent translate a service configuration into the correct upstream parameter value.

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

Purpose5/5

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

States a specific verb+resource: reports Kong's own health verdict for each target of an upstream. It clearly distinguishes this read-only health probe from siblings like diagnose_route and list_upstreams by focusing on the gateway's target-level verdict.

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

Usage Guidelines5/5

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

Provides explicit trigger conditions (route returns 503, auth/routing ruled out) and the exact context required (service whose host names a Kong upstream). This is a textbook when-to-use statement that leaves no ambiguity.

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

Deploy Server

Other Tools