fixup! docs: vowTools

packages/vow/README.md

@@ -101,17 +101,17 @@ export const start = async (zcf, privateArgs, baggage) => {
 ### Available Tools
 
 #### `when(vowOrPromise)`
-Waits for a Vow or Promise to resolve and returns its value.  It can't handle disconnections due to vat upgrades.
+Returns a Promise for the fulfillment of the very end of the `vowOrPromise` chain.  It can retry disconnections due to upgrades of other vats, but cannot survive the upgrade of the calling vat.
 
 #### `watch(promiseOrVow, [watcher], [context])`
 Watch a Vow and optionally provide a `watcher` with `onFulfilled`/`onRejected` handlers and a `context` value for the handlers. When handlers are not provided the fulfillment or rejection will simply pass through.
 
-Also converts a Promise into a Vow which can survive vat upgrades.
+It also registers pending Promises, so if the current vat is upgraded, the watcher is rejected because the Promise was lost when the heap was reset.
 
-#### `all(arrayOfVowsOrPassables, [watcher], [context])`
-Vow-tolerant implementation of Promise.all that takes an iterable of vows and other Passables and returns a single Vow.  It resolves with an array of values when all of the input's promises or vows are fulfilled and rejects when any of the input's promises or vows are rejected with the first rejection reason.
+#### `all(arrayOfPassables, [watcher], [context])`
+Vow-tolerant implementation of Promise.all that takes an iterable of vows and other Passables and returns a single Vow.  It resolves with an array of values when all of the input's promises or vows are fulfilled and rejects with the first rejection reason when any of the input's promises or vows are rejected.
 
-#### `allSettled(arrayOfVowsOrPassables, [watcher], [context])`
+#### `allSettled(arrayOfPassables, [watcher], [context])`
 Vow-tolerant implementation of Promise.allSettled that takes an iterable of vows and other Passables and returns a single Vow.  It resolves when all of the input's promises or vows are settled with an array of settled outcome objects.
 
 #### `asVow(fn)`