Skip to main content
Glama

jobd_events

Read-only

Explain why a job is queued, skipped, or stalled by querying the broker event stream; filter by since window, event type, job ID, project, or source.

Instructions

The broker's event stream — the surface that explains WHY, not just what. /jobs says a job is queued; only this says it has been skipped 400 times because no worker advertises cuda-32gb, or that its dependency was cancelled, or that a watchdog killed it. Filter by since (2h/3d/1w), event type, job_id, project, or source (broker|worker). Use when a job is not doing what you expect and jobd_status alone does not explain it.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "jobd_events"
  }
}

Input Schema

NameRequiredDescriptionDefault
eventNoFilter to one event type. Known types: admission_blocked, auto_preempt, checkpoint_complete, cwd_identity_applied, cwd_refused, cwd_route_warning, dispatch_skip, env_scrubbed, gpu_contention_warning, job_adopted, job_cancelled, job_completed, job_dispatched, job_orphaned, job_resurrected, job_retry_scheduled, job_started, job_submitted, job_uncancelled, jobs_pruned, logs_pruned, preflight_warning, reclaim_suppressed, scheduling_timeout, serialization_warning, stale_scope_sweep, submit_warning, sweep_warning, unknown_project, version_drift, watchdog_fired, worker_offline, worker_registered, worker_shutdown, worker_stale. Hook-ingested events may carry custom names beyond these.
limitNoMax rows, newest-last (1..1000). Narrow with since, event or job_id rather than raising it.
sinceNoRelative window (2h, 3d, 1w) or an ISO-8601 timestamp. Default: all retained.
job_idNoOnly events for this job.
sourceNoWhich side emitted the event.
projectNoOnly events for this project.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv0.5.58
    • changedInput schema / properties / limit / description
      Previous value: -"Max rows, newest-last. Broker clamps to 10000."New value: +"Max rows, newest-last (1..1000). Narrow with since, event or job_id rather than raising it."
    • addedInput schema / properties / limit / maximum
      Added value: +1000
    • addedInput schema / properties / limit / minimum
      Added value: +1
  2. Changed2 schema fields changedv0.5.47
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / event / description
      Previous value: -"Filter to one event type. Known types: admission_blocked, auto_preempt, checkpoint_complete, cwd_identity_applied, cwd_refused, cwd_route_warning, dispatch_skip, env_scrubbed, gpu_contention_warning, job_cancelled, job_completed, job_dispatched, job_orphaned, job_resurrected, job_started, job_submitted, job_uncancelled, jobs_pruned, logs_pruned, preflight_warning, reclaim_suppressed, scheduling_timeout, serialization_warning, stale_scope_sweep, submit_warning, sweep_warning, unknown_project, version_drift, watchdog_fired, worker_offline, worker_registered, worker_shutdown, worker_stale. Hook-ingested events may carry custom names beyond these."New value: +"Filter to one event type. Known types: admission_blocked, auto_preempt, checkpoint_complete, cwd_identity_applied, cwd_refused, cwd_route_warning, dispatch_skip, env_scrubbed, gpu_contention_warning, job_adopted, job_cancelled, job_completed, job_dispatched, job_orphaned, job_resurrected, job_retry_scheduled, job_started, job_submitted, job_uncancelled, jobs_pruned, logs_pruned, preflight_warning, reclaim_suppressed, scheduling_timeout, serialization_warning, stale_scope_sweep, submit_warning, sweep_warning, unknown_project, version_drift, watchdog_fired, worker_offline, worker_registered, worker_shutdown, worker_stale. Hook-ingested events may carry custom names beyond these."
  3. Changed1 schema field changedv0.5.44
    • changedInput schema / properties / event / description
      Previous value: -"Filter to one event type. Known types: admission_blocked, auto_preempt, checkpoint_complete, cwd_refused, dispatch_skip, env_scrubbed, job_cancelled, job_completed, job_dispatched, job_orphaned, job_resurrected, job_started, job_submitted, job_uncancelled, jobs_pruned, logs_pruned, reclaim_suppressed, scheduling_timeout, stale_scope_sweep, submit_warning, sweep_warning, version_drift, watchdog_fired, worker_offline, worker_registered, worker_shutdown, worker_stale. Hook-ingested events may carry custom names beyond these."New value: +"Filter to one event type. Known types: admission_blocked, auto_preempt, checkpoint_complete, cwd_identity_applied, cwd_refused, cwd_route_warning, dispatch_skip, env_scrubbed, gpu_contention_warning, job_cancelled, job_completed, job_dispatched, job_orphaned, job_resurrected, job_started, job_submitted, job_uncancelled, jobs_pruned, logs_pruned, preflight_warning, reclaim_suppressed, scheduling_timeout, serialization_warning, stale_scope_sweep, submit_warning, sweep_warning, unknown_project, version_drift, watchdog_fired, worker_offline, worker_registered, worker_shutdown, worker_stale. Hook-ingested events may carry custom names beyond these."
  4. Addedv0.5.36
  5. Removedv0.5.34
  6. Changed1 schema field changedv0.5.31
    • changedInput schema / properties / event / description
      Previous value: -"Filter to one event type. Known types: admission_blocked, auto_preempt, checkpoint_complete, cwd_refused, dispatch_skip, job_cancelled, job_completed, job_dispatched, job_orphaned, job_resurrected, job_started, job_submitted, job_uncancelled, jobs_pruned, logs_pruned, scheduling_timeout, stale_scope_sweep, submit_warning, sweep_warning, watchdog_fired, worker_offline, worker_registered, worker_shutdown, worker_stale. Hook-ingested events may carry custom names beyond these."New value: +"Filter to one event type. Known types: admission_blocked, auto_preempt, checkpoint_complete, cwd_refused, dispatch_skip, env_scrubbed, job_cancelled, job_completed, job_dispatched, job_orphaned, job_resurrected, job_started, job_submitted, job_uncancelled, jobs_pruned, logs_pruned, scheduling_timeout, stale_scope_sweep, submit_warning, sweep_warning, version_drift, watchdog_fired, worker_offline, worker_registered, worker_shutdown, worker_stale. Hook-ingested events may carry custom names beyond these."
  7. Addedv0.5.26

TDQS

A4/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description's added value is interpretive — that events carry causal narrative and that hook-ingested sources may emit custom names. It does not add operational detail like retention bounds, ordering under filtering, or volume expectations beyond a brief 'newest-last' hint, which is adequate but not rich for a diagnostic tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Three sentences, front-loaded with the differentiator, then concrete failure scenarios, then the routing condition and filter summary. The illustrative examples earn their space by teaching an agent what kinds of signals to look for; no sentence is filler.

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

Completeness4/5

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

For a six-optional-parameter, read-only diagnostic query with no output schema, the definition covers purpose, when to reach for it, filter axes, and the character of the records returned. The one gap is return shape — the description notes row limit and 'newest-last' but does not sketch what an event record contains, which matters since there is no output schema to fall back on.

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

Parameters3/5

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

Schema description coverage is 100%, so every parameter is already documented with examples and enums, establishing a baseline of 3. The description restates the filter dimensions and the '2h/3d/1w' shorthand, which aids scanning but adds little beyond the schema — and notably describes source as 'broker|worker' while the schema enum includes hook and mcp, so the prose is actually narrower than the authoritative field.

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

Purpose5/5

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

The description names the resource (the broker's event stream) and its distinctive purpose — explaining causality rather than state — with concrete contrasting examples ('skipped 400 times because no worker advertises cuda-32gb', 'watchdog killed it'). It explicitly distinguishes itself from the state-oriented siblings by opening with 'jobd_status says a job is queued; only this says...', so an agent can route without opening any schema.

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

Usage Guidelines4/5

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

It gives a clear triggering condition — 'Use when a job is not doing what you expect and jobd_status alone does not explain it' — which names the sibling to try first and the point at which to escalate here. It stops short of explicit exclusions (e.g. 'do not use this to list jobs; use jobd_list'), so it is strong context rather than full when/when-not routing.

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