CloudOps MCP es un servidor de solo lectura del Model Context Protocol que expone contexto operacional de infraestructura normalizado (logs, métricas, despliegues, estado) a agentes de IA a través de un pequeño conjunto de herramientas tipadas y acotadas.
Un agente que investiga un incidente necesita contexto operacional: qué cambió recientemente, cómo se ve la tasa de error, qué dicen los logs. No necesita acceso sin restricciones a las APIs de la nube, y no debería ser quien decida qué constituye una causa raíz.
CloudOps MCP se sitúa entre los dos:
Cloud APIs / observability systems
|
Provider adapters
|
Normalized operational domain
|
Deterministic services
|
MCP tools
|
AI agentCada capa normaliza aún más y reduce lo que el agente puede solicitar. Los adaptadores de proveedor traducen las APIs de los proveedores a un modelo de dominio compartido. Los servicios aplican límites, ordenación y agregación de manera determinista, de la misma forma para cada proveedor. Las herramientas MCP exponen eso como una superficie pequeña y tipada.
CloudOps MCP devuelve hechos operacionales, no conclusiones de causa raíz. Una herramienta puede decir "la tasa de error aumentó del 0,4% al 8% a las 14:06"; no dirá "el despliegue causó la interrupción". Ese juicio pertenece al agente, con los hechos que CloudOps MCP le entrega como evidencia.
Related MCP server: cloud-chat-assistant
Seis herramientas, todas de solo lectura y acotadas:
Herramienta | Propósito |
| Lista los servicios conocidos y qué capacidades están configuradas para cada uno. |
| Estado reportado por el proveedor para un servicio. Nunca inferido a partir de logs o métricas. |
| Eventos de despliegue recientes, acotados por rango de tiempo y cantidad. |
| Eventos de log, acotados por rango de tiempo, cantidad y longitud del mensaje. |
| Series de métricas con agregados deterministas (mín/máx/promedio/último); los puntos brutos son optativos y acotados. |
| Una vista compuesta: despliegues recientes, métricas de instantánea configuradas, logs recientes y estado, en una llamada acotada. |
get_operational_snapshot compone los mismos servicios primitivos que usan las otras cinco herramientas, ejecutando las cuatro consultas independientes de forma concurrente. Nunca habla directamente con un proveedor y nunca falla en su conjunto porque una sección no esté disponible; cada sección reporta su propio estado.
Solo lectura por construcción. Las interfaces de proveedor no exponen métodos de mutación. No existe ninguna ruta de código hacia una API de escritura.
Identidad de servicio neutral respecto al proveedor. Un servicio se identifica por (service, environment). Los identificadores específicos de proveedor (un grupo de logs de CloudWatch, un nombre de objeto de Kubernetes) permanecen internos a los enlaces del proveedor y nunca forman parte del contrato público.
Métricas canónicas y extensibles. error_rate, latency_p99 y nombres similares son nuestros, no del proveedor. La correspondencia de un nombre canónico a una métrica real reside en la configuración, por servicio. El vocabulario es abierto, no una enumeración fija.
Consultas acotadas. Cada consulta de telemetría tiene un límite de rango de tiempo y un límite de cantidad. Un solicitante puede pedir menos; no puede pedir datos sin límite.
Disponibilidad de datos explícita. Cada recolección reporta uno de SUCCESS, EMPTY, PARTIAL, o FAILED. Los datos faltantes nunca se tratan silenciosamente como "saludable" o "no pasó nada".
Disponibilidad separada del resultado. NOT_CONFIGURED (ningún proveedor conectado) y EMPTY (consultado con éxito, cero coincidencias) son estados diferentes y nunca se confunden.
Procedencia sin filtrar internos. Los resultados individuales llevan provider y source cuando un adaptador de proveedor los proporciona. La referencia interna utilizada para llamar a un proveedor nunca se copia en la salida pública.
UTC en todas partes. Todas las marcas de tiempo son conscientes de la zona horaria y están normalizadas a UTC; las fechas y horas ingenuas se rechazan en el límite del modelo.
Sin LLM dentro del servidor MCP. Sin resumen, sin clasificación, sin inferencia sobre el contenido de los logs. Los mensajes de log se tratan como texto opaco y no confiable.
Sin razonamiento causal. Las herramientas reportan qué cambió y cuándo. Interpretar el por qué se deja al agente.
El modo fake es el predeterminado y la forma principal de probar CloudOps MCP. No necesita ninguna cuenta en la nube.
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"Ejecuta el servidor (transporte stdio):
python -m cloudops_mcp.serverO, si el paquete está instalado con su script de consola:
cloudops-mcpEl servidor habla MCP sobre stdio y espera un cliente al otro lado. Para probarlo directamente desde Python, usando el cliente del SDK oficial:
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
params = StdioServerParameters(command="python", args=["-m", "cloudops_mcp.server"])
async with stdio_client(params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
print([t.name for t in tools.tools])
result = await session.call_tool(
"get_operational_snapshot",
{"service": "checkout-api", "environment": "production"},
)
print(result.structured_content)
asyncio.run(main())Selecciona un escenario con CLOUDOPS_MCP_SCENARIO (por defecto healthy):
Escenario | Qué simula |
| Un servicio con cada capacidad configurada, nada inusual. |
| Un despliegue, luego un cambio en la tasa de error y latencia, luego logs de timeout. |
| Una capacidad fallando a medio camino, una no configurada, el resto teniendo éxito. |
CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.serverbad_deploy siembra tres hechos correlacionados en marcas de tiempo fijas: un despliegue, luego un cambio en las métricas unos minutos después, luego líneas de log de timeout poco después. CloudOps MCP reporta esos tres hechos y nada más. No afirma que el despliegue causó los errores; esa inferencia se deja enteramente al agente consumidor.
pip install -e ".[aws]" # runtime only
pip install -e ".[dev,aws]" # developmentCLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcpConsulta examples/aws-cloudwatch.toml para un ejemplo completo de configuración. Solo utiliza valores de relleno; ningún ID de cuenta real, ARN o credencial debe estar en ese archivo.
Las credenciales provienen enteramente de la cadena de proveedores estándar de boto3: AWS_PROFILE, AWS_REGION / AWS_DEFAULT_REGION, credenciales de entorno, o un rol de IAM. CloudOps MCP nunca lee, almacena ni registra una clave de acceso o secreto.
Implementado en modo AWS:
Logs: CloudWatch Logs FilterLogEvents.
Métricas: CloudWatch GetMetricData (consultas MetricStat únicamente).
Aún no implementado: despliegues y estado respaldados por AWS. Un servicio configurado sin esas secciones simplemente reporta NOT_CONFIGURED para ellas, igual que cualquier otra capacidad no configurada. Consulta docs/aws.md para el esquema de configuración, comportamiento de paginación y limitaciones.
Política de solo lectura mínima para esta integración (cuenta y grupo de logs ficticios):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "logs:FilterLogEvents",
"Resource": "arn:aws:logs:us-east-1:123456789012:log-group:/aws/lambda/checkout-api"
},
{
"Effect": "Allow",
"Action": "cloudwatch:GetMetricData",
"Resource": "*"
}
]
}FilterLogEvents puede acotarse al ARN específico del grupo de logs. Para las consultas MetricStat que emite esta integración, GetMetricData no tiene ámbito a nivel de recurso en el modelo de autorización IAM de AWS, por lo que esa declaración usa Resource: "*". Eso es una propiedad de la API, no una elección tomada aquí.
Recurso | Valor por defecto | Límite máximo |
Servicios listados | 50 | 200 |
Eventos de log | 100 | 500 |
Longitud del mensaje de log | - | 2000 caracteres |
Rango de tiempo de log/métrica | 1 hora | 24 horas (logs), 7 días (métricas) |
Puntos de métrica por serie | - | 500 |
Eventos de despliegue | 20 | 100 |
Métricas de instantánea por servicio | - | 5 |
Cada resultado acotado reporta tanto requested_bounds como applied_bounds, para que un solicitante pueda ver exactamente qué se ajustó. Ajustar una solicitud al límite máximo no es lo mismo que PARTIAL: una consulta ajustada pero completamente satisfecha sigue siendo SUCCESS. PARTIAL significa que la extracción en sí misma está incompleta, por ejemplo, un proveedor paginó y se detuvo antes de agotar todas las coincidencias dentro de la ventana aplicada.
Dos preguntas ortogonales, nunca fusionadas en una:
¿Está una capacidad configurada para este servicio? (CONFIGURED / NOT_CONFIGURED)
Si se consultó, ¿qué sucedió? (SUCCESS / EMPTY / PARTIAL / FAILED)
Estado | Significado |
| Ningún proveedor está conectado para esta capacidad. No se intentó ninguna consulta. |
| Se consultó al proveedor, la extracción se agotó y no hubo coincidencias. |
| Se consultó al proveedor y devolvió un resultado completo. |
| La extracción está incompleta. Puede haber datos o no; por ejemplo, cada página escaneada hasta ahora estaba vacía pero existen más páginas. |
| Se consultó al proveedor y la llamada en sí falló (timeout, error de autenticación, límite de tasa). |
Una verificación de estado para un servicio sin proveedor de estado configurado es NOT_CONFIGURED, no EMPTY ni FAILED. Una consulta de log que legítimamente no encontró nada en la ventana de tiempo es EMPTY, no FAILED. Una llamada de métricas que alcanzó un límite de tasa antes de devolver algo utilizable es FAILED con una razón, no datos vacíos silenciosos.
Cada herramienta toma argumentos tipados y devuelve un modelo Pydantic tipado. El SDK oficial de MCP para Python deriva structuredContent y el esquema de salida de la herramienta directamente de ese tipo de retorno; las respuestas de las herramientas son datos estructurados reales, no una cadena JSON envuelta en un bloque de texto.
flowchart TD
subgraph Providers
Fake[Fake providers]
AWS[AWS CloudWatch providers]
end
Fake --> Services
AWS --> Services
Registry[ServiceRegistry] --> Services
subgraph Services[Deterministic services]
Catalog[catalog_service]
Health[health_service]
Deploy[deployment_service]
Logs[logs_service]
Metrics[metrics_service]
Snapshot[snapshot_service]
end
Snapshot --> Deploy
Snapshot --> Logs
Snapshot --> Metrics
Snapshot --> Health
Services --> Tools[MCP tools]
Tools --> Agent[AI agent]get_operational_snapshot compone los servicios primitivos, no los elude ni habla directamente con proveedores. Consulta docs/architecture.md para el desglose técnico completo.
Escenarios fake deterministas ejercitan toda la superficie de las herramientas de extremo a extremo.
Las pruebas a nivel de proveedor utilizan proveedores stub deliberadamente mal comportados (orden incorrecto, límites ignorados) para demostrar que la capa de servicio defiende la salida en sí misma, no solo proveedores bien comportados.
Las pruebas del proveedor de AWS utilizan pequeños clientes stub de CloudWatch, sin llamadas reales a AWS, sin moto, sin LocalStack.
Una prueba impulsa el cliente real del SDK de MCP contra un servidor en proceso, confirmando el límite del protocolo en sí (descubrimiento de herramientas, salida estructurada) en lugar de solo la lógica interna.
ruff check src tests
mypy src tests --strict
pytest -qLa validación en vivo de AWS se ha realizado con análisis de configuración tipado, pruebas de cliente stub y el límite real del cliente/servidor MCP, aún no contra una cuenta real de AWS. Eso requiere recursos seleccionados por el usuario y no se automatiza intencionalmente: CloudOps MCP no descubre ni sondea una cuenta por sí mismo.
Aún no hay proveedor de despliegues o estado respaldado por AWS.
Solo transporte stdio, sin MCP remoto.
El registro de servicios es estático y respaldado por configuración; no hay descubrimiento automático de servicios desde una cuenta en la nube.
No hay mutación, remediación ni ruta de escritura de ningún tipo.
Capacidades adicionales de solo lectura en proveedores existentes.
Un segundo proveedor real, para probar el límite de normalización contra más de un vendedor.
Un transporte remoto, si un escenario de despliegue realmente lo necesita.
Consumo por agentes de respuesta a incidentes, como un ejemplo de cliente MCP genérico. CloudOps MCP no está acoplado a ningún consumidor específico.
No hay métodos de mutación en ninguna de las interfaces del proveedor.
No se ejecutan comandos de shell ni llamadas a subprocesos de CLI en la nube.
IAM con mínimo privilegio: exactamente logs:FilterLogEvents y cloudwatch:GetMetricData, nada
solicitado "por si acaso".
Solo se utiliza la cadena de credenciales estándar de AWS, sin manejo personalizado de credenciales.
Las referencias internas del proveedor (nombres de grupos de logs, dimensiones de CloudWatch) nunca aparecen en la salida de la herramienta.
El contenido de los logs se trata como texto no confiable y opaco: nunca se analiza, ejecuta ni interpreta.
Los fallos inesperados se sanean en el límite de la herramienta; solo un mensaje fijo y genérico lo cruza, nunca una cadena de excepción sin procesar.
Cada consulta de telemetría está acotada, protegiendo tanto las API del proveedor como la ventana de contexto del agente.
MIT, consulte LICENSE.
Get log events for a service, bounded by time range, count, and message length. Message content is opaque and never interpreted.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| max_events | No | ||
| time_range | No | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that message content is opaque and never interpreted and that results are bounded by count and message length (i.e., truncation behavior), but omits ordering, permissions, and, critically, what happens when time_range is null.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the core operation front-loaded and zero filler; the opacity caveat follows the scope statement logically.
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?
An output schema exists, so return values need not be explained. However, the absence of annotations and of any guidance on the required service/environment values or on the null-defaulted time_range leaves meaningful gaps for an agent to resolve.
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 on the named properties is 0%, so the description must compensate. It loosely maps to time_range and max_events but gives no format or default semantics, and the two required parameters (service, environment) are undocumented in both schema and 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?
States a specific verb and resource ('Get log events for a service') and names the dimensions it is bounded by (time range, count, message length). The resource is clearly distinguishable from siblings like get_metrics and get_service_health, though it never explicitly routes the agent against 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 when-to-use guidance, no prerequisites, and no mention of alternatives such as get_metrics or get_operational_snapshot for higher-level views. The bounding clauses describe limits, not when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metric series for a service. metric_names must be canonical names from get_services' available_metrics for that service. Always includes deterministic aggregates (min/max/average/last); raw points only when include_points=True, bounded.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| max_points | No | ||
| time_range | No | ||
| environment | Yes | ||
| metric_names | Yes | ||
| include_points | No |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose output-shaping behavior: deterministic aggregates (min/max/average/last) are always returned, raw points only when include_points=True, and results are bounded. It says nothing about auth requirements, defaults for time_range, or rate limits, so it is strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the core action and then the two key constraints; almost no filler. The trailing word 'bounded' is terse to the point of ambiguity about what bound applies.
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?
An output schema exists, so the description need not restate return fields, and it still usefully flags the conditional raw-points behavior. Given the 0% parameter coverage, it leaves time_range, service, and environment semantics undocumented, which is the main gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% across 6 parameters, so the description must compensate and only partially does: it explains metric_names (canonical names from get_services) and include_points, and hints at max_points via 'bounded'. service, environment, and time_range semantics (inclusive start / exclusive end, default) are left entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Get metric series for a service'), which naturally separates it from siblings like get_logs or get_service_health that operate on different resources. It is clear but never explicitly names a sibling or contrasting scope, so it stops short of 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?
It gives a concrete precondition: metric_names must be canonical names obtained from get_services' available_metrics, effectively telling the agent to call get_services first. It does not state when to prefer get_metrics over get_operational_snapshot or get_service_health, so no exclusions are covered.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a bounded operational snapshot for a service: recent deployments, its configured snapshot metrics, recent logs, and health. Each section reports its own status independently; a failure or unconfigured capability in one section never hides the others. Reports facts only, never a root cause.
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| time_range | No | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| logs | Yes | |
| health | Yes | |
| metrics | Yes | |
| service | Yes | |
| deployments | Yes | |
| environment | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does meaningful work: each section reports status independently, a failure or unconfigured capability in one section never hides others, and it reports facts only, never root cause. These are genuinely useful operational traits. It still omits what 'bounded' means concretely, permission/auth requirements, and volume limits for logs and metrics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the purpose followed by two high-value behavioral notes. No filler, and each sentence adds information about scope or behavior rather than restating the name.
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?
An output schema exists, so return-value explanation is not needed, and the description adequately covers purpose and partial-failure semantics. However, for an aggregation tool with three parameters and 0% schema coverage, the absence of parameter semantics and any guidance on choosing it over its four siblings leaves 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 0%, so the description must compensate, and it largely does not. 'for a service' gestures at the required service parameter, but environment, the optional time_range, and the default-null behavior are unexplained. The nested TimeRange carries its own schema description, but nothing in the tool description clarifies how parameters shape the snapshot.
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?
States a specific verb and resource (get an operational snapshot for a service) and enumerates the four content areas: deployments, metrics, logs, and health. This maps cleanly onto the four sibling tools, but the description never explicitly contrasts itself with those siblings (e.g., 'use this instead of calling get_logs/get_metrics separately'), so differentiation is implied rather than stated.
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 word 'bounded' hints at a scoped overview use case, but there is no explicit when-to-use, when-not-to-use, or mention of the sibling alternatives it aggregates. An agent cannot tell from the text whether to prefer this tool over get_recent_deployments + get_logs + get_metrics + get_service_health.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get recent deployment events for a service, bounded by time/count
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| max_events | No | ||
| time_range | No | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Bounded by time/count' gestures at limiting behavior, but it never says what happens when time_range or max_events are omitted (both default to null), whether there is a server-side default window, or what the ordering/recency guarantee is. Read-only intent is only implied by the verb 'get'.
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?
A single front-loaded sentence with no filler; the scope qualifier follows the core action. It is efficient, though 'bounded by time/count' is compressed to the point of ambiguity.
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?
An output schema exists, so return-value documentation is not required, and the read-only nature of a 'get' tool is largely self-evident. Still, with zero annotations and two nullable tuning parameters, the description omits default-window behavior and the required environment parameter, leaving the agent to infer invocation semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It covers 'service' and loosely maps 'time/count' onto time_range and max_events, but the required 'environment' parameter is never mentioned and no defaults or format details are supplied (the UTC/inclusive-start semantics live only in the nested schema).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb (get) and resource (recent deployment events) plus scope (for a service, bounded by time/count), which distinguishes it from get_logs, get_metrics, and get_service_health. It does not name any sibling explicitly, so it stops short of 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 word 'recent' hints at a use case, but there is no statement of when to prefer this over get_logs, get_metrics, or get_operational_snapshot, and no exclusions or prerequisites. An agent must infer everything about tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Provider-reported health signal for a service, never inferred
| Name | Required | Description | Default |
|---|---|---|---|
| service | Yes | ||
| environment | Yes |
| Name | Required | Description |
|---|---|---|
| capability | No | |
| collection | No | |
| availability | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it does disclose one meaningful trait: the signal is provider-reported and never inferred, which tells the agent this is authoritative provenance rather than a derived heuristic. It still omits freshness, auth requirements, failure/unknown states, and error semantics for a tool whose entire value is a status signal.
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?
A single clause, front-loaded with the resource and followed by the one qualifier that matters. Nothing is padded and nothing needs trimming.
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?
An output schema exists, so return values need not be described, and the tool is structurally simple with only two params. Still, with zero annotations and zero parameter coverage, the definition leaves the agent without usage context or argument semantics, so it is only minimally 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?
Both parameters (service, environment) have 0% schema description coverage, and the description adds no meaning — it does not clarify identifier format, environment naming, or whether defaults exist. For a 2-param required tool at zero coverage, the description should compensate and does not.
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 names a specific resource (a service's health signal) and its provenance, so an agent can distinguish it from get_logs, get_metrics, or get_recent_deployments. However, there is no explicit verb and no named sibling to route against, so differentiation is implied rather than stated.
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?
There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_operational_snapshot or get_metrics. The agent is left to infer that this is the health-check counterpart to the other read tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List known services and which capabilities are configured for each.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | No | ||
| max_services | No |
| Name | Required | Description |
|---|---|---|
| services | No | |
| truncated | No | |
| applied_max | Yes | |
| requested_max | Yes | |
| returned_count | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only list but does not state authentication requirements, pagination behavior, rate limits, or error handling.
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?
A single front-loaded sentence with no filler or redundancy. It is appropriately concise for a list operation, though its brevity contributes to gaps in other dimensions.
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?
An output schema exists, so return values need not be explained. However, with zero annotations and 0% parameter description coverage, the description omits filtering behavior (environment) and result limiting (max_services), leaving the agent without enough context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the environment or max_services parameters at all. With 0% schema description coverage, it fails to compensate for the missing parameter documentation.
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?
States a specific verb ('List') and resource ('services') plus the returned data ('capabilities configured for each'). However, it does not differentiate from siblings such as get_operational_snapshot, so it misses the top 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 when-to-use guidance, prerequisites, or alternatives are named. Sibling tools like get_service_health or get_operational_snapshot are not referenced, leaving the agent to infer when this inventory tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_logsget_metricsget_operational_snapshotget_recent_deploymentsget_service_healthget_servicesScored across 6 tools
Each tool targets a distinct observability resource or action: service inventory, deployments, health, logs, metrics, and a composite snapshot. The composite snapshot is explicitly scoped as a bounded aggregation, so it does not blur with the individual tools. No two tools appear to do the same thing.
All six tools use the same get_ verb prefix and snake_case convention, with clear noun phrases (get_services, get_recent_deployments, get_service_health, get_logs, get_metrics, get_operational_snapshot). The pattern is predictable and easy to scan.
Six tools is a well-scoped size for a read-only CloudOps observability server. Each tool covers a distinct monitoring concern without redundant or filler endpoints.
The surface covers core operational data: services, deployments, health, logs, metrics, and a combined snapshot. Minor gaps exist for adjacent operational context such as alerts/incidents or deployment detail views, but core diagnostic workflows are supported.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
