CloudOps MCP ist ein schreibgeschützter Model Context Protocol-Server, der normalisierten Betriebsinfrastrukturkontext (Logs, Metriken, Bereitstellungen, Zustand) für KI-Agenten über eine kleine Menge typisierter, begrenzter Werkzeuge bereitstellt.
Ein Agent, der einen Vorfall untersucht, benötigt Betriebskontext: was sich kürzlich geändert hat, wie die Fehlerrate aussieht, was die Logs sagen. Er benötigt keinen uneingeschränkten Zugriff auf Cloud-APIs, und er sollte nicht das sein, was entscheidet, was als Grundursache gilt.
CloudOps MCP sitzt zwischen beiden:
Cloud APIs / observability systems
|
Provider adapters
|
Normalized operational domain
|
Deterministic services
|
MCP tools
|
AI agentJede Schicht normalisiert weiter und schränkt ein, was der Agent anfragen kann. Provider-Adapter übersetzen Anbieter-APIs in ein gemeinsames Domänenmodell. Dienste wenden Begrenzungen, Sortierung und Aggregation deterministisch an, auf die gleiche Weise für jeden Anbieter. MCP-Werkzeuge legen dies als eine kleine, typisierte Oberfläche dar.
CloudOps MCP liefert Betriebsfakten, keine Schlussfolgerungen zur Grundursache. Ein Werkzeug kann sagen „Fehlerrate von 0,4 % auf 8 % um 14:06 gestiegen“; es wird nicht sagen „die Bereitstellung hat den Ausfall verursacht.“ Dieses Urteil obliegt dem Agenten, mit den Fakten, die CloudOps MCP ihm als Beweismittel übergibt.
Related MCP server: cloud-chat-assistant
Sechs Werkzeuge, alle schreibgeschützt und begrenzt:
Werkzeug | Zweck |
| Bekannte Dienste auflisten und welche Fähigkeiten für jeden konfiguriert sind. |
| Vom Anbieter gemeldeter Zustand eines Dienstes. Nie aus Logs oder Metriken abgeleitet. |
| Kürzliche Bereitstellungsereignisse, begrenzt nach Zeitraum und Anzahl. |
| Log-Ereignisse, begrenzt nach Zeitraum, Anzahl und Nachrichtenlänge. |
| Metrikreihen mit deterministischen Aggregaten (min/max/Durchschnitt/letzter); Rohdatenpunkte sind optional und begrenzt. |
| Eine zusammengesetzte Ansicht: kürzliche Bereitstellungen, konfigurierte Snapshot-Metriken, kürzliche Logs und Zustand, in einem begrenzten Aufruf. |
get_operational_snapshot setzt sich aus denselben primitiven Diensten zusammen, die auch die anderen fünf Werkzeuge verwenden, und führt alle vier unabhängigen Abfragen gleichzeitig aus. Es kommuniziert nie direkt mit einem Anbieter, und es schlägt nie als Ganzes fehl, weil ein Abschnitt nicht verfügbar ist; jeder Abschnitt meldet seinen eigenen Status.
Von Grund auf schreibgeschützt. Anbieterschnittstellen legen keine Mutationsmethoden offen. Es gibt keinen Codepfad zu einer Schreib-API.
Anbieterneutrale Dienstidentität. Ein Dienst wird durch (service, environment) identifiziert. Anbieterspezifische Bezeichner (eine CloudWatch-Loggruppe, ein Kubernetes-Objektname) bleiben intern in den Anbieterbindungen und sind nie Teil des öffentlichen Vertrags.
Kanonische, erweiterbare Metriken. error_rate, latency_p99 und ähnliche Namen sind unsere, nicht die des Anbieters. Die Abbildung eines kanonischen Namens auf eine echte Metrik lebt in der Konfiguration, pro Dienst. Das Vokabular ist offen, kein festgelegtes Enum.
Begrenzte Abfragen. Jede Telemetrieabfrage hat eine Zeitbereichsobergrenze und eine Anzahlsobergrenze. Ein Aufrufer kann nach weniger fragen; er kann nicht nach unbegrenzten Daten fragen.
Explizite Datenverfügbarkeit. Jede Sammlung meldet einen von SUCCESS, EMPTY, PARTIAL oder FAILED. Fehlende Daten werden nie stillschweigend als „gesund“ oder „nichts passiert“ behandelt.
Verfügbarkeit getrennt vom Ergebnis. NOT_CONFIGURED (kein Anbieter angeschlossen) und EMPTY (erfolgreich abgefragt, null Treffer) sind unterschiedliche Zustände und werden nie vermischt.
Herkunft ohne Offenlegung von Interna. Einzelergebnisse tragen provider und source, wenn ein Anbieteradapter sie liefert. Die interne Referenz, die zum Aufrufen eines Anbieters verwendet wird, wird nie in die öffentliche Ausgabe kopiert.
Überall UTC. Alle Zeitstempel sind zeitzonenbewusst und auf UTC normalisiert; naive Datums-/Zeitangaben werden an der Modellgrenze zurückgewiesen.
Kein LLM im MCP-Server. Keine Zusammenfassung, keine Klassifizierung, keine Schlussfolgerung über Log-Inhalte. Log-Nachrichten werden als undurchsichtiger, nicht vertrauenswürdiger Text behandelt.
Keine kausale Argumentation. Werkzeuge berichten, was sich wann geändert hat. Die Interpretation des Warums bleibt dem Agenten überlassen.
Der Fake-Modus ist der Standard und der primäre Weg, CloudOps MCP auszuprobieren. Er benötigt kein Cloud-Konto.
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"Den Server ausführen (stdio-Transport):
python -m cloudops_mcp.serverOder, wenn das Paket mit seinem Konsolenskript installiert ist:
cloudops-mcpDer Server spricht MCP über stdio und erwartet einen Client auf der anderen Seite. Um es direkt von Python aus mit dem Client des offiziellen SDKs zu testen:
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())Wählen Sie ein Szenario mit CLOUDOPS_MCP_SCENARIO (Standard healthy):
Szenario | Was es simuliert |
| Ein Dienst mit jeder konfigurierten Fähigkeit, nichts Ungewöhnliches. |
| Eine Bereitstellung, dann eine Veränderung der Fehlerrate und Latenz, dann Timeout-Logs. |
| Eine Fähigkeit schlägt während der Abfrage fehl, eine ist nicht konfiguriert, der Rest erfolgreich. |
CLOUDOPS_MCP_SCENARIO=bad_deploy python -m cloudops_mcp.serverbad_deploy säht drei korrelierte Fakten zu festen Zeitstempeln: eine Bereitstellung, dann eine Metrikverschiebung einige Minuten später, dann Timeout-Logzeilen kurz danach. CloudOps MCP meldet diese drei Fakten und sonst nichts. Es behauptet nicht, dass die Bereitstellung die Fehler verursacht hat; diese Schlussfolgerung wird vollständig dem verbrauchenden Agenten überlassen.
pip install -e ".[aws]" # runtime only
pip install -e ".[dev,aws]" # developmentCLOUDOPS_MCP_MODE=aws CLOUDOPS_MCP_CONFIG=/path/to/cloudops.toml cloudops-mcpSiehe examples/aws-cloudwatch.toml für eine vollständige Beispielkonfiguration. Sie verwendet nur Platzhalterwerte, keine echte Konto-ID, ARN oder Anmeldeinformation gehört in diese Datei.
Anmeldeinformationen stammen vollständig aus boto3s Standard-Provider-Kette: AWS_PROFILE, AWS_REGION / AWS_DEFAULT_REGION, Umgebungsanmeldeinformationen oder eine IAM-Rolle. CloudOps MCP liest, speichert oder protokolliert niemals einen Zugriffsschlüssel oder ein Secret.
Im AWS-Modus implementiert:
Logs: CloudWatch Logs FilterLogEvents.
Metrics: CloudWatch GetMetricData (MetricStat queries only).
Noch nicht implementiert: AWS-gestützte Bereitstellungen und Zustand. Ein Dienst, der ohne diese Abschnitte konfiguriert ist, meldet einfach NOT_CONFIGURED für sie, wie jede andere nicht konfigurierte Fähigkeit. Siehe docs/aws.md für Konfigurationsschema, Paginierungsverhalten und Einschränkungen.
Mindestrichtlinie für schreibgeschützten Zugriff für diese Integration (fiktives Konto und Loggruppe):
{
"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 kann auf die spezifische Loggruppen-ARN eingegrenzt werden. Für die MetricStat-Abfragen, die diese Integration ausgibt, hat GetMetricData keine ressourcenbezogene Eingrenzung im IAM-Autorisierungsmodell von AWS, daher verwendet diese Anweisung Resource: "*". Das ist eine Eigenschaft der API, keine hier getroffene Wahl.
Ressource | Standard | Harte Obergrenze |
Services listed | 50 | 200 |
Log events | 100 | 500 |
Log message length | - | 2000 chars |
Log/metric time range | 1 hour | 24 hours (logs), 7 days (metrics) |
Metric points per series | - | 500 |
Deployment events | 20 | 100 |
Snapshot metrics per service | - | 5 |
Jedes begrenzte Ergebnis meldet sowohl requested_bounds als auch applied_bounds, sodass ein Aufrufer genau sehen kann, was begrenzt wurde. Eine Begrenzung einer Anfrage auf die harte Obergrenze ist nicht dasselbe wie PARTIAL: Eine begrenzte, aber vollständig erfüllte Abfrage ist immer noch SUCCESS. PARTIAL bedeutet, dass die Extraktion selbst bekanntermaßen unvollständig ist, zum Beispiel wenn ein Anbieter paginiert und aufgehört hat, bevor alle Treffer innerhalb des angewendeten Fensters ausgeschöpft wurden.
Zwei orthogonale Fragen, die nie zu einer zusammengefasst werden:
Ist eine Fähigkeit für diesen Dienst überhaupt konfiguriert? (CONFIGURED / NOT_CONFIGURED)
Wenn sie abgefragt wurde, was ist passiert? (SUCCESS / EMPTY / PARTIAL / FAILED)
Zustand | Bedeutung |
| Kein Anbieter ist für diese Fähigkeit angeschlossen. Es wurde keine Abfrage versucht. |
| Der Anbieter wurde abgefragt, die Extraktion wurde ausgeschöpft, und es gab keine Treffer. |
| Der Anbieter wurde abgefragt und hat ein vollständiges Ergebnis zurückgegeben. |
| Die Extraktion ist bekanntermaßen unvollständig. Daten können vorhanden sein oder nicht, z. B. war jede bisher gescannte Seite leer, aber es existieren weitere Seiten. |
| Der Anbieter wurde abgefragt, und der Aufruf selbst ist fehlgeschlagen (Timeout, Authentifizierungsfehler, Ratenbegrenzung). |
Eine Zustandsprüfung für einen Dienst ohne konfigurierten Zustandsanbieter ist NOT_CONFIGURED, nicht EMPTY und nicht FAILED. Eine Log-Abfrage, die im Zeitfenster berechtigterweise nichts gefunden hat, ist EMPTY, nicht FAILED. Ein Metrikaufruf, der auf eine Ratenbegrenzung stößt, bevor er etwas Verwertbares zurückgibt, ist FAILED mit einem Grund, nicht stillschweigend leere Daten.
Jedes Werkzeug akzeptiert typisierte Argumente und gibt ein typisiertes Pydantic-Modell zurück. Das offizielle Python MCP SDK leitet structuredContent und das Ausgabeschema des Werkzeugs direkt von diesem Rückgabetyp ab, Werkzeugantworten sind echte strukturierte Daten, kein JSON-String, der in einen Textblock eingewickelt ist.
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 setzt die primitiven Dienste zusammen, es umgeht sie nicht oder spricht selbst mit Anbietern. Siehe docs/architecture.md für die vollständige technische Aufschlüsselung.
Deterministische Fake-Szenarien üben die gesamte Werkzeugoberfläche Ende-zu-Ende.
Tests auf Anbieterebene verwenden absichtlich fehlverhaltende Stub-Anbieter (falsche Sortierung, ignorierte Begrenzungen), um zu beweisen, dass die Dienstschicht die Ausgabe selbst verteidigt, nicht nur wohlverhaltende Anbieter.
AWS-Anbieter-Tests verwenden kleine Stub-CloudWatch-Clients, keine echten AWS-Aufrufe, kein moto, kein LocalStack.
Ein Test treibt den echten MCP SDK-Client gegen einen prozessinternen Server an und bestätigt die Protokollgrenze selbst (Werkzeugerkennung, strukturierte Ausgabe) und nicht nur die interne Logik.
ruff check src tests
mypy src tests --strict
pytest -qDie Live-Validierung für AWS wurde mit typisierter Konfigurationsanalyse, gestubten Client-Tests und der echten MCP-Client/Server-Grenze durchgeführt, noch nicht gegen ein echtes AWS-Konto. Das erfordert benutzerausgewählte Ressourcen und ist absichtlich nicht automatisiert: CloudOps MCP entdeckt oder prüft kein Konto von sich aus.
Noch keine AWS-gestützten Bereitstellungen oder Zustandsanbieter.
Nur stdio-Transport, kein Remote-MCP.
Das Dienstregister ist statisch und konfigurationsgestützt, es gibt keine automatische Erkennung von Diensten aus einem Cloud-Konto.
Keine Mutation, Behebung oder Schreibpfad jeglicher Art.
Zusätzliche schreibgeschützte Fähigkeiten bei bestehenden Anbietern.
Ein zweiter echter Anbieter, um die Normalisierungsgrenze gegen mehr als einen Anbieter zu testen.
Ein Remote-Transport, falls ein Bereitstellungsszenario tatsächlich einen benötigt.
Nutzung durch Incident-Response-Agenten als ein Beispiel eines generischen MCP-Clients. CloudOps MCP ist an keinen bestimmten Verbraucher gekoppelt.
Keine Mutationsmethoden irgendwo in den Provider-Schnittstellen.
Keine Shell-Ausführung, keine Aufrufe von Cloud-CLI-Subprozessen.
Least-Privilege-IAM: genau logs:FilterLogEvents und cloudwatch:GetMetricData, nichts wird "für den Fall der Fälle" angefordert.
Nur die Standard-AWS-Anmeldeinformationskette, keine benutzerdefinierte Anmeldeinformationsverwaltung.
Interne Provider-Referenzen (Log-Gruppennamen, CloudWatch-Dimensionen) erscheinen niemals in der Tool-Ausgabe.
Log-Inhalte werden als nicht vertrauenswürdiger, undurchsichtiger Text behandelt: niemals geparst, ausgeführt oder interpretiert.
Unerwartete Fehler werden an der Tool-Grenze bereinigt; nur eine feste, generische Nachricht überschreitet sie, niemals eine rohe Ausnahmestring.
Jede Telemetrieabfrage ist begrenzt, um sowohl die Provider-APIs als auch das Kontextfenster des Agents zu schützen.
MIT, siehe 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.
