node-autotask 0.60.1 → 0.62.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. package/CHANGELOG.md +30 -0
  2. package/MCP_TOOL_CATALOG.json +298 -9
  3. package/README.md +3 -3
  4. package/capabilities.json +1047 -7
  5. package/dist/capabilities-data.js +1046 -6
  6. package/dist/capabilities.cjs +4 -4
  7. package/dist/capabilities.js +1 -1
  8. package/dist/{chunk-XYWSPKCN.cjs → chunk-LFEMZVOV.cjs} +33 -31
  9. package/dist/{chunk-2GPQ55O6.js → chunk-O6SYTORL.js} +4 -2
  10. package/dist/{chunk-XP43NERF.cjs → chunk-ODPM4YVG.cjs} +3 -3
  11. package/dist/{chunk-VN3OZHC7.cjs → chunk-QHM6ROAE.cjs} +174 -174
  12. package/dist/{chunk-XUPVX5MQ.js → chunk-S4YR3RLJ.js} +2 -2
  13. package/dist/{chunk-Y2SR6D2D.js → chunk-TGCFJCWN.js} +237 -8
  14. package/dist/{chunk-MYLSBOZI.cjs → chunk-VDYUG6RK.cjs} +242 -13
  15. package/dist/{chunk-K722F7EM.js → chunk-XJNNCMBS.js} +3 -3
  16. package/dist/{index-BmaFIj42.d.cts → index-BXJOPL7w.d.cts} +4 -2
  17. package/dist/{index-cAntv7_A.d.ts → index-C4wZRw9N.d.ts} +4 -2
  18. package/dist/{index-D6bAO4ZV.d.cts → index-COQEG55Q.d.cts} +90 -1
  19. package/dist/{index-D6bAO4ZV.d.ts → index-COQEG55Q.d.ts} +90 -1
  20. package/dist/index.cjs +84 -84
  21. package/dist/index.d.cts +3 -3
  22. package/dist/index.d.ts +3 -3
  23. package/dist/index.js +5 -5
  24. package/dist/operations/index.cjs +50 -50
  25. package/dist/operations/index.d.cts +4 -4
  26. package/dist/operations/index.d.ts +4 -4
  27. package/dist/operations/index.js +2 -2
  28. package/dist/pool.cjs +8 -8
  29. package/dist/pool.d.cts +1 -1
  30. package/dist/pool.d.ts +1 -1
  31. package/dist/pool.js +4 -4
  32. package/dist/resources/index.cjs +27 -27
  33. package/dist/resources/index.d.cts +2 -2
  34. package/dist/resources/index.d.ts +2 -2
  35. package/dist/resources/index.js +3 -3
  36. package/dist/types/index.d.cts +1 -1
  37. package/dist/types/index.d.ts +1 -1
  38. package/docs/API.md +4 -2
  39. package/docs/VENDOR-QUIRKS.md +18 -3
  40. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.62.0] - 2026-11-12
11
+
12
+ ### Fixed
13
+
14
+ - The unfiltered `count` on `user_defined_field_definitions` and `user_defined_field_list_items` is now pinned as an
15
+ `unfiltered-blind` surface (#432). On the verified zone it answers 0 even though data exists, and 0.61.0 served that
16
+ 0 as a plain number. It now carries the typed `blindSurface` sentinel, and a `latest` read no longer returns an
17
+ empty answer from it. It walks the unfiltered query, which is not blind. A filtered count of 0 stays a true zero.
18
+ Only `count` is pinned, so a UDF `get` miss still reports `not-found`. In the capabilities gate, a count-only pin
19
+ binds its reachability row's kind only when that row is not data-full. The UDF rows are data-full.
20
+
21
+ ## [0.61.0] - 2026-11-11
22
+
23
+ ### Added
24
+
25
+ - UDF definition and picklist-value maintenance is now exposed as planned resources (#428):
26
+ `user_defined_field_definitions` (the company UDF definition table: query, count, get, create, update, plus
27
+ the entity/field/UDF info trio) and `user_defined_field_list_items` (the picklist values of a `List` UDF,
28
+ parent-scoped under the definition id: scoped create/update/get, global query/count). The vendor REST API
29
+ defines no DELETE for either entity, so removal is soft via `isActive`; writes go to the parent-scoped
30
+ `/V1.0/UserDefinedFields/{parentId}/ListItems` URL while reads also work on the standalone
31
+ `/V1.0/UserDefinedFieldListItems` path. Vendor constraints carried into the op metadata: `dataType` and
32
+ `udfType` are immutable after creation, `isFieldMapping` is immutable (a mapped field updates only
33
+ `isActive`/`sortOrder`), list items require a unique `valueForDisplay`/`valueForExport`, a default-value
34
+ item's `valueForDisplay` is rename-locked, and the vendor caps active company UDFs at 200. Multi-select and
35
+ reference UDF types are not supported by the vendor API.
36
+ - Consumer note for `iit-mcp-autotask`: the capability-plan hash changes with this; at release, re-pin the SDK
37
+ and plan hash together and decide the tool surface for the new `autotask_userDefinedFieldDefinition_*` and
38
+ `autotask_userDefinedFieldListItem_*` tools.
39
+
10
40
  ## [0.60.1] - 2026-11-09
11
41
 
12
42
  ### Changed
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "generatedBy": "scripts/build-tool-catalog.mjs",
3
- "generatedAt": "2026-11-08T03:47:47.958Z",
4
- "planHash": "95323eaa92fca1ba1541721c6f34ce671118736aca889ea432156d87a8a8ecd8",
3
+ "generatedAt": "2026-11-11T22:57:14.052Z",
4
+ "planHash": "ccbe1f33bf20dfb0f67f994169a5e15a1be839e82703dd2f3929e7247991d3f0",
5
5
  "metaTools": [
6
6
  {
7
7
  "name": "autotask_catalog",
@@ -51,7 +51,7 @@
51
51
  {
52
52
  "name": "autotask_read",
53
53
  "title": "Read One Registry Operation (read mode)",
54
- "description": "Route an effect=read registry operation by its exact name (never fuzzy, never a tool name): the 384 field/entity/UDF-info reads (getEntityInfo/getFieldInfo/getUdfInfo) have no dedicated tool and ride this one, and any read op is routable. For field discovery use operations.fieldCatalog (compact) instead of per-resource getFieldInfo (full dump). Read-only by construction — every op it can route is effect=read (zero mutating requests), and a write or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Reads have no dry run (a read with dry_run: true is refused). Harness approval policy: approve every tool with readOnlyHint !== true (exactly 247 today); the 604 readOnlyHint: true tools — including this one — are safe ungated; the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. 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.",
54
+ "description": "Route an effect=read registry operation by its exact name (never fuzzy, never a tool name): the 390 field/entity/UDF-info reads (getEntityInfo/getFieldInfo/getUdfInfo) have no dedicated tool and ride this one, and any read op is routable. For field discovery use operations.fieldCatalog (compact) instead of per-resource getFieldInfo (full dump). Read-only by construction — every op it can route is effect=read (zero mutating requests), and a write or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Reads have no dry run (a read with dry_run: true is refused). Harness approval policy: approve every tool with readOnlyHint !== true (exactly 251 today); the 610 readOnlyHint: true tools — including this one — are safe ungated; the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. 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.",
55
55
  "input": {
56
56
  "operation": {
57
57
  "type": "string",
@@ -71,7 +71,7 @@
71
71
  {
72
72
  "name": "autotask_write",
73
73
  "title": "Write One Registry Operation (write mode)",
74
- "description": "Route an effect=write registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true — the mutating request is never issued); pass dry_run: false to apply. A read or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). The 2 approval-gated writes (configuration_items.moveConfigurationItem, contacts.moveToCompany) additionally require confirm === the operation key, in BOTH dry-run and apply mode. Harness approval policy: this tool is one of the 247 tools that require approval (readOnlyHint !== true); the 604 readOnlyHint: true tools are safe ungated, and the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. 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.",
74
+ "description": "Route an effect=write registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true — the mutating request is never issued); pass dry_run: false to apply. A read or delete op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). The 2 approval-gated writes (configuration_items.moveConfigurationItem, contacts.moveToCompany) additionally require confirm === the operation key, in BOTH dry-run and apply mode. Harness approval policy: this tool is one of the 251 tools that require approval (readOnlyHint !== true); the 610 readOnlyHint: true tools are safe ungated, and the 57 destructiveHint: true tools (56 dedicated delete tools + autotask_delete) require confirm === the operation key. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. For query/count ops args[0] is a params object (filter/limit); call autotask_describe first for the exact arg shape and filter grammar. 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.",
75
75
  "input": {
76
76
  "operation": {
77
77
  "type": "string",
@@ -101,7 +101,7 @@
101
101
  {
102
102
  "name": "autotask_delete",
103
103
  "title": "Delete One Registry Operation (delete mode)",
104
- "description": "Route an effect=destructive (delete) registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true); pass dry_run: false to apply. confirm === the operation key is REQUIRED for every delete (all 56), in BOTH dry-run and apply mode — the deliberate act is the call, not the delete. A read or write op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Harness approval policy: this tool is one of the 57 destructiveHint: true tools that require approval + confirm; approve every tool with readOnlyHint !== true (exactly 247 today); the 604 readOnlyHint: true tools are safe ungated. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. 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.",
104
+ "description": "Route an effect=destructive (delete) registry operation by its exact name (never fuzzy, never a tool name), dry-run-first: the first call always travels dry_run: true (the pinned DryRunResult envelope, simulated: true); pass dry_run: false to apply. confirm === the operation key is REQUIRED for every delete (all 56), in BOTH dry-run and apply mode — the deliberate act is the call, not the delete. A read or write op is refused BEFORE any request (cross-mode refusal; the message names the correct tool). Harness approval policy: this tool is one of the 57 destructiveHint: true tools that require approval + confirm; approve every tool with readOnlyHint !== true (exactly 251 today); the 610 readOnlyHint: true tools are safe ungated. Migration: autotask_invoke is REPLACED by autotask_read/autotask_write/autotask_delete — update harness config. 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.",
105
105
  "input": {
106
106
  "operation": {
107
107
  "type": "string",
@@ -11737,6 +11737,295 @@
11737
11737
  "reachReason": null,
11738
11738
  "boundedAlternative": null
11739
11739
  },
11740
+ {
11741
+ "operation": "user_defined_field_definitions.count",
11742
+ "core": false,
11743
+ "tool": "autotask_userDefinedFieldDefinition_count",
11744
+ "purpose": "Count user-defined field definition records matching a JSON filter.",
11745
+ "preferredWhen": null,
11746
+ "backingOperation": "user_defined_field_definitions.count",
11747
+ "effect": "read",
11748
+ "dryRunFirst": false,
11749
+ "confirm": false,
11750
+ "requiredArgs": [],
11751
+ "tier": "advanced",
11752
+ "reachable": true,
11753
+ "reach": "dedicated tool",
11754
+ "reachReason": null,
11755
+ "boundedAlternative": null
11756
+ },
11757
+ {
11758
+ "operation": "user_defined_field_definitions.create",
11759
+ "core": false,
11760
+ "tool": "autotask_userDefinedFieldDefinition_create",
11761
+ "purpose": "Create a UDF definition.",
11762
+ "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
11763
+ "backingOperation": "user_defined_field_definitions.create",
11764
+ "effect": "write",
11765
+ "dryRunFirst": true,
11766
+ "confirm": false,
11767
+ "requiredArgs": [
11768
+ "data"
11769
+ ],
11770
+ "tier": "advanced",
11771
+ "reachable": true,
11772
+ "reach": "dedicated tool",
11773
+ "reachReason": null,
11774
+ "boundedAlternative": null
11775
+ },
11776
+ {
11777
+ "operation": "user_defined_field_definitions.get",
11778
+ "core": false,
11779
+ "tool": "autotask_userDefinedFieldDefinition_get",
11780
+ "purpose": "Get one UserDefinedFieldDefinition by id.",
11781
+ "preferredWhen": "Preferred when the numeric id is already known; query by name when it is not.",
11782
+ "backingOperation": "user_defined_field_definitions.get",
11783
+ "effect": "read",
11784
+ "dryRunFirst": false,
11785
+ "confirm": false,
11786
+ "requiredArgs": [
11787
+ "id"
11788
+ ],
11789
+ "tier": "advanced",
11790
+ "reachable": true,
11791
+ "reach": "dedicated tool",
11792
+ "reachReason": null,
11793
+ "boundedAlternative": null
11794
+ },
11795
+ {
11796
+ "operation": "user_defined_field_definitions.getEntityInfo",
11797
+ "core": false,
11798
+ "tool": null,
11799
+ "purpose": "Get the UserDefinedFieldDefinition capability metadata (canCreate/canUpdate/hasUserDefinedFields/...).",
11800
+ "preferredWhen": null,
11801
+ "backingOperation": "user_defined_field_definitions.getEntityInfo",
11802
+ "effect": "read",
11803
+ "dryRunFirst": false,
11804
+ "confirm": false,
11805
+ "requiredArgs": [],
11806
+ "tier": "advanced",
11807
+ "reachable": true,
11808
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
11809
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
11810
+ "boundedAlternative": null
11811
+ },
11812
+ {
11813
+ "operation": "user_defined_field_definitions.getFieldInfo",
11814
+ "core": false,
11815
+ "tool": null,
11816
+ "purpose": "Get the UserDefinedFieldDefinition field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog).",
11817
+ "preferredWhen": null,
11818
+ "backingOperation": "user_defined_field_definitions.getFieldInfo",
11819
+ "effect": "read",
11820
+ "dryRunFirst": false,
11821
+ "confirm": false,
11822
+ "requiredArgs": [],
11823
+ "tier": "advanced",
11824
+ "reachable": true,
11825
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
11826
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
11827
+ "boundedAlternative": null
11828
+ },
11829
+ {
11830
+ "operation": "user_defined_field_definitions.getUdfInfo",
11831
+ "core": false,
11832
+ "tool": null,
11833
+ "purpose": "Get the UserDefinedFieldDefinition user-defined-field catalog.",
11834
+ "preferredWhen": null,
11835
+ "backingOperation": "user_defined_field_definitions.getUdfInfo",
11836
+ "effect": "read",
11837
+ "dryRunFirst": false,
11838
+ "confirm": false,
11839
+ "requiredArgs": [],
11840
+ "tier": "advanced",
11841
+ "reachable": true,
11842
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
11843
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
11844
+ "boundedAlternative": null
11845
+ },
11846
+ {
11847
+ "operation": "user_defined_field_definitions.query",
11848
+ "core": false,
11849
+ "tool": "autotask_userDefinedFieldDefinition_query",
11850
+ "purpose": "Query UserDefinedFieldDefinition records with a JSON filter.",
11851
+ "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
11852
+ "backingOperation": "user_defined_field_definitions.query",
11853
+ "effect": "read",
11854
+ "dryRunFirst": false,
11855
+ "confirm": false,
11856
+ "requiredArgs": [],
11857
+ "tier": "advanced",
11858
+ "reachable": true,
11859
+ "reach": "dedicated tool",
11860
+ "reachReason": null,
11861
+ "boundedAlternative": null
11862
+ },
11863
+ {
11864
+ "operation": "user_defined_field_definitions.update",
11865
+ "core": false,
11866
+ "tool": "autotask_userDefinedFieldDefinition_update",
11867
+ "purpose": "Update a UDF definition.",
11868
+ "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
11869
+ "backingOperation": "user_defined_field_definitions.update",
11870
+ "effect": "write",
11871
+ "dryRunFirst": true,
11872
+ "confirm": false,
11873
+ "requiredArgs": [
11874
+ "id",
11875
+ "data"
11876
+ ],
11877
+ "tier": "advanced",
11878
+ "reachable": true,
11879
+ "reach": "dedicated tool",
11880
+ "reachReason": null,
11881
+ "boundedAlternative": null
11882
+ },
11883
+ {
11884
+ "operation": "user_defined_field_list_items.count",
11885
+ "core": false,
11886
+ "tool": "autotask_userDefinedFieldListItem_count",
11887
+ "purpose": "Count user-defined field list item records matching a JSON filter.",
11888
+ "preferredWhen": null,
11889
+ "backingOperation": "user_defined_field_list_items.count",
11890
+ "effect": "read",
11891
+ "dryRunFirst": false,
11892
+ "confirm": false,
11893
+ "requiredArgs": [],
11894
+ "tier": "extended",
11895
+ "reachable": true,
11896
+ "reach": "dedicated tool",
11897
+ "reachReason": null,
11898
+ "boundedAlternative": null
11899
+ },
11900
+ {
11901
+ "operation": "user_defined_field_list_items.create",
11902
+ "core": false,
11903
+ "tool": "autotask_userDefinedFieldListItem_create",
11904
+ "purpose": "Create a UDF list item.",
11905
+ "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
11906
+ "backingOperation": "user_defined_field_list_items.create",
11907
+ "effect": "write",
11908
+ "dryRunFirst": true,
11909
+ "confirm": false,
11910
+ "requiredArgs": [
11911
+ "parentId",
11912
+ "data"
11913
+ ],
11914
+ "tier": "extended",
11915
+ "reachable": true,
11916
+ "reach": "dedicated tool",
11917
+ "reachReason": null,
11918
+ "boundedAlternative": null
11919
+ },
11920
+ {
11921
+ "operation": "user_defined_field_list_items.get",
11922
+ "core": false,
11923
+ "tool": "autotask_userDefinedFieldListItem_get",
11924
+ "purpose": "Get one UserDefinedFieldListItem by id.",
11925
+ "preferredWhen": "Preferred when the numeric id is known with the parent definition id; query by udfFieldId when it is not.",
11926
+ "backingOperation": "user_defined_field_list_items.get",
11927
+ "effect": "read",
11928
+ "dryRunFirst": false,
11929
+ "confirm": false,
11930
+ "requiredArgs": [
11931
+ "parentId",
11932
+ "id"
11933
+ ],
11934
+ "tier": "extended",
11935
+ "reachable": true,
11936
+ "reach": "dedicated tool",
11937
+ "reachReason": null,
11938
+ "boundedAlternative": null
11939
+ },
11940
+ {
11941
+ "operation": "user_defined_field_list_items.getEntityInfo",
11942
+ "core": false,
11943
+ "tool": null,
11944
+ "purpose": "Get the UserDefinedFieldListItem capability metadata (canCreate/canUpdate/hasUserDefinedFields/...).",
11945
+ "preferredWhen": null,
11946
+ "backingOperation": "user_defined_field_list_items.getEntityInfo",
11947
+ "effect": "read",
11948
+ "dryRunFirst": false,
11949
+ "confirm": false,
11950
+ "requiredArgs": [],
11951
+ "tier": "extended",
11952
+ "reachable": true,
11953
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
11954
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
11955
+ "boundedAlternative": null
11956
+ },
11957
+ {
11958
+ "operation": "user_defined_field_list_items.getFieldInfo",
11959
+ "core": false,
11960
+ "tool": null,
11961
+ "purpose": "Get the UserDefinedFieldListItem field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog).",
11962
+ "preferredWhen": null,
11963
+ "backingOperation": "user_defined_field_list_items.getFieldInfo",
11964
+ "effect": "read",
11965
+ "dryRunFirst": false,
11966
+ "confirm": false,
11967
+ "requiredArgs": [],
11968
+ "tier": "extended",
11969
+ "reachable": true,
11970
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
11971
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
11972
+ "boundedAlternative": null
11973
+ },
11974
+ {
11975
+ "operation": "user_defined_field_list_items.getUdfInfo",
11976
+ "core": false,
11977
+ "tool": null,
11978
+ "purpose": "Get the UserDefinedFieldListItem user-defined-field catalog.",
11979
+ "preferredWhen": null,
11980
+ "backingOperation": "user_defined_field_list_items.getUdfInfo",
11981
+ "effect": "read",
11982
+ "dryRunFirst": false,
11983
+ "confirm": false,
11984
+ "requiredArgs": [],
11985
+ "tier": "extended",
11986
+ "reachable": true,
11987
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
11988
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
11989
+ "boundedAlternative": null
11990
+ },
11991
+ {
11992
+ "operation": "user_defined_field_list_items.query",
11993
+ "core": false,
11994
+ "tool": "autotask_userDefinedFieldListItem_query",
11995
+ "purpose": "Query UserDefinedFieldListItem records with a JSON filter.",
11996
+ "preferredWhen": "Default for filtered reads (the bounded query op). queryAll is the unbounded raw walk — only when you need the ENTIRE set and accept a large payload; default to the bounded query op. Prefer an includeFields subset over the full model (field names via operations.fieldCatalog). latest: N is the latest-N rows (id-descending) when the newest rows are the goal (the vendor has no sort — count-anchored, docs/API.md §4). Prefer a hand-listed includeFields for common narrow reads (removed the closed fieldsPreset presets — the v1 billing_join field list for billing_items.query, if you need it, is: companyID, ticketID, projectID, timeEntryID, contractServiceID, contractID, billingCodeID, expenseItemID, itemDate, quantity, rate, extendedPrice, totalAmount, nonBillable); noteChars: N caps the untrusted-class free-text fields of the resource (notes/descriptions/UDF prose) to N chars each with the explicit … [+N chars truncated] marker (opt-in; the raw result when absent).",
11997
+ "backingOperation": "user_defined_field_list_items.query",
11998
+ "effect": "read",
11999
+ "dryRunFirst": false,
12000
+ "confirm": false,
12001
+ "requiredArgs": [],
12002
+ "tier": "extended",
12003
+ "reachable": true,
12004
+ "reach": "dedicated tool",
12005
+ "reachReason": null,
12006
+ "boundedAlternative": null
12007
+ },
12008
+ {
12009
+ "operation": "user_defined_field_list_items.update",
12010
+ "core": false,
12011
+ "tool": "autotask_userDefinedFieldListItem_update",
12012
+ "purpose": "Update a UDF list item.",
12013
+ "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
12014
+ "backingOperation": "user_defined_field_list_items.update",
12015
+ "effect": "write",
12016
+ "dryRunFirst": true,
12017
+ "confirm": false,
12018
+ "requiredArgs": [
12019
+ "parentId",
12020
+ "id",
12021
+ "data"
12022
+ ],
12023
+ "tier": "extended",
12024
+ "reachable": true,
12025
+ "reach": "dedicated tool",
12026
+ "reachReason": null,
12027
+ "boundedAlternative": null
12028
+ },
11740
12029
  {
11741
12030
  "operation": "version_information.get",
11742
12031
  "core": false,
@@ -22630,11 +22919,11 @@
22630
22919
  }
22631
22920
  ],
22632
22921
  "counts": {
22633
- "registryOperations": 1230,
22922
+ "registryOperations": 1246,
22634
22923
  "coreOperations": 10,
22635
- "catalogRows": 1230,
22636
- "withTool": 846,
22637
- "readModeOnly": 384,
22924
+ "catalogRows": 1246,
22925
+ "withTool": 856,
22926
+ "readModeOnly": 390,
22638
22927
  "neverExposed": 0,
22639
22928
  "metaTools": 5
22640
22929
  }
package/README.md CHANGED
@@ -342,7 +342,7 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
342
342
  governor place: `src/operations/invoke.ts`).
343
343
 
344
344
  <!-- BEGIN GENERATED:approval-policy -->
345
- **Harness approval policy (recommended).** Require approval on every tool whose MCP annotation is `readOnlyHint !== true` — today exactly **247 tools**: the 245 dedicated write/delete tools (189 `effect=write` + 56 `effect=destructive`, every one of them has a dedicated tool) + `autotask_write` + `autotask_delete`. The remaining **604 tools** (the 591 dedicated read tools + the 10 core read tools + `autotask_read` + `autotask_catalog` + `autotask_describe`) all carry `readOnlyHint: true` and are safe ungated: every op they can route is `effect=read` (zero mutating requests). Refined class for the highest-risk ops: the **57 tools with `destructiveHint: true`** (56 dedicated delete tools + `autotask_delete`) additionally require `confirm === <operation key>` even inside `autotask_delete`. The approval-gated writes (`configuration_items.moveConfigurationItem`, `contacts.moveToCompany`) require the same confirm inside `autotask_write`. Migration: `autotask_invoke` is REPLACED by `autotask_read`/`autotask_write`/`autotask_delete` — update harness config and remove any `autotask_invoke` entry. The rule is derivable from the registry `effect` column and the mode tools’ fixed annotations; it never needs a hand-maintained name list.
345
+ **Harness approval policy (recommended).** Require approval on every tool whose MCP annotation is `readOnlyHint !== true` — today exactly **251 tools**: the 249 dedicated write/delete tools (193 `effect=write` + 56 `effect=destructive`, every one of them has a dedicated tool) + `autotask_write` + `autotask_delete`. The remaining **610 tools** (the 597 dedicated read tools + the 10 core read tools + `autotask_read` + `autotask_catalog` + `autotask_describe`) all carry `readOnlyHint: true` and are safe ungated: every op they can route is `effect=read` (zero mutating requests). Refined class for the highest-risk ops: the **57 tools with `destructiveHint: true`** (56 dedicated delete tools + `autotask_delete`) additionally require `confirm === <operation key>` even inside `autotask_delete`. The approval-gated writes (`configuration_items.moveConfigurationItem`, `contacts.moveToCompany`) require the same confirm inside `autotask_write`. Migration: `autotask_invoke` is REPLACED by `autotask_read`/`autotask_write`/`autotask_delete` — update harness config and remove any `autotask_invoke` entry. The rule is derivable from the registry `effect` column and the mode tools’ fixed annotations; it never needs a hand-maintained name list.
346
346
  <!-- END GENERATED:approval-policy -->
347
347
  **Provider tool-search interop.** Hosts with provider-native tool search
348
348
  (OpenAI `type: "tool_search"` / `defer_loading`; Anthropic's tool search
@@ -375,8 +375,8 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
375
375
  LLM-facing guidance encodes — the spec-derived delete
376
376
  boundaries (`plan.deleteBoundaries`) (incl. the 7-endpoint 405 class — scratch records on those
377
377
  endpoints are API-undeletable, cleanup is UI-only), the
378
- blind count/query surfaces (companies, unfiltered billing_codes, resources
379
- — `get(id)` is the authority), the isActive-is-a-number quirk, the
378
+ blind count/query surfaces (companies, unfiltered billing_codes, the unfiltered
379
+ UDF definition / list-item counts, resources — `get(id)` is the authority), the isActive-is-a-number quirk, the
380
380
  time-entry `internalBillingCodeID` wire key, and the W-D3 posted-state
381
381
  gap on this zone's `time_entries` (the live TimeEntry entity has NO
382
382
  `postedDate`; `time_entries.dateWorkedWindow` (the single posted-state read