node-autotask 0.85.0 → 0.87.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 +13 -0
  2. package/MCP_TOOL_CATALOG.json +336 -9
  3. package/README.md +1 -1
  4. package/capabilities.json +1411 -218
  5. package/dist/capabilities-data.js +1562 -369
  6. package/dist/capabilities.cjs +4 -4
  7. package/dist/capabilities.js +1 -1
  8. package/dist/{chunk-7GNZT7Y7.cjs → chunk-CUZJJCI5.cjs} +1231 -438
  9. package/dist/{chunk-GTTAPAGP.js → chunk-EXNDYJPG.js} +3 -3
  10. package/dist/{chunk-EPJG7M5C.js → chunk-G57Q7OAC.js} +2 -2
  11. package/dist/{chunk-L6YCH2I4.js → chunk-GAFG7RHG.js} +1226 -433
  12. package/dist/{chunk-PBOH2OHJ.cjs → chunk-HUA4WB4N.cjs} +32 -30
  13. package/dist/{chunk-HF5YG4TV.js → chunk-NXSQXXNK.js} +4 -2
  14. package/dist/{chunk-JV6MX2U3.cjs → chunk-RU4ECNQN.cjs} +200 -200
  15. package/dist/{chunk-JCKYM7FD.cjs → chunk-YVNGUGG6.cjs} +3 -3
  16. package/dist/{index-rWcPjRpX.d.ts → index-CsL5gGJo.d.ts} +33 -13
  17. package/dist/{index-CCW_EpLg.d.cts → index-Cxfr_DOD.d.cts} +76 -3
  18. package/dist/{index-CCW_EpLg.d.ts → index-Cxfr_DOD.d.ts} +76 -3
  19. package/dist/{index-DkyNXWyt.d.cts → index-DGiua9uK.d.cts} +33 -13
  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 +51 -51
  25. package/dist/operations/index.d.cts +5 -20
  26. package/dist/operations/index.d.ts +5 -20
  27. package/dist/operations/index.js +2 -2
  28. package/dist/pool.cjs +12 -12
  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 +34 -17
  40. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [0.87.0] - 2026-11-20
11
+
12
+ ### Changed
13
+
14
+ - Label name reads are batched: two or more uncached ids of one record table (company, contract, ticket, role, billing code, product, CI category) now resolve through one chunked `id in` query that selects only the name fields, instead of one get per id. A lone uncached id keeps its single-record get, and so does the Line of Business contract on `tickets.fullContext` (its pointer is not a name field); staff names keep their per-id reads. The batched rows are partial records, so they are cached under a name-only key that only the label path reads, and a later full `get` of the same id still reads the wire. An id the batch does not return is reported as unreadable (`name: null`, `blind: true`, `unreadable: true` on composite name rows), never as not-found, and no not-found marker is cached: a query can be narrower than a per-id read for the API user. The default name-read budget (`DEFAULT_MAX_NAME_READS`, `maxNameReads`) rises from 20 to 50 ids per call, still counted per id; callers may lower it, never raise it. The labelled-result `names` note now gives the over-budget and unreadable counts separately. Served guidance for the composites' `maxNameReads` default changes with it, so the capability plan hash changes (#500).
15
+ - The unknown-field refusal on query and count bags lists the valid field names nearest-first (a substring or a shared meaningful name token, then a small edit distance, then a shared generic token such as `Date`, `is` or `Number`, then date fields for a date-looking name; the rest keep model order) and adds `did you mean: "<name>" -> a, b, c` (at most three) for each unknown name that has a close candidate. Generic tokens alone never make a candidate close, and a small synonym table reads `purchase` as `install`, so `purchaseDate` on configuration items suggests `installDate`. The suggestion is kept when the 3000-character rule drops the full list (#501).
16
+
17
+ ## [0.86.0] - 2026-11-20
18
+
19
+ ### Added
20
+
21
+ - Add account-wide knowledge-base category workflows and category-scoped article root create, update, and delete. Root workflows include documented reads and metadata, governed previews, and fresh identity checks. Article update and delete compare explicit stale tokens against the identity-checked snapshot, and publish values use fresh metadata. Knowledge-base record and receipt IDs above JavaScript’s safe integer range are returned as decimal strings. Hidden drafts and Global Articles remain outside the public API. Article content is tracked separately (#466, #464).
22
+
10
23
  ## [0.85.0] - 2026-11-20
11
24
 
12
25
  ### Added
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "generatedBy": "scripts/build-tool-catalog.mjs",
3
- "generatedAt": "2026-11-20T05:02:15.646Z",
4
- "planHash": "9521525945b1306da363ce5fb38649e17c5526f2c0842da64c3bec7993e62735",
3
+ "generatedAt": "2026-11-20T11:02:15.393Z",
4
+ "planHash": "c97deac4ac7c3ca9ce4cea10ac6a50bb19b6517993d9657c52397964e1fcf715",
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 432 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 283 today); the 665 readOnlyHint: true tools — including this one — are safe ungated; the 70 destructiveHint: true tools (69 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 438 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 289 today); the 671 readOnlyHint: true tools — including this one — are safe ungated; the 72 destructiveHint: true tools (71 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 283 tools that require approval (readOnlyHint !== true); the 665 readOnlyHint: true tools are safe ungated, and the 70 destructiveHint: true tools (69 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 289 tools that require approval (readOnlyHint !== true); the 671 readOnlyHint: true tools are safe ungated, and the 72 destructiveHint: true tools (71 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 69), 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 70 destructiveHint: true tools that require approval + confirm; approve every tool with readOnlyHint !== true (exactly 283 today); the 665 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 71), 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 72 destructiveHint: true tools that require approval + confirm; approve every tool with readOnlyHint !== true (exactly 289 today); the 671 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",
@@ -5306,6 +5306,333 @@
5306
5306
  "reachReason": null,
5307
5307
  "boundedAlternative": null
5308
5308
  },
5309
+ {
5310
+ "operation": "knowledge_base_articles.count",
5311
+ "core": false,
5312
+ "tool": "autotask_knowledgeBaseArticle_count",
5313
+ "purpose": "Count KnowledgeBaseArticle records matching a JSON filter.",
5314
+ "preferredWhen": null,
5315
+ "backingOperation": "knowledge_base_articles.count",
5316
+ "effect": "read",
5317
+ "dryRunFirst": false,
5318
+ "confirm": false,
5319
+ "requiredArgs": [],
5320
+ "tier": "extended",
5321
+ "reachable": true,
5322
+ "reach": "dedicated tool",
5323
+ "reachReason": null,
5324
+ "boundedAlternative": null
5325
+ },
5326
+ {
5327
+ "operation": "knowledge_base_articles.create",
5328
+ "core": false,
5329
+ "tool": "autotask_knowledgeBaseArticle_create",
5330
+ "purpose": "create article root records.",
5331
+ "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
5332
+ "backingOperation": "knowledge_base_articles.create",
5333
+ "effect": "write",
5334
+ "dryRunFirst": true,
5335
+ "confirm": false,
5336
+ "requiredArgs": [
5337
+ "parentId",
5338
+ "data"
5339
+ ],
5340
+ "tier": "extended",
5341
+ "reachable": true,
5342
+ "reach": "dedicated tool",
5343
+ "reachReason": null,
5344
+ "boundedAlternative": null
5345
+ },
5346
+ {
5347
+ "operation": "knowledge_base_articles.delete",
5348
+ "core": false,
5349
+ "tool": "autotask_knowledgeBaseArticle_delete",
5350
+ "purpose": "delete article root records.",
5351
+ "preferredWhen": null,
5352
+ "backingOperation": "knowledge_base_articles.delete",
5353
+ "effect": "destructive",
5354
+ "dryRunFirst": true,
5355
+ "confirm": true,
5356
+ "requiredArgs": [
5357
+ "parentId",
5358
+ "id"
5359
+ ],
5360
+ "tier": "extended",
5361
+ "reachable": true,
5362
+ "reach": "dedicated tool",
5363
+ "reachReason": null,
5364
+ "boundedAlternative": null
5365
+ },
5366
+ {
5367
+ "operation": "knowledge_base_articles.get",
5368
+ "core": false,
5369
+ "tool": "autotask_knowledgeBaseArticle_get",
5370
+ "purpose": "get article root records.",
5371
+ "preferredWhen": "Preferred when the numeric id is already known.",
5372
+ "backingOperation": "knowledge_base_articles.get",
5373
+ "effect": "read",
5374
+ "dryRunFirst": false,
5375
+ "confirm": false,
5376
+ "requiredArgs": [
5377
+ "id"
5378
+ ],
5379
+ "tier": "extended",
5380
+ "reachable": true,
5381
+ "reach": "dedicated tool",
5382
+ "reachReason": null,
5383
+ "boundedAlternative": null
5384
+ },
5385
+ {
5386
+ "operation": "knowledge_base_articles.getEntityInfo",
5387
+ "core": false,
5388
+ "tool": null,
5389
+ "purpose": "Get the KnowledgeBaseArticle capability metadata (canCreate/canUpdate/hasUserDefinedFields/...).",
5390
+ "preferredWhen": "Can access Knowledgebase permission is required; mutations additionally require the corresponding Add/Edit/Delete Articles permission. Only the latest published version is visible, and API creation publishes an article. Hidden drafts and approval state are not exposed and can cause a vendor refusal after a valid preview. Global root routes do not expose the separate vendor Global Articles feature. Article roots have no company ownership. Content uses separate child APIs (K2); content, UDF and audit-field writes are unsupported. Empty reads do not establish tenant-wide absence.",
5391
+ "backingOperation": "knowledge_base_articles.getEntityInfo",
5392
+ "effect": "read",
5393
+ "dryRunFirst": false,
5394
+ "confirm": false,
5395
+ "requiredArgs": [],
5396
+ "tier": "extended",
5397
+ "reachable": true,
5398
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
5399
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
5400
+ "boundedAlternative": null
5401
+ },
5402
+ {
5403
+ "operation": "knowledge_base_articles.getFieldInfo",
5404
+ "core": false,
5405
+ "tool": null,
5406
+ "purpose": "Get the KnowledgeBaseArticle field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog).",
5407
+ "preferredWhen": "Can access Knowledgebase permission is required; mutations additionally require the corresponding Add/Edit/Delete Articles permission. Only the latest published version is visible, and API creation publishes an article. Hidden drafts and approval state are not exposed and can cause a vendor refusal after a valid preview. Global root routes do not expose the separate vendor Global Articles feature. Article roots have no company ownership. Content uses separate child APIs (K2); content, UDF and audit-field writes are unsupported. Empty reads do not establish tenant-wide absence. Inspect current active publish picklist values before writes; metadata is not proof of permission or draft visibility.",
5408
+ "backingOperation": "knowledge_base_articles.getFieldInfo",
5409
+ "effect": "read",
5410
+ "dryRunFirst": false,
5411
+ "confirm": false,
5412
+ "requiredArgs": [],
5413
+ "tier": "extended",
5414
+ "reachable": true,
5415
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
5416
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
5417
+ "boundedAlternative": null
5418
+ },
5419
+ {
5420
+ "operation": "knowledge_base_articles.getUdfInfo",
5421
+ "core": false,
5422
+ "tool": null,
5423
+ "purpose": "Get the KnowledgeBaseArticle user-defined-field catalog.",
5424
+ "preferredWhen": "Can access Knowledgebase permission is required; mutations additionally require the corresponding Add/Edit/Delete Articles permission. Only the latest published version is visible, and API creation publishes an article. Hidden drafts and approval state are not exposed and can cause a vendor refusal after a valid preview. Global root routes do not expose the separate vendor Global Articles feature. Article roots have no company ownership. Content uses separate child APIs (K2); content, UDF and audit-field writes are unsupported. Empty reads do not establish tenant-wide absence.",
5425
+ "backingOperation": "knowledge_base_articles.getUdfInfo",
5426
+ "effect": "read",
5427
+ "dryRunFirst": false,
5428
+ "confirm": false,
5429
+ "requiredArgs": [],
5430
+ "tier": "extended",
5431
+ "reachable": true,
5432
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
5433
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
5434
+ "boundedAlternative": null
5435
+ },
5436
+ {
5437
+ "operation": "knowledge_base_articles.query",
5438
+ "core": false,
5439
+ "tool": "autotask_knowledgeBaseArticle_query",
5440
+ "purpose": "Query KnowledgeBaseArticle records with a JSON filter.",
5441
+ "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).",
5442
+ "backingOperation": "knowledge_base_articles.query",
5443
+ "effect": "read",
5444
+ "dryRunFirst": false,
5445
+ "confirm": false,
5446
+ "requiredArgs": [],
5447
+ "tier": "extended",
5448
+ "reachable": true,
5449
+ "reach": "dedicated tool",
5450
+ "reachReason": null,
5451
+ "boundedAlternative": null
5452
+ },
5453
+ {
5454
+ "operation": "knowledge_base_articles.update",
5455
+ "core": false,
5456
+ "tool": "autotask_knowledgeBaseArticle_update",
5457
+ "purpose": "update article root records.",
5458
+ "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
5459
+ "backingOperation": "knowledge_base_articles.update",
5460
+ "effect": "write",
5461
+ "dryRunFirst": true,
5462
+ "confirm": false,
5463
+ "requiredArgs": [
5464
+ "parentId",
5465
+ "id",
5466
+ "data"
5467
+ ],
5468
+ "tier": "extended",
5469
+ "reachable": true,
5470
+ "reach": "dedicated tool",
5471
+ "reachReason": null,
5472
+ "boundedAlternative": null
5473
+ },
5474
+ {
5475
+ "operation": "knowledge_base_categories.count",
5476
+ "core": false,
5477
+ "tool": "autotask_knowledgeBaseCategory_count",
5478
+ "purpose": "Count knowledgebase categories.",
5479
+ "preferredWhen": null,
5480
+ "backingOperation": "knowledge_base_categories.count",
5481
+ "effect": "read",
5482
+ "dryRunFirst": false,
5483
+ "confirm": false,
5484
+ "requiredArgs": [],
5485
+ "tier": "extended",
5486
+ "reachable": true,
5487
+ "reach": "dedicated tool",
5488
+ "reachReason": null,
5489
+ "boundedAlternative": null
5490
+ },
5491
+ {
5492
+ "operation": "knowledge_base_categories.create",
5493
+ "core": false,
5494
+ "tool": "autotask_knowledgeBaseCategory_create",
5495
+ "purpose": "Create a knowledgebase category.",
5496
+ "preferredWhen": "Only for a record that does not exist yet; prefer update for an id you already have.",
5497
+ "backingOperation": "knowledge_base_categories.create",
5498
+ "effect": "write",
5499
+ "dryRunFirst": true,
5500
+ "confirm": false,
5501
+ "requiredArgs": [
5502
+ "data"
5503
+ ],
5504
+ "tier": "extended",
5505
+ "reachable": true,
5506
+ "reach": "dedicated tool",
5507
+ "reachReason": null,
5508
+ "boundedAlternative": null
5509
+ },
5510
+ {
5511
+ "operation": "knowledge_base_categories.delete",
5512
+ "core": false,
5513
+ "tool": "autotask_knowledgeBaseCategory_delete",
5514
+ "purpose": "Delete a knowledgebase category.",
5515
+ "preferredWhen": null,
5516
+ "backingOperation": "knowledge_base_categories.delete",
5517
+ "effect": "destructive",
5518
+ "dryRunFirst": true,
5519
+ "confirm": true,
5520
+ "requiredArgs": [
5521
+ "id"
5522
+ ],
5523
+ "tier": "extended",
5524
+ "reachable": true,
5525
+ "reach": "dedicated tool",
5526
+ "reachReason": null,
5527
+ "boundedAlternative": null
5528
+ },
5529
+ {
5530
+ "operation": "knowledge_base_categories.get",
5531
+ "core": false,
5532
+ "tool": "autotask_knowledgeBaseCategory_get",
5533
+ "purpose": "Read a knowledgebase category.",
5534
+ "preferredWhen": "Preferred when the numeric id is already known.",
5535
+ "backingOperation": "knowledge_base_categories.get",
5536
+ "effect": "read",
5537
+ "dryRunFirst": false,
5538
+ "confirm": false,
5539
+ "requiredArgs": [
5540
+ "id"
5541
+ ],
5542
+ "tier": "extended",
5543
+ "reachable": true,
5544
+ "reach": "dedicated tool",
5545
+ "reachReason": null,
5546
+ "boundedAlternative": null
5547
+ },
5548
+ {
5549
+ "operation": "knowledge_base_categories.getEntityInfo",
5550
+ "core": false,
5551
+ "tool": null,
5552
+ "purpose": "Read knowledgebase-category capability metadata.",
5553
+ "preferredWhen": null,
5554
+ "backingOperation": "knowledge_base_categories.getEntityInfo",
5555
+ "effect": "read",
5556
+ "dryRunFirst": false,
5557
+ "confirm": false,
5558
+ "requiredArgs": [],
5559
+ "tier": "extended",
5560
+ "reachable": true,
5561
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
5562
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
5563
+ "boundedAlternative": null
5564
+ },
5565
+ {
5566
+ "operation": "knowledge_base_categories.getFieldInfo",
5567
+ "core": false,
5568
+ "tool": null,
5569
+ "purpose": "Get the KnowledgeBaseCategory field catalog (types, picklists, required, maxLength) — the full raw field dump (the largest read of the info trio; compact discovery: operations.fieldCatalog).",
5570
+ "preferredWhen": null,
5571
+ "backingOperation": "knowledge_base_categories.getFieldInfo",
5572
+ "effect": "read",
5573
+ "dryRunFirst": false,
5574
+ "confirm": false,
5575
+ "requiredArgs": [],
5576
+ "tier": "extended",
5577
+ "reachable": true,
5578
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
5579
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
5580
+ "boundedAlternative": null
5581
+ },
5582
+ {
5583
+ "operation": "knowledge_base_categories.getUdfInfo",
5584
+ "core": false,
5585
+ "tool": null,
5586
+ "purpose": "Read the specified knowledgebase-category UDF metadata route; no UDF writes are supported.",
5587
+ "preferredWhen": null,
5588
+ "backingOperation": "knowledge_base_categories.getUdfInfo",
5589
+ "effect": "read",
5590
+ "dryRunFirst": false,
5591
+ "confirm": false,
5592
+ "requiredArgs": [],
5593
+ "tier": "extended",
5594
+ "reachable": true,
5595
+ "reach": "autotask_read (exact operation name; effect=read — read-only; zero mutating requests)",
5596
+ "reachReason": "no dedicated tool — the op is still discoverable and invocable by exact name",
5597
+ "boundedAlternative": null
5598
+ },
5599
+ {
5600
+ "operation": "knowledge_base_categories.query",
5601
+ "core": false,
5602
+ "tool": "autotask_knowledgeBaseCategory_query",
5603
+ "purpose": "Query knowledgebase categories.",
5604
+ "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).",
5605
+ "backingOperation": "knowledge_base_categories.query",
5606
+ "effect": "read",
5607
+ "dryRunFirst": false,
5608
+ "confirm": false,
5609
+ "requiredArgs": [],
5610
+ "tier": "extended",
5611
+ "reachable": true,
5612
+ "reach": "dedicated tool",
5613
+ "reachReason": null,
5614
+ "boundedAlternative": null
5615
+ },
5616
+ {
5617
+ "operation": "knowledge_base_categories.update",
5618
+ "core": false,
5619
+ "tool": "autotask_knowledgeBaseCategory_update",
5620
+ "purpose": "Update a knowledgebase category.",
5621
+ "preferredWhen": "Preferred over create or delete when the record exists and only some fields change.",
5622
+ "backingOperation": "knowledge_base_categories.update",
5623
+ "effect": "write",
5624
+ "dryRunFirst": true,
5625
+ "confirm": false,
5626
+ "requiredArgs": [
5627
+ "id",
5628
+ "data"
5629
+ ],
5630
+ "tier": "extended",
5631
+ "reachable": true,
5632
+ "reach": "dedicated tool",
5633
+ "reachReason": null,
5634
+ "boundedAlternative": null
5635
+ },
5309
5636
  {
5310
5637
  "operation": "modules.get",
5311
5638
  "core": false,
@@ -25263,11 +25590,11 @@
25263
25590
  }
25264
25591
  ],
25265
25592
  "counts": {
25266
- "registryOperations": 1375,
25593
+ "registryOperations": 1393,
25267
25594
  "coreOperations": 10,
25268
- "catalogRows": 1375,
25269
- "withTool": 943,
25270
- "readModeOnly": 432,
25595
+ "catalogRows": 1393,
25596
+ "withTool": 955,
25597
+ "readModeOnly": 438,
25271
25598
  "neverExposed": 0,
25272
25599
  "metaTools": 5
25273
25600
  }
package/README.md CHANGED
@@ -389,7 +389,7 @@ The SDK ships the mechanical substrate, not a server (no MCP imports, no zod):
389
389
  governor place: `src/operations/invoke.ts`).
390
390
 
391
391
  <!-- BEGIN GENERATED:approval-policy -->
392
- **Harness approval policy (recommended).** Require approval on every tool whose MCP annotation is `readOnlyHint !== true` — today exactly **283 tools**: the 281 dedicated write/delete tools (212 `effect=write` + 69 `effect=destructive`, every one of them has a dedicated tool) + `autotask_write` + `autotask_delete`. The remaining **665 tools** (the 652 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 **70 tools with `destructiveHint: true`** (69 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.
392
+ **Harness approval policy (recommended).** Require approval on every tool whose MCP annotation is `readOnlyHint !== true` — today exactly **289 tools**: the 287 dedicated write/delete tools (216 `effect=write` + 71 `effect=destructive`, every one of them has a dedicated tool) + `autotask_write` + `autotask_delete`. The remaining **671 tools** (the 658 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 **72 tools with `destructiveHint: true`** (71 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.
393
393
  <!-- END GENERATED:approval-policy -->
394
394
  **Provider tool-search interop.** Hosts with provider-native tool search
395
395
  (OpenAI `type: "tool_search"` / `defer_loading`; Anthropic's tool search