Skip to main content
Glama

Get worklist status

well_get_worklist_status
Read-only

Ask whether a repair gate is still OPEN, without drawing its card.

Call this BEFORE the worklist read whenever you are checking rather than repairing — the first pass of a gate, and every re-check after the reader has cleared one. open: false means the gate is settled: carry on, and call nothing else.

Only call the worklist read when this says open: true. Those reads draw a card on every call, empty included, so reaching for one to find out whether there is anything to do puts a picker with no rows and a dead button in front of the reader. The tool that draws each card comes back as card_tool.

WORKLISTS, and the scope each one needs:

  • accounts_needing_company — the accounts with no company attached, or whose ownership is still unknown. No scope.

  • uncategorized_window — the transactions in a window carrying no category. Needs from (inclusive) and to (EXCLUSIVE), both YYYY-MM-DD.

  • unposted_transactions — a period's categorized rows still missing the ledger account they would post to. Needs fiscal_year and fiscal_period.

  • invoice_sources_for_pick — how many of the vendors the user picked on the missing-invoices card carry a connector that can bring an invoice in. No scope: the pick is on this session's own lane. Ask it BEFORE any well_list_connectors({ from_selection: true }) call, and make that call only when this answers above zero — a pick with no invoice source behind it draws a picker with no rows and a dead button.

  • counterparties_to_categorize — the counterparties whose invoices the named months are still missing and that carry no industry category. Needs periods, the same [{ calendar_year, calendar_month }] list the card takes.

A scope field the named worklist needs is REQUIRED. Omit one and this refuses: a gate reported clear over the wrong window cannot be told from one that is genuinely clear, and the figure behind it would be computed on that.

success: false means the gate is UNKNOWN, not clear. open is ABSENT on that path, so a failed read can never be mistaken for a settled worklist. Retry once; on a second failure say the gate could not be read and stop, rather than computing a figure on evidence you never obtained.

Most worklists report no COUNT. One row answers "is it open", and the count of what is left comes from the worklist read itself — which you are about to call anyway when the gate is open. Two kinds are the exception and carry count. invoice_sources_for_pick reads its whole set by id in one go, never paged, so the number comes free. counterparties_to_categorize reads the whole month population rather than one row, so the number is already in hand, and it is the same number the card reports as uncategorized_count.

COST: counterparties_to_categorize reads each named month's spend — the same reads its card makes, and a scope with work left in it pays for them TWICE, once here and once when the card draws. A clean scope pays once and skips the card entirely, which is what the check buys. Probe the months the user actually named, not a whole year "to be safe".

When the token authorizes one workspace, call this directly — no other tool call is needed first. When it authorizes several, this read will not guess which one you mean: pass workspace_id on the call.

That holds for every gate but two. invoice_sources_for_pick and counterparties_to_categorize follow their cards instead: well_list_connectors and well_list_counterparties both answer from the token's primary workspace when you name none, so those gates answer from the same one. A probe that refused where its card answers would be describing a different workspace from the card it stands in for. The result names the workspace that answered.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
toNo`uncategorized_window` only: the day AFTER the window's last, exclusive.
fromNo`uncategorized_window` only: the window's first day, inclusive.
periodsNo`counterparties_to_categorize` only: the calendar months to check, the same list the card takes. Every month must have ended.
worklistYesWhich repair gate to check. Each one names its own required scope in this tool's description.
fiscal_yearNo`unposted_transactions` only: the period's fiscal year.
workspace_idNoTarget workspace. Omit when the token authorizes one workspace. Required when it authorizes several: this read reports one workspace's own figures and will not choose which.
fiscal_periodNo`unposted_transactions` only: the fiscal period, 1-12 for a month; 13 is the adjustment period and resolves to no rows.
conversation_idNoThe conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
openNoWhether the worklist still holds a row. Absent when `success` is false — an unknown gate, not a clear one.
countNoHow many rows the gate still holds. Carried only by the kinds whose read counts the whole set (`invoice_sources_for_pick`, and `counterparties_to_categorize` where it equals the card's `uncategorized_count`); absent on the kinds answered one row at a time, and absent whenever `success` is false.
errorNo
successYes
worklistYesThe gate that was checked, echoed back.
card_toolYesThe tool that draws this worklist's repair card. Call it only when `open` is true.
conversation_idNoThe conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.
resolved_workspaceNoThe workspace that answered, when the caller named none and the token authorizes several.
conversation_id_noteNoPresent only when the server opened a fresh lane, stating that no choice recorded earlier was read.
conversation_id_sourceNoWhere the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / conversation_id
      Added value: +{
      +  "description": "The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / conversation_id
      Added value: +{
      +  "description": "The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / conversation_id_note
      Added value: +{
      +  "description": "Present only when the server opened a fresh lane, stating that no choice recorded earlier was read.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / conversation_id_source
      Added value: +{
      +  "description": "Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened.",
      +  "enum": [
      +    "host_meta",
      +    "argument",
      +    "minted"
      +  ],
      +  "type": "string"
      +}
  2. Changed3 schema fields changed
    • addedInput schema / properties / periods
      Added value: +{
      +  "description": "`counterparties_to_categorize` only: the calendar months to check, the same list the card takes. Every month must have ended.",
      +  "items": {
      +    "additionalProperties": false,
      +    "properties": {
      +      "calendar_month": {
      +        "description": "Calendar month, 1 = January … 12 = December.",
      +        "maximum": 12,
      +        "minimum": 1,
      +        "type": "integer"
      +      },
      +      "calendar_year": {
      +        "description": "Calendar year, e.g. 2026.",
      +        "maximum": 2100,
      +        "minimum": 2000,
      +        "type": "integer"
      +      }
      +    },
      +    "required": [
      +      "calendar_year",
      +      "calendar_month"
      +    ],
      +    "type": "object"
      +  },
      +  "maxItems": 12,
      +  "minItems": 1,
      +  "type": "array"
      +}
    • changedInput schema / properties / worklist / enum
      Previous value: -[
      -  "accounts_needing_company",
      -  "uncategorized_window",
      -  "unposted_transactions"
      -]New value: +[
      +  "accounts_needing_company",
      +  "uncategorized_window",
      +  "unposted_transactions",
      +  "invoice_sources_for_pick",
      +  "counterparties_to_categorize"
      +]
    • addedOutput schema / properties / count
      Added value: +{
      +  "description": "How many rows the gate still holds. Carried only by the kinds whose read counts the whole set (`invoice_sources_for_pick`, and `counterparties_to_categorize` where it equals the card's `uncategorized_count`); absent on the kinds answered one row at a time, and absent whenever `success` is false.",
      +  "maximum": 9007199254740991,
      +  "minimum": -9007199254740991,
      +  "type": "integer"
      +}
  3. Changed2 schema fields changed
    • changedInput schema / properties / fiscal_period / description
      Previous value: -"`unposted_transactions` only: the period's fiscal period, 1-12."New value: +"`unposted_transactions` only: the fiscal period, 1-12 for a month; 13 is the adjustment period and resolves to no rows."
    • changedInput schema / properties / fiscal_period / maximum
      Previous value: -12New value: +13
  4. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations already mark this as read-only and non-destructive, and the description adds substantial behavioral context beyond that: it does not draw a card, open: false means settled, success: false means UNKNOWN with open absent, two worklists return count, and counterparties_to_categorize pays for month spend twice. No contradiction with annotations appears.

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?

The description is long but well-organized with bold section headers and front-loaded key guidance. Nearly every sentence contributes, though there is some repetition (e.g., 'a picker with no rows and a dead button' appears twice) and a few rhetorical asides that could be tightened without losing meaning.

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?

Despite having an output schema, the description covers everything an agent needs to call this correctly: the exact gate semantics, ordering dependencies, scope requirements, failure behavior, cost implications, workspace resolution, and conversation_id propagation. It is complete for a tool of this complexity.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by mapping each worklist to its required scope fields, stating that omitted required scope causes a refusal, and clarifying workspace_id and conversation_id handling. It reinforces and extends the schema without replacing it.

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 opens with a specific, unambiguous statement: 'Ask whether a repair gate is still OPEN, without drawing its card.' It names the exact resource (repair gate/worklist status) and clearly distinguishes itself from the worklist-read siblings by framing it as a predicate check. It also enumerates the worklists it covers and contrasts with the reads that draw cards.

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?

The description gives explicit sequencing guidance: call this BEFORE the worklist read when checking rather than repairing, and only call the worklist read when this returns open: true. It also names alternatives like well_list_connectors and well_list_counterparties, specifies workspace_id behavior for multi-workspace tokens, and gives retry/stop instructions on failure. This is unusually strong usage guidance.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources