Provides read-only triage of Kubernetes CronJobs through the cluster API: lists CronJobs with health verdicts (failing, stalled, never-succeeded, degraded, overrunning, suspended), checks whether a job is on schedule, late, missed or overrunning, returns retained Job run history with duration trends and pod exit codes, finds silent failures and CronJobs that stopped firing, lists recent failed Jobs and active runs, and synthesizes failure causes from pod state, Events and log tails. Access is limited to get/list/log reads on cronjobs, jobs, pods, pods/log and events, optionally confined to an allowlist of namespaces.
Click on "Deploy 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., "@k8s-cronjob-mcp Which CronJobs in batch haven't succeeded this week, and why?"
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.
A read-only MCP server that lets an AI agent triage Kubernetes CronJobs: did it run, is it getting slower, has it quietly stopped succeeding, and why did that run fail?
General-purpose Kubernetes MCP servers expose CronJobs as just another resource type, so an agent has to fetch the CronJob, its Jobs, pods, Events and logs separately and then work out cron schedules, timezones and history limits itself. This server does that reasoning in tested code and returns a verdict with the evidence behind it, in one tool call, with zero write access to the cluster.
Use it for: on-demand triage. "Which CronJobs in batch haven't succeeded this week, and why?" "Is the nightly report job running late?" "Why did last night's run fail?"
It is not alerting. It only looks when an agent asks. Keep your existing alerts (for example Prometheus with kube-state-metrics' kube_cronjob_status_last_successful_time, or a dead-man's-switch service) to learn that something broke; use this server to find out what and why.
Tool | What it answers |
| Is the server set up correctly? Checks kubeconfig, context, auth helper, timezone, cluster reachability and read access to each resource, in the exact environment your MCP client runs it in. Every problem comes with the variable to set and where. |
| What CronJobs are there and how are they doing? One compact row each, worst first: schedule, effective timezone, health ( |
| Is it on schedule? Verdict: |
| Retained Jobs, newest first: start, duration, status ( |
| The flagship. CronJobs with no successful run in N days even if nothing is erroring right now, CronJobs that have stopped firing, CronJobs whose runs outlast their schedule, and |
| What failed recently? Every failed Job in the window (including ones not created by a CronJob), newest first, each with its synthesized cause and whether a later run of the same CronJob has succeeded since. |
| Why a Job failed. A synthesized cause (e.g. |
| What is running right now? Unfinished Jobs (including ones not created by a CronJob), longest-running first, with owning CronJob, elapsed time, pod counts, retries, deadline, and a |
Timezone. Schedules are evaluated in spec.timeZone when set, otherwise in UTC, which is what the kube-controller-manager almost always uses. The timezone of the machine running this server is never used. If your controller runs in another timezone, set CRON_DEFAULT_TIMEZONE.
Schedule check. The expected last fire time is computed from spec.schedule. The actual last run comes from the batch.kubernetes.io/cronjob-scheduled-timestamp annotation on Jobs where available (Kubernetes 1.32+), falling back to status.lastScheduleTime. A run due less than 60s ago is still on-schedule; after that it is late until startingDeadlineSeconds, then missed. If startingDeadlineSeconds is unset, Kubernetes itself has no deadline; the server uses a 300s cutoff as a heuristic and says so in the verdict.
Stopped firing. If no run has started for 3 or more scheduled fire times (and none is active), the CronJob is reported as stalled, even if it succeeded recently. This catches a frequent job that stopped an hour ago without waiting for the days window.
Overrun. Compares the median duration of recent runs (and any active run) with the shortest gap between scheduled fire times. A CronJob whose runs use more than 80% of that gap is reported as at-risk (one slow run away from overrunning). A CronJob whose runs outlast that gap is reported as degraded/overrunning, with the effect of its concurrencyPolicy: with Forbid, scheduled runs are skipped or start late; with Allow, runs overlap; with Replace, runs are cancelled before they finish. Late starts (more than 60s after the scheduled time) are counted as supporting evidence.
Silent failures. "Last success" is the later of status.lastSuccessfulTime (which survives Job deletion) and retained Jobs. The window is max(days, 2 × the schedule's cadence), so a weekly job is not flagged by a 7-day window. A brand-new CronJob that has not failed is not flagged. Suspended CronJobs are never reported as failures; find_silent_failures lists them separately (name and last success) unless include_suspended=true.
Failure cause. Checked in order: OOMKilled, DeadlineExceeded, image pull errors, container config errors, eviction, non-zero exit code (with hints such as 127 = command not found), unschedulable, then the most relevant warning Event. When a Job's pods are already gone, the cause falls back to what the Job object still records (failure reason and message, number of failed pods) and says why the evidence is missing, for example ttlSecondsAfterFinished.
Every answer says what it is based on. Each result has asOf (when it was computed) and basis, one sentence such as "Failed Jobs that finished in the last 3 days, from only the Jobs Kubernetes still keeps" or "median of last 2 successful runs". When ALLOWED_NAMESPACES is set, scope shows those namespaces instead of "all namespaces".
Related MCP server: platform-mcp-server
This is deliberate and enforced in two independent places:
Code. The only Kubernetes calls are get/list/log reads. The ClusterReader interface in src/k8s/client.ts has no create/patch/delete/exec method for a tool to call.
RBAC. deploy/rbac.yaml grants get/list/watch on exactly cronjobs, jobs, pods, pods/log and events. Nothing else: no secrets, no pods/exec, no write verbs. npm run check:rbac asserts this against a real cluster (47 checks: reads allowed, every write denied).
Also worth knowing:
Set ALLOWED_NAMESPACES=a,b to confine the server to specific namespaces; anything else is refused before any API call. This is enforced by the server, not by Kubernetes: the bundled RBAC is a ClusterRole, so the ServiceAccount itself can still read pods and logs cluster-wide. If you need Kubernetes to enforce the boundary, bind the same rules with a namespaced Role and RoleBinding in each namespace instead.
Log tails are passed through a best-effort secret masker (passwords, tokens, API keys, bearer tokens). It is pattern-based and will not catch everything; treat logs as potentially sensitive.
Job and pod data comes from live cluster state. There is no database. What you can see is bounded by successfulJobsHistoryLimit/failedJobsHistoryLimit, and Events expire after about an hour by default.
Requires Node 20+. No install step is needed; npx fetches it on demand.
Add it to Claude Code (stdio):
claude mcp add k8s-cronjobs -e K8S_CONTEXT=my-context -- npx -y k8s-cronjob-mcpOr to any MCP client config:
{
"mcpServers": {
"k8s-cronjobs": {
"command": "npx",
"args": ["-y", "k8s-cronjob-mcp"],
"env": {
"K8S_CONTEXT": "my-context",
"ALLOWED_NAMESPACES": "batch,reports"
}
}
}
}Variable | Meaning |
| Standard kubeconfig lookup, or in-cluster config when running in a pod. |
| Context to use instead of the kubeconfig's current one. Set this explicitly so the server cannot silently target the wrong cluster. |
| Optional comma-separated allowlist. |
| Timezone for CronJobs that do not set |
To run from source instead: npm install && npm run build, then use node /absolute/path/to/dist/index.js as the command.
To give the server its own least-privilege identity, apply deploy/rbac.yaml and build a kubeconfig from the k8s-cronjob-mcp ServiceAccount (see scripts/sa-kubeconfig.sh for an example).
By default Kubernetes keeps only the last 3 successful and 1 failed Job per CronJob. That is too little evidence for useful answers: duration trends need at least 4 successful runs, and consecutive failures cannot be counted past 1. For the CronJobs you care about, raise the limits:
spec:
successfulJobsHistoryLimit: 10
failedJobsHistoryLimit: 5get_run_history warns when a CronJob's limits are too low.
Errors are short: what went wrong, the underlying error, what the server is using, and the fix. When a setting fixes it, the error names the variable, the value and the file to put it in. For example:
✗ No permission to read across all namespaces (403)
Error: cronjobs.batch is forbidden: User "you@example.com" cannot list resource "cronjobs" ... at the cluster scope
Using: context dev (pinned) · EKS dev-cluster (eu-west-2) · ~/.kube/config
Fix: Limit the server to namespaces you can read
Check one: kubectl auth can-i list cronjobs -n <namespace>
Set: ALLOWED_NAMESPACES=team-a
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json → "env" of this server (then Cmd+Q and reopen)To check everything step by step:
From your agent: ask it to run check_setup. This is the most accurate check, because it runs with the same environment as your MCP client (which, for desktop apps, is not your shell's environment).
From a terminal: npx -y k8s-cronjob-mcp --check (exit code 0 when everything passes).
If the configuration is broken at startup (for example a wrong K8S_CONTEXT), the server still starts and every tool returns the fix instead of failing silently. The startup summary and any problems are also written to the client's server log (Claude Desktop: ~/Library/Logs/Claude/mcp-server-k8s-cronjobs.log).
Symptom | Cause | Fix |
| MCP clients do not expand | Use the absolute path |
| Cluster name used instead of context name | Use the NAME column of |
| Desktop apps do not load your shell profile, so | Add a |
| You can read only some namespaces | Set |
| Expired login or token | Log in again with your cloud CLI, or create a new ServiceAccount token |
| Cluster down, VPN off, or wrong context | Check connectivity, or change |
The demo uses kind and a repo-local kubeconfig (.kube/). The scripts never read your $KUBECONFIG and refuse to continue unless the context is a kind-* cluster, so no other cluster is touched.
npm run demo:up # kind cluster + demo CronJobs + RBAC
npm run check:rbac # prove the role is read-only
npm run test:integration # runs every tool as the read-only ServiceAccount
npm run demo:downThe demo namespace contains: healthy, flaky (fails randomly), always-failing (the silent failure), paused (suspended), slowing (duration trend) and oom (OOMKilled). Give the CronJobs a few minutes (they fire every 2 minutes), then ask an agent: "Which CronJobs in demo are failing silently, and why?"
npm test # unit tests (no cluster needed)
npm run typecheck
npm run dev # run from source over stdioThe logic lives in src/analysis/ as pure functions over Kubernetes objects, so it is tested with fixtures. src/tools/ is thin glue.
See PUBLISHING.md for the npm release checklist.
Only retained Jobs are visible, so consecutive-failure counts are capped by failedJobsHistoryLimit. A CronJob with a history limit of 0 leaves no evidence; the tools say so rather than reporting it as healthy.
Trends need at least 4 successful runs (see raise history limits). The overrun check works from 1 finished run but is more reliable with more.
list_recent_failures only sees failed Jobs Kubernetes still retains; failures removed by history limits or ttlSecondsAfterFinished are gone.
Check this server's configuration step by step (kubeconfig, context, auth helper, timezone, cluster reachability and read access to each resource) in the exact environment the MCP client runs it in. For every problem it says what is wrong, which environment variable to set and where. Run this first whenever another tool reports a configuration, permission or connection error. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden: it declares 'Read-only', discloses that it runs in the exact environment the MCP client uses, and describes what the output contains ('what is wrong, which environment variable to set and where'). Minor gaps remain (whether a failed check aborts the run, roughly how long it takes), but the behavioral profile is well covered for a no-annotation 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?
Two sentences, front-loaded with the action and the list of checks, followed by the invocation rule. The trailing 'Read-only.' fragment earns its place as a safety signal. No filler.
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?
With no annotations and no output schema, the description still tells the agent what the tool inspects, what its output communicates, and when to call it. Slightly incomplete on failure semantics (does it stop at the first broken step?) and expected cost, but sufficient to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The description correctly implies a parameterless, all-checks-at-once invocation.
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 ('Check this server's configuration') and enumerates the exact checks performed (kubeconfig, context, auth helper, timezone, cluster reachability, read access). This is clearly a diagnostics tool, which is easy to distinguish from the sibling tools that all deal with cronjobs and runs.
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?
Gives an explicit trigger: 'Run this first whenever another tool reports a configuration, permission or connection error.' That is a clear, actionable usage condition. It does not state when NOT to use it (e.g. for logical cronjob failures where config is fine), so it stops short of the 5 bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan CronJobs (one namespace or all) for ones with no successful run in the last N days, even if nothing is erroring right now. Returns the CronJobs needing attention, most urgent first, with the pattern (failing, stalled, never-succeeded), time since last success and last failure. Also catches CronJobs that stopped firing after a recent success, reports CronJobs whose runs outlast their schedule interval as degraded, and flags at-risk ones whose runs use more than 80% of it. Suspended CronJobs are listed briefly. Every result says what time window and runs it is based on.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Flag CronJobs with no success in this many days | |
| limit | No | Max findings to return | |
| namespace | No | Namespace to scan; omit for all namespaces | |
| include_suspended | No | Return suspended CronJobs as full findings instead of a short list |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so well: it discloses result ordering (most urgent first), the classification taxonomy (failing, stalled, never-succeeded), extra behaviors not obvious from the name (stopped-after-success detection, degraded = runtime exceeds interval, at-risk = >80% of interval), how suspended CronJobs are handled, and that each finding states its basis window. This is behavior an agent could not infer from the schema.
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?
Purpose and the key differentiating condition are front-loaded in the first sentence, and subsequent sentences each add a distinct capability rather than restating. It is dense but slightly long, and the closing sentence about window provenance is meta rather than actionable.
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?
There is no output schema and no annotations, yet the description explains what is returned, in what order, with what labels and evidence fields. It never explicitly states the tool is read-only or says anything about errors or truncation via limit, which are the remaining small gaps for a four-parameter diagnostic 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 coverage is 100% and all four parameters are already documented in the schema, so the baseline is 3. The description reinforces the meaning of the days window and namespace scoping and implies suspended handling, but adds no format or syntax detail beyond what the schema states, and never mentions limit.
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?
Names a specific verb and resource (scan CronJobs for no recent success) and immediately pins the differentiating angle: 'even if nothing is erroring right now.' That scope statement cleanly separates it from siblings like list_recent_failures and get_cronjob_status, which surface already-visible errors or a single CronJob's state.
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 phrase 'even if nothing is erroring right now' strongly signals the use case (proactive health sweeps vs reactive error inspection), and 'one namespace or all' hints at scoping choice. It stops short of naming an alternative sibling or stating exclusions (e.g., 'for a specific known failure use get_failure_details'), so it is clear context without explicit routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether a CronJob is running on schedule. Compares its cron schedule against the actual last scheduled run and returns a verdict: on-schedule, late, missed, currently running (or suspended), plus the next run time and whether runs take longer than the schedule interval (overrun: skipped, late or overlapping runs).
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the CronJob | |
| namespace | Yes | Namespace of the CronJob |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does substantial work: it enumerates the verdict values (on-schedule, late, missed, currently running, suspended), promises next run time, and explains the overrun concept (skipped, late, overlapping runs). Gaps remain around failure modes, e.g. what happens if the named CronJob does not exist, and no explicit read-only/safety statement beyond the word 'Check'.
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 sentences with the purpose and scoping front-loaded, followed by a compact enumeration of what is returned. Every clause (verdicts, next run time, overrun) adds information 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?
Since there is no output schema, the description appropriately explains the return shape — verdict categories, next run time, overrun flag. It is nearly complete for a simple two-parameter read tool, with only error/not-found behavior left unaddressed.
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 both parameters (name, namespace), so the schema already explains them fully. The description adds no syntax, format, or lookup-failure semantics for these parameters, so baseline 3 applies.
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 ('Check whether a CronJob is running on schedule') and defines the tool's scope as schedule adherence rather than listing or history. This clearly separates it from siblings such as list_cronjobs, get_run_history, and find_silent_failures.
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?
Usage is implied by the purpose — use it to diagnose whether a job is on schedule, late, or missed — but the description never explicitly says when to pick it over get_run_history or find_silent_failures, nor does it state preconditions. An agent can infer the right context but must do the routing work itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain why a Job failed. Finds its pods, reads container exit state, Kubernetes Events and a log tail (secrets masked), and returns a synthesized cause such as 'container OOMKilled at 340Mi, exit code 137' followed by the evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| job_name | Yes | Name of the failed Job (e.g. from get_run_history) | |
| namespace | Yes | Namespace of the Job | |
| tail_lines | No | Log lines to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the exact evidence gathered (pods, container exit state, Events, log tail) and a security-relevant behavior ('secrets masked'). It stops short of stating read-only safety, permissions needed, or latency/cost.
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?
Front-loaded with the purpose, then the mechanism, then the output shape. Dense but every clause adds distinct information with no filler.
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?
No output schema exists, yet the description explains the return value precisely ('synthesized cause such as ... followed by the evidence'), closing the gap. Nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters (job_name, namespace, tail_lines) are already documented. The description adds nothing beyond the schema about parameter formats or defaults, so baseline 3 applies.
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+resource ('Explain why a Job failed') and enumerates the investigation it performs. Clearly distinguishable from sibling tools like get_run_history (which finds runs) or list_recent_failures.
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?
Usage is implied: use it to diagnose a single failed Job. However, it never states when to prefer it over find_silent_failures, list_recent_failures, or get_run_history, nor any prerequisites (e.g., job must still have pods).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List retained Jobs for a CronJob (newest first) with start time, duration, status and pod exit code, plus a duration trend. Warns when history limits are too short to be useful.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the CronJob | |
| limit | No | Max runs to return | |
| namespace | Yes | Namespace of the CronJob |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden and does disclose non-obvious traits: newest-first ordering, an aggregated duration trend, and a proactive warning when history limits are too short to be meaningful. What it omits is the safety profile (presumably read-only, implied by 'List'/'get') and behavior when a CronJob has zero retained runs.
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 names the resource and the exact payload, with the warning behavior appended in a short clause. No filler and nothing buried.
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?
With no output schema, the description correctly enumerates what comes back and in what order, and it flags the trend and warning side-effects. Only the empty-history case and the read-only nature are left implicit, which is a small gap for a simple listing 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 coverage is 100%, so namespace, name and limit are already fully documented in the schema. The description adds nothing about limit semantics beyond an indirect nod in 'history limits', so the baseline 3 applies.
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 (list retained Jobs for a CronJob) plus the returned fields (start time, duration, status, pod exit code) and ordering (newest first). It is clearly distinct from failure-oriented siblings like get_failure_details or find_silent_failures, though it never names an alternative explicitly.
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?
Usage is only implied: you invoke it when you want the run history of one CronJob. There is no statement of when to prefer list_active_runs or list_recent_failures instead, and no 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 Jobs that are running right now (one namespace or all), including Jobs not created by a CronJob. For each: owning CronJob, start time, how long it has been running, pod counts, deadline, and whether it is taking more than twice its typical duration. Longest-running and overdue Jobs first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max runs to return | |
| namespace | No | Namespace to list; omit for all namespaces |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it enumerates returned fields (owning CronJob, start time, duration, pod counts, deadline), declares sort order ('Longest-running and overdue Jobs first'), and surfaces a derived signal ('more than twice its typical duration'). It omits the implicit read-only nature and any truncation/pagination behavior when limit is hit.
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 sentences, purpose front-loaded in the opening clause, followed by a tight inventory of what each row contains and the ordering rule. No filler or repetition.
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?
There is no output schema, so the description must describe returned values — it does so field by field, including the anomaly indicator and sort order. For a two-parameter read-only list tool, nothing an agent needs to call and interpret it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented in the schema, and the description's 'one namespace or all' only restates the namespace parameter's meaning. No additional semantics such as how limit interacts with the sort order are added, so baseline 3 applies.
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 ('List Jobs that are running right now') plus scope ('one namespace or all') and explicitly extends beyond the sibling CronJob-centric tools by including Jobs not created by a CronJob. An agent can distinguish it from get_run_history or list_cronjobs without opening a schema.
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?
'running right now' clearly delimits this against historical tools, and the parenthetical 'one namespace or all' tells the agent how to scope the call. It does not name an explicit alternative (e.g. get_run_history for completed runs) or state exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Overview of every CronJob (one namespace or all), one compact row each: schedule, effective timezone, health (failing, stalled, never-succeeded, degraded, overrunning, at-risk, healthy, suspended), next run, last scheduled run, last success and last result. Worst first. Use this to see what exists before drilling into one CronJob.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Window for judging 'no recent success' | |
| limit | No | Max rows to return | |
| namespace | No | Namespace to list; omit for all namespaces | |
| include_suspended | No | Include suspended CronJobs in the rows (they are always counted) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does substantial work: it declares the compact-row shape, the worst-first ordering, the full health taxonomy, and the effective timezone concept. It does not state that this is a read-only listing, nor mention truncation at the limit default of 200, which matters for a list tool that could silently cut results.
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 sentences, front-loaded with the resource and scope before the row contents and the usage hint. The long parenthetical health enumeration is dense but each entry is decision-relevant, so little is wasted; the sentence could have been split for scannability.
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?
No output schema exists, and the description compensates by spelling out every returned column, including the ordering rule. Combined with the fully documented input schema, an agent has enough to call it correctly and interpret the response.
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 all four parameters are already documented, and the description only restates the namespace scope ("one namespace or all"). It adds no syntax, format, or interaction detail (e.g., how days interacts with the health verdicts) beyond what the schema provides, so the baseline 3 applies.
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?
Names a specific verb and resource (overview of every CronJob), scopes it (one namespace or all), and enumerates the exact row contents: schedule, effective timezone, health states, next/last run, last success/result. The closing sentence separates it from the drill-down siblings such as get_cronjob_status, so an agent can pick it without opening the schema.
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?
"Use this to see what exists before drilling into one CronJob" gives clear when-to-use context and implicitly routes to the single-CronJob sibling for detail. It also signals triage intent via "Worst first." It stops short of naming an explicit alternative or stating when not 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 Jobs that failed in the last N hours (one namespace or all), newest first, each with a synthesized cause (e.g. OOMKilled, exit code, image pull, deadline) and whether a later run of the same CronJob has succeeded since. Includes Jobs not created by a CronJob. Use get_failure_details for logs and events of one failure.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | Look back this many hours | |
| limit | No | Max failures to inspect and return | |
| namespace | No | Namespace to scan; omit for all namespaces |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses ordering (newest first), the derived fields returned, and the non-obvious scope fact that Jobs not created by a CronJob are included. It omits that `limit` can truncate the inspection set and says nothing about read-only semantics, but 'List' makes the safety profile self-evident.
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 sentences, front-loaded with scope and result shape, then the disambiguation pointer. Every clause carries information — the OOMKilled/exit-code examples and the 'not created by a CronJob' note each prevent a real misread. No filler.
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?
There is no output schema, so the description must carry return semantics, and it does by enumerating the synthesized cause and the later-success flag. For a three-param read tool with full schema coverage this is nearly complete; only truncation behavior under `limit` is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so `hours`, `limit`, and `namespace` are already fully documented, and the description adds nothing new — its 'last N hours' and 'one namespace or all' phrasing merely restates the schema. Baseline 3 is correct; `limit`'s interaction with truncation is not clarified in either place.
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 ('List Jobs that failed in the last N hours'), plus scope (one namespace or all) and exact return contents (synthesized cause, later-CronJob-success flag). It also carves out a niche the agent can distinguish from siblings by naming get_failure_details. This is a precise, non-tautological purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes the agent to get_failure_details for logs/events of a single failure, which is the key adjacent use case. However, it never contrasts with find_silent_failures or get_run_history, both of which plausibly overlap, so the agent must infer which of those to pick. Clear context, but incomplete alternative routing.
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.
v1.0.0check_setupfind_silent_failuresget_cronjob_statusget_failure_detailsget_run_historylist_active_runslist_cronjobslist_recent_failuresScored across 8 tools
Each tool targets a distinct lens (setup diagnostics, single-CronJob schedule status, run history, silent failures, failure forensics, active runs, inventory, recent failures) and descriptions explicitly cross-reference when to use a sibling. Minor overlap remains between find_silent_failures, list_recent_failures and get_cronjob_status, which all surface problem states, and between list_active_runs and the 'currently running' verdict in get_cronjob_status.
All tools follow a verb_noun snake_case pattern (get_cronjob_status, list_recent_failures, find_silent_failures). Small deviations exist: check_setup lacks a resource noun and find_silent_failures inserts an adjective, but the convention is still predictable overall.
Eight tools is well-scoped for a CronJob monitoring server, and each tool earns its place by covering a distinct workflow (setup validation, health triage, drill-down, forensics). No redundant or filler tools are apparent.
For a read-only diagnostics/monitoring domain the lifecycle is well covered: configuration check, inventory, per-object status, history, failure explanation, active runs, and two failure-scan modes. The notable gap is the absence of any mutation tools (suspend/resume, manual trigger), which may be intentional for a strictly read-only server but limits remediation workflows.
Read-only, deterministic AI triage and readiness tools implementing Sophon's published rubrics.
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
Manage CronPulser from an AI agent: HTTP, Runner and TLS jobs, alerts, Runners and run history.
A cron job monitor your AI agent sets up and can ask why a job failed. Free for up to 200 checks.
