node-autotask 0.37.1 → 0.39.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.39.0] - Unreleased
+
+Minor: the plan hash moves `2dab3980...` (0.38.0) -> `9bb87de7bcbda60f6c44955dba52b8e61e9c5547750ea8acacfcb6f261d7734f` (a new `field-semantics` caveat on `time_entries.query` / `time_entries.get`), so the MCP server must re-pin.
+
+### Changed
+- **#282: label siblings are never missing for a keyed field.** When a labelled field is present in a query row, aggregate group key or fetched record, its sibling is now always there: `<fk>Name` (`contractIDName`, `assignedResourceIDName`, ...) and the deprecated `assignedResourceName` alias are `null` when the id is null, 0 or unresolved, and `<picklist>Label` (`statusLabel`) is `null` when the value is null. Previously these keys were omitted, which broke clients that read them unconditionally. Non-null values are unchanged; `*Name` values keep the 200-char cap and the `<untrusted_content>` wrapping. The `assignedResourceName` alias stays in 0.39.0 (its removal, announced for this minor, is deferred).
+### Added
+- **#282: `operations.fieldCatalog` compact rows and a size cap.** Measured live from the SDK (no client in between): a `tickets` result is 19,816 bytes full, 137,355 bytes with `labels: true` (what the MCP server sends for a one-resource call) and 11,057 bytes with `compact: true`; `time_entries` is 9,218 / 11,339 / 5,320 bytes. So the >96 KB payload clients saw cut off is the SDK's own full labelled result.
+  - `compact: true` serves each field row as `{ name, type, isPickList, isReference, udf }`. Picklist values ride a compact row only with `labels: true` and a `fields` filter. The row name lists (`required`, `readOnly`, `queryable`, `picklistFields`) are kept.
+  - `maxBytes` (integer >= 4096) caps the UTF-8 JSON size. Over it, field rows are dropped from the end (udf rows first, then fields rows, last resource first; the name lists only if the field rows alone cannot fit), and the result carries `truncated: true` plus `truncation: { reason: 'maxBytes', maxBytes, fullBytes, omitted: [{ resource, kind, count }], note }`. The result is always valid JSON and never over the cap: when the envelope alone cannot fit (many resources under a small cap), the call is refused with `CONFIG_ERROR`. The cost is linear in the result size: each dropped entry is measured once.
+  - Defaults are unchanged (full rows, no cap), so existing SDK callers see the same output. The SDK cannot tell an MCP caller apart, and the server's describe enrichment reads the full rows, so the compact default belongs in the server: pass `compact: true` (and a `maxBytes`) on model-facing calls.
+  - Types: `FieldCatalogResult` / `FieldCatalogRow` take the field-row type as a parameter (default the full row; `fieldCatalog(client, { compact: true })` is typed with `FieldCatalogCompactFieldRow`). `FieldCatalogResult.truncated` is now `boolean` (was the literal `false`); over-cap wire requests are still refused, never truncated. New exports: `FieldCatalogCompactFieldRow`, `FieldCatalogTruncation`, `FieldCatalogTrimKind`, `MIN_FIELD_CATALOG_MAX_BYTES`.
+- **#282: `hoursWorked` vs `hoursToBill` in the registry.** `time_entries.query` and `time_entries.get` carry a `field-semantics` caveat (a new caveat kind, `fields` required) whose note a server can quote: `hoursWorked` is the time worked (effort, utilisation); `hoursToBill` is the vendor-derived billing quantity (read-only: `hoursWorked` plus `offsetHours`, rounded to two decimals), stays populated on `isNonBillable` entries, and can differ from `hoursWorked` on the same entry.
+
+## [0.38.0] - Unreleased
+
+Minor: query/aggregate/count answer "company X time in a window, with labels" in 1-3 calls using existing operations. The plan hash changes (registry text), so the MCP server must re-pin.
+
+### Added
+- **#274: `in` / `notIn` accept a comma-separated string.** `value: "1,2,3"` is split on commas, trimmed, empty tokens dropped, and canonical number tokens become numbers (`"007"` stays a string; `udf: true` values stay strings), producing the same wire filter as `[1, 2, 3]`. Applies everywhere filters are built (query, count, aggregate, latest walks, the field-name pre-check). A string with no tokens is refused pre-request with `AutotaskConfigError`. Array values are unchanged. Filter grammar text in the registry, README and `docs/API.md` updated.
+- **#275: relation filters.** On a resource with a `ticketID` / `taskID` / `projectID` foreign key, a condition on `ticket.<field>`, `task.<field>` or `project.<field>` is resolved to `<relation>ID in [ids]` (one parent read of at most 300 ids per relation; per leaf inside an `or`). Works in `queryBounded` / the invoke `query` op, `count` and `operations.aggregate`, so `time_entries` can be scoped by company: `[{ field: 'ticket.companyID', op: 'eq', value: 123 }, { field: 'dateWorked', op: 'gte', value: '2026-10-01' }]`. No parent match returns an empty result (`relationNote`, `count` 0) without the child call; more than 300 parents is a typed `AutotaskConfigError`; relation field names are checked against the parent's field set pre-request. New additive result field `BoundedQueryResult.relationNote` / `AggregateResult.relationNote`. `companies.unbilledWork` now uses the shared join-set helper (`capJoinSet`, cap 300), no behaviour change.
+- **#276: default label siblings on query, aggregate and fetch.** The invoke `<resource>.query` rows, `operations.aggregate` group keys and `operations.fetchMany` / `fetchByIds` records now carry `<picklist>Label` (e.g. `statusLabel`) and `<fk>Name` siblings (`companyIDName`, `contractIDName`, `ticketIDName` = "<number> <title>", `roleIDName`, `billingCodeIDName`, and `resourceIDName` / `assignedResourceIDName` / every `*ResourceIDName`) through `resolveCompositeNames` (now also resolving companies and tickets, and any resource's picklists). Default on; `names: false` opts out per call (new key on the query bag, aggregate opts and fetch opts). Cold reads stay capped at 20 per call: capped ids get a null name and the result carries `names: { truncated, capped, note, reasons? }`. Warm caches cost zero vendor calls. `*Name` values are vendor free text, so they are capped at 200 chars (noteChars marker) and wrapped in `<untrusted_content>` markers by the SDK; picklist `*Label` values stay raw. `assignedResourceName` is written as a deprecated alias of `assignedResourceIDName` for this minor release. Worst-case row growth (full model, every FK set): tickets ~50%, time_entries ~77% (see `docs/API.md` §11.27). Behaviour change: callers that compare whole rows should pass `names: false`.
+- **#277: catalog discoverability.** `MCP_TOOL_CATALOG.json` rows for the repeated date-window helpers (`today`, `yesterday`, `last24h`, `last7/14/30/90`, `lastFullWeek/Fortnight/Month/Quarter`, `customRange` on `time_entries`, `billing_items`, `invoices`, plus `time_entries.dateWorkedWindow`: 37 rows) carry `hidden: true` + `hiddenReason`; they stay in the catalog and callable by exact key. `operations.aggregate`'s purpose gains discovery text (totals, sums, counts, hours per ticket / resource / company / contract / month). The `autotask_catalog` meta-tool data documents `q` and `includeHidden`, and the reference server (`examples/mcp/rank.ts`) ships the ranker: BM25 x squared query-term coverage, rows under half the terms dropped, tool-served rows x1.5, hidden rows excluded unless asked, exact key always resolves. Golden test: "aggregate time entries hours grouped by ticket resource" ranks `operations.aggregate` first (7 rows, previously 518 `time_entries.*` rows without aggregate in the top 20).
+### Deprecated
+- **#278: `time_entries.recentTickets`** (removed in the next minor; works unchanged until then). It is a subset of `operations.aggregate('time_entries.query', [resourceID eq R, dateWorked window, optional ticket.companyID eq C], { groupBy: ['ticketID'], sum: ['hoursWorked'] })`, whose group keys now carry `ticketIDName`. The registry purpose / preferredWhen (what describe shows) open with the deprecation and the replacement call, the generated method carries `@deprecated`, the catalog row carries `deprecated: true`, and `docs/API.md` has the worked example.
+### Changed
+- Label siblings are on by default (#276): code that compares whole query / fetch rows or aggregate keys should pass `names: false`.
+### Fixed
+- **#280: `operations.aggregate` checks filter field names.** Filter, `groupBy` and `sum` names now go through the same field-name check as the invoke query/count bags (one shared `findUnknownFieldNames`), against the vendored spec plus the plan-pinned live-only fields. An unknown name is a typed `CONFIG_ERROR` in the one-round problem list, with no vendor request (no metadata read either). `udf: true` conditions are exempt; relation leaves (`ticket.<field>`) are checked against the parent's field set by the relation rewrite. A bucketed `groupBy` entry with an unknown base is quoted as given (`"nope@year": "nope"`).
+- **#281: the `query()` iterator resolves relation filters and labels rows.** `client.<resource>.query()` (the iterator behind the MCP server's `output_path`) now runs the same relation rewrite as `queryBounded` / `count` (`ticket.<field>` etc. become `<relation>ID in [ids]`; no parent match yields nothing with no child call; more than 300 parents is the typed error), and adds the default label siblings per page through the same `labelRows` (new `QueryParams.names`, `false` opts out; the cold-read cap of 20 applies per page and capped ids get a null `*Name`, since an iterator has no `names` summary). `queryAll` also resolves relation filters (raw rows, no labels). As a backstop, `HttpClient.request` refuses any `/query` call whose filter still carries a dotted non-UDF field, so no path can send an unresolved relation filter to the vendor. `operations.revenueRollup`'s internal walks pass `names: false` (no change to its vendor-call budget).
+
 ## [0.37.1] - 2026-10-29
 Patch: circuit-breaker probe-settlement fixes only; the plan hash is unchanged (`5cd6c667...`), so consumers need no re-pin for the plan.
 ### Fixed

package/MCP_TOOL_CATALOG.json

@@ -1,12 +1,12 @@
 {
   "generatedBy": "scripts/build-tool-catalog.mjs",
-  "generatedAt": "2026-10-28T12:58:12.762Z",
-  "planHash": "5cd6c6679384651e7f67a0135915bcc031ef542640d9ebb6992b729ca42efe37",
+  "generatedAt": "2026-10-29T10:47:35.516Z",
+  "planHash": "9bb87de7bcbda60f6c44955dba52b8e61e9c5547750ea8acacfcb6f261d7734f",
   "metaTools": [
     {
       "name": "autotask_catalog",
       "title": "Discover Operations (Catalog)",
-      "description": "List the operations the SDK implements with tool/effect/dry-run/confirmation/required-args rows; bounded (limit default 40, max 500, tier + effect filters); the tool list on the server is a SUBSET — this is how a capability without a tool of its own is found. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
+      "description": "List the operations the SDK implements with tool/effect/dry-run/confirmation/required-args rows; bounded (limit default 40, max 500, tier + effect filters); the tool list on the server is a SUBSET — this is how a capability without a tool of its own is found. Rows flagged hidden (the repeated date-window helpers) are left out of default results and stay callable by exact key. The argument set is CLOSED at the top level: an unknown argument is refused before any request, with a typed error naming the key and the valid keys.",
       "input": {
         "limit": {
           "type": "number",
@@ -18,6 +18,14 @@
         },
         "effect": {
           "type": "read | write | destructive"
+        },
+        "q": {
+          "type": "string",
+          "note": "ranked search (most query words matched, tool-served rows first)"
+        },
+        "includeHidden": {
+          "type": "boolean",
+          "default": false
         }
       },
       "annotations": {
@@ -664,7 +672,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.get",
@@ -751,7 +761,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.last24h",
@@ -768,7 +780,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.last30",
@@ -785,7 +799,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.last7",
@@ -802,7 +818,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.last90",
@@ -819,7 +837,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.lastFullFortnight",
@@ -836,7 +856,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.lastFullMonth",
@@ -853,7 +875,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.lastFullQuarter",
@@ -870,7 +894,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.lastFullWeek",
@@ -887,7 +913,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.query",
@@ -940,7 +968,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "billing_items.update",
@@ -977,7 +1007,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "change_request_links.count",
@@ -11519,7 +11551,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.dateWorkedWindow",
@@ -11539,7 +11573,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.delete",
@@ -11679,7 +11715,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.last24h",
@@ -11696,7 +11734,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.last30",
@@ -11713,7 +11753,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.last7",
@@ -11730,7 +11772,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.last90",
@@ -11747,7 +11791,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.lastFullFortnight",
@@ -11764,7 +11810,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.lastFullMonth",
@@ -11781,7 +11829,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.lastFullQuarter",
@@ -11798,7 +11848,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.lastFullWeek",
@@ -11815,7 +11867,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.moveToTicket",
@@ -11878,8 +11932,8 @@
       "operation": "time_entries.recentTickets",
       "core": false,
       "tool": "autotask_timeEntry_recent_tickets",
-      "purpose": "List the distinct tickets a resource logged time against in an inclusive dateWorked window, with entry count, total hours, last worked date and the ticket's number, title, status, assignee and company.",
-      "preferredWhen": "Finding the ticket a piece of work was logged against, or which tickets a resource has been working on lately. Not for a total over many groups (operations.aggregate) or the raw entries (time_entries.dateWorkedWindow).",
+      "purpose": "DEPRECATED (since 0.38.0; removed in the next minor; still works): use operations.aggregate('time_entries.query', [{field:'resourceID',op:'eq',value:R},{field:'dateWorked',op:'gte',value:FROM},{field:'dateWorked',op:'lte',value:TO}], {groupBy:['ticketID'], sum:['hoursWorked']}) instead — the group keys carry ticketIDName (ticket number + title); add {field:'ticket.companyID',op:'eq',value:C} for one company. List the distinct tickets a resource logged time against in an inclusive dateWorked window, with entry count, total hours, last worked date and the ticket's number, title, status, assignee and company.",
+      "preferredWhen": "Deprecated: prefer operations.aggregate grouped by ticketID (see purpose). Kept for existing callers until the next minor.",
       "backingOperation": "time_entries.recentTickets",
       "effect": "read",
       "dryRunFirst": false,
@@ -11893,7 +11947,8 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "deprecated": true
     },
     {
       "operation": "time_entries.resolve",
@@ -11929,7 +11984,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entries.update",
@@ -11966,7 +12023,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "time_entry_attachments.count",
@@ -18508,7 +18567,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.get",
@@ -18595,7 +18656,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.last24h",
@@ -18612,7 +18675,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.last30",
@@ -18629,7 +18694,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.last7",
@@ -18646,7 +18713,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.last90",
@@ -18663,7 +18732,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.lastFullFortnight",
@@ -18680,7 +18751,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.lastFullMonth",
@@ -18697,7 +18770,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.lastFullQuarter",
@@ -18714,7 +18789,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.lastFullWeek",
@@ -18731,7 +18808,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.markupHtml",
@@ -18841,7 +18920,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "invoices.update",
@@ -18878,7 +18959,9 @@
       "reachable": true,
       "reach": "dedicated tool",
       "reachReason": null,
-      "boundedAlternative": null
+      "boundedAlternative": null,
+      "hidden": true,
+      "hiddenReason": "date-window helper (one date field, no company/contract scope): hidden from default results — prefer <resource>.query with a date filter or operations.aggregate; still callable by exact key"
     },
     {
       "operation": "opportunities.count",
@@ -23252,7 +23335,7 @@
       "operation": "operations.aggregate",
       "core": false,
       "tool": "autotask_aggregate",
-      "purpose": "Fold any query surface into groups/sums/totals in one bounded call — or count it with the vendor count endpoint when no folding is needed — with blind-surface and truncation honesty (caps documented: the walk scans at most 2500 rows and top keeps at most 100 groups — a truncated aggregate is a PARTIAL answer, never a tenant-wide total); date fields bucket via the closed groupBy suffix <field>@month | @week | @year (ISO labels, UTC-anchored)",
+      "purpose": "Fold any query surface into groups/sums/totals in one bounded call — or count it with the vendor count endpoint when no folding is needed — with blind-surface and truncation honesty (caps documented: the walk scans at most 2500 rows and top keeps at most 100 groups — a truncated aggregate is a PARTIAL answer, never a tenant-wide total); date fields bucket via the closed groupBy suffix <field>@month | @week | @year (ISO labels, UTC-anchored). Use it for totals, sums, counts and hours per ticket, resource, company, contract or month (group by any field), e.g. time entries hours grouped by ticket and resource",
       "preferredWhen": "For existence checks and totals over any queryable table (count mode is one call vs a 50k-char page); group-by/sum folds the vendor has no endpoint for; a targeted read is cheaper when you need the rows",
       "backingOperation": "operations.aggregate",
       "effect": "read",