Skip to main content
Glama
Sign In
bantamkit

bantamkit

by Ink01101011
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Shift work: status

shiftwork_status
Read-only

Read a shift-work checkpoint to report unit counts by status, the current plan cursor, pending handoff questions, and the last history entry before resuming a job or locating its state.

Instructions

Shift-work status: where ONE checkpoint file stands — units counted by status, the unit plan.cursor points at, how many handoff.open_questions are waiting, and the last history entry. Call it first when resuming a job or answering 'where is job X'; it is the cheap read before any clock-in. It does not say WHICH units may run now — that is shiftwork_plan, the dependency batches — and it says nothing about the server itself, which is bantamkit_status. Every fact is read from the checkpoint on this call, nothing is cached, and a checkpoint that is missing, not valid JSON or failing the checkpoint schema answers {"result": "error", "reason": ""} instead of a partial summary — the same refusals shiftwork_plan and shiftwork_clock_in give for that file. With search, it also returns the lines of jobs Retention archived under the checkpoint's .shiftwork/archive/ that hold every word of the query. Opens only the checkpoint (and that archive directory when search is given); writes nothing, not even the log shiftwork_clock_in appends to.

Input Schema

NameRequiredDescriptionDefault
searchNoAlso search jobs Retention archived under this checkpoint's .shiftwork/archive/: every line holding all the query's words, as {job, file, line}.
checkpointYesPath to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json.

Output Schema

NameRequiredDescriptionDefault
unitsNoUnit count per status, keys among todo, in_progress, done, blocked, dropped; a status no unit holds is absent.
cursorNoThe unit id plan.cursor points at.
reasonNoWith result `error`: one sentence saying why the call was refused.
resultYes`status` on success; `error` when the checkpoint could not be read or failed the schema, with `reason`.
searchNoOnly when `search` was given: every archived line holding all its words, as {job, file, line}.
last_historyNoThe newest entry of the 5-entry history ring ({unit, outcome, notes?, ...}), or null when the ring is empty.
open_questionsNoHow many handoff.open_questions are waiting; non-zero means the next clock-in escalates.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.37.1
    • addedInput schema / properties / search
      Added value: +{
+  "description": "Also search jobs Retention archived under this checkpoint's .shiftwork/archive/: every line holding all the query's words, as {job, file, line}.",
+  "type": "string"
+}
    • addedOutput schema / properties / search
      Added value: +{
+  "description": "Only when `search` was given: every archived line holding all its words, as {job, file, line}.",
+  "items": {
+    "properties": {
+      "file": {
+        "description": "Path of the archived file, relative to the job.",
+        "type": "string"
+      },
+      "job": {
+        "description": "The archived job the line belongs to.",
+        "type": "string"
+      },
+      "line": {
+        "description": "1-based line number within that file.",
+        "type": "integer"
+      }
+    },
+    "type": "object"
+  },
+  "type": "array"
+}
  2. Changed3 schema fields changedv0.36.2
    • addedInput schema / properties / checkpoint / description
      Added value: +"Path to the shift-work checkpoint JSON file (by convention .shiftwork/checkpoint.json in the repo the job works on), absolute or relative to the server's working directory. The same file shiftwork_plan, shiftwork_clock_in and shiftwork_clock_out take; it must validate against assets/schemas/shiftwork-checkpoint.json."
    • addedOutput schema / properties
      Added value: +{
+  "cursor": {
+    "description": "The unit id plan.cursor points at.",
+    "type": "string"
+  },
+  "last_history": {
+    "anyOf": [
+      {
+        "type": "object"
+      },
+      {
+        "type": "null"
+      }
+    ],
+    "description": "The newest entry of the 5-entry history ring ({unit, outcome, notes?, ...}), or null when the ring is empty."
+  },
+  "open_questions": {
+    "description": "How many handoff.open_questions are waiting; non-zero means the next clock-in escalates.",
+    "type": "integer"
+  },
+  "reason": {
+    "description": "With result `error`: one sentence saying why the call was refused.",
+    "type": "string"
+  },
+  "result": {
+    "description": "`status` on success; `error` when the checkpoint could not be read or failed the schema, with `reason`.",
+    "type": "string"
+  },
+  "units": {
+    "additionalProperties": {
+      "type": "integer"
+    },
+    "description": "Unit count per status, keys among todo, in_progress, done, blocked, dropped; a status no unit holds is absent.",
+    "type": "object"
+  }
+}
    • addedOutput schema / required
      Added value: +[
+  "result"
+]
  3. First observedv0.36.0

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnly/openWorld annotations, it discloses that every fact is read fresh on this call (no caching), that invalid or missing checkpoints return a structured {"result": "error", "reason": ...} instead of a partial summary, and that it opens only the checkpoint (plus the archive dir when search is given) and writes nothing, not even a log line.

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

Conciseness4/5

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

Content is front-loaded with purpose, then usage, exclusions, behavior, and side effects, and nearly every clause carries information. It is dense and long-winded in places (the error/refusal sentence and the search aside), slightly hurting scanability, but nothing is filler.

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

Completeness5/5

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

For a read-only status tool with an output schema, the description covers everything an agent needs: what is returned, when to call it, which siblings to use instead, failure semantics, and side effects. No material gap remains.

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 coverage is 100%, so both parameters are already fully documented in the schema. The description's search sentence largely restates the schema text, adding only the note about opening the archive directory; with the schema doing the heavy lifting, baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource ('where ONE checkpoint file stands') and enumerates the exact facts returned (units by status, plan.cursor unit, handoff.open_questions count, last history entry). It explicitly demarcates itself from siblings: shiftwork_plan for runnable units and bantamkit_status for the server.

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

Usage Guidelines5/5

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

Gives an explicit trigger ('Call it first when resuming a job or answering where is job X; it is the cheap read before any clock-in') plus explicit exclusions routed to named alternatives. Nothing about when to pick this versus shiftwork_plan or bantamkit_status is left to inference.

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

Deploy Server

Other Tools